Important: This tutorial is for the Tux Gadget Maker included in the tuxsetup1.2beta. If you want to use the Gadget Maker please upgrade your software to this version.

Also important: Both the Gadget Manager and Gadget Maker use the gadget framework which cannot run multiple instances at the same time. Meaning, when using the Gadget Maker make sure the Gadget Manager is NOT running and vice versa.

1.1 Creating a new gadget

• Start the Tux Gadget Maker from the desktop menu in Applications > Programming > Tux Gadget Maker.

• Once the program is launched, select "New TGF file" from the "Files" menu.
• Enter the new gadget name: "hello_world.tgf" and save it. After saving the tgf file, it is automatically opened in the Gadget Maker.

1.2 Adding gadget information

We are going to define the system name and add additional gadget information about our new gadget.

In the "About" tab you enter the following in the text fields:

Next, save the changes in the tgf file by selecting Files > Save as TGF file in the menu.

1.3 Defining the localized gadget name

The localized gadget name is the name that will displayed in the Gadget Manager and the gadget window. The gadget framework has multi-language support, meaning for every language another gadget name can be specified.

We will do this for the English language.

• Click the "Strings" tab. Here you can specify the localized name for your gadget.
• Select "<en_us> English United States" in the "language" list.
• In the "Strings" list, select "name_to_read", on the right of the list the "Name" and "Value" will be displayed for "name_to_read"
• In the "Value" text field, replace "Template" with "Hello world"
• Click the "Modify" button to update the changes.
  

From this point the localized name for US English has been defined. Execute the gadget by selecting Files > Execute in the menu.

Both the gadget window and settings window will be displayed with the updated name.

1.4 Making Tux Droid talk

Here we will add a function to our gadget making Tux say something.

• First select in the menu Files > Stop to make the gadget stop.
  

• Next, select the "Codes" tab.
• Select the entry "/Scripts/Python/main.pyp" in the "Commons" list. The source code main.pyp is responsible for the "voiceget" side of the gadget. Meaning it represents the Text-To-Speech service.
• Click the "edit" button to view the selected code with gedit.

• Add the following line to the code:
  

  tux.tts.speak('Hello world! How are you?')

• Save the edited code and execute the gadget.
• When pushing the "ok" button on the remote control Tux will say the gadget's localized name. Next you will hear and interface sound as used in the Gadget Manager. And after that Tux will say the Text-To-Speech message we just added to the code.
  

1.5 Testing the gadget in the Gadget Manager

Now lets try the hello world gadget for real:

• Stop the gadget (in the menu: File > Stop) and save our changes (in the menu Files > Save as TGF file).
  

• Close the Gadget Maker and start the Gadget Manager
• Locate your new Hello_world.tgf file and drag and drop it into the Gadget Manager.
• The gadget should be added below in the gadget list. From here you can select it with the remote control and start it. Or use the right-click menu and select "Run".
• Also when, selecting the "About" in the right click menu of our gadget you see the information we added at the start of this tutorial.
  

1.6 Adding multi-language support

This part explains how to add support for a second language (French in our example) to the hello world gadget. First we will translate the localized gadget name and next translate the Text-To-Speech message.

1.6.1 Localized gadget name

• Close the Gadget Manager and start the Gadget Maker again.
• Select "Files > Open a TGF file" to load the hello world gadget.
• Go to the the "Strings" tab and select "<FR_ALL> French" in the "Language" list.
• Look for the "name_to_read" entry in the "Strings" list and select it.
• Replace "Template" in the "Value" field on the right with "Salut monde"
• To finish, click on the "Modify" button and the translation is done.

1.6.2 TTS message "Hello world! How are you!"

• Select "<en_US> English United States
• In the text fields on the right side, enter "voiceget_text1" in the "Name" field and "Hello world! How are you?" in the "Value" field.
• Next, click the "Add" button.

• Now, for the French version: Select "<fr_ALL> French" in the language list.
• For voiceget_text1, change the "Value" text field with the French translation: "Salut tout le monde! Comment allez vous?"
• Finish the translation by clicking the "Modify" button.
  
  

The TTS message is now available in the gadget's source code. Now we have to update the code for main.pyp:

• Go to the "Codes" tab
• Select main.pyp and click the "Edit" button.
• In the text editor, replace:

tux.tts.speak('Hello world! How are you?")

with:

tux.tts.speak(_me.string('voiceget_text1'))

• Save the edited code and close gedit. Also store the changes of our gadget by selecting "Save as TGF file" from the menu.
  
  

Notice the _me part in the above command. This word actually represents our gadget, a bit like self in a class.

Our gadget now supports French and US English. Be careful though, you cannot not test the multi-language support from the Gadget Maker. The reason: there is no interface to switch to a different language. So the only way to test the gadget is to re-install it in the Gadget Manager.

Another note: If the Gadget Manager is configured in a language that is not supported by your gadget, US English will be used by default.

For reference you can download the hello world gadget here.

1. Gadget creation

Like in the previous tutorial we are going to create the new gadget and define the gadget information:

• Create a new TGF file by selecting "Create new TGF file" from the menu
• When prompted for a name enter "Clipboard" and save it.
  

• In the "About" tab:
• Name: "Clipboard"
• Author: "Your name"
• Version: "0.0.1"
• Description: "Clipboard tutorial gadget for Tux Droid."
• In the "Strings" tab:
• name_to_read: in English "Clipboard" and for French "Presse papier". Don't forget to use the "Modify" button every time to store the changes.
  

2. Declaring the variables and shared functions

• Select the "Codes" tab and open the init.pyp file, by selecting it in the list and clicking the "Edit" button.
  
• To create shared variables (called parameters in the gadgets) we use the _me.set_param() object in the gadget:

_me.set_param('last_text',")
_me.set_param('current_text',")

• We will need both parameters to compare the clipboard text which already has been read and the text that hasn't been read. Both parameters are initialized with a string of empty characters. The next variable is a Clipboard object from the GTK library.

clipboard = gtk.clipboard_get(gtk.gdk.SELECTION_CLIPBOARD)
_me.set_param('clipboard', clipboard)

• Now we are going to create two functions. One to check the contents of the clipboard and the other one to check if the content is text.

def clipboard_accepted_text(clipboard, text, data):
    if not text or text == ":
        return
    _me.set_param('current_text', text)
    return
def clipboard_find_info():
    gtk.gdk.threads_enter()
    _me.get_param('clipboard').request_text(_me.get_funct('clipboard_accepted_text'))
    gtk.gdk.threads_leave()
    return True

Notice we are using threads_enter() and threads_leave() in the second function. Those functions are required to use GTK in a thread. Later on the clipboard_find_info() function will be used by the gadget notification system working in a concurrent thread. Do the test by removing the protections and you will see the result.

• Now the functions are declared, we need to register them in the gadget to make them available in every gadget code part. To do this, we are using the _me.insert_funct() method.

_me.insert_funct('clipboard_accepted_text', clipboard_accepted_text)
_me.insert_funct('clipboard_find_info', clipboard_find_info)

Below you see the completed init.pyp code with added remarks:

# ----------------------------------------------------------------------------
# Definition and initialization of the shared parameters
# ----------------------------------------------------------------------------
# Set a shared parameter for saving the last spoken text
_me.set_param('last_text', "")
# Set a shared parameter for saving the current clipboard text
_me.set_param('current_text', "")
# Create a gtk clipboard object
gtk.gdk.threads_enter()
clipboard = gtk.clipboard_get(gtk.gdk.SELECTION_CLIPBOARD)
gtk.gdk.threads_leave()
# Set a shared parameter with the clipboard object
_me.set_param('clipboard', clipboard)

# ----------------------------------------------------------------------------
# Definition of the shared functions
# ----------------------------------------------------------------------------
def clipboard_accepted_text(clipboard, text, data):
    if not text or text == '':
        return
    _me.set_param('current_text', text)
    return

def clipboard_find_info():
    gtk.gdk.threads_enter()
    _me.get_param('clipboard').request_text(_me.get_funct('clipboard_accepted_text'))
    gtk.gdk.threads_leave()
    return True

# ----------------------------------------------------------------------------
# Initialization and finalization functions
# ----------------------------------------------------------------------------
def initialization():
    """
    Function to initialize the gadget. This function is executed when all gadgets
    has been loaded.
    """
    pass
    
def finalization():
    """
    Function to finalize the gadget. This function is executed when the gadget is 
    destroyed.
    """
    pass

# ----------------------------------------------------------------------------
# Registeration of the shared functions
# ----------------------------------------------------------------------------
_me.insert_funct('initialization', initialization)
_me.insert_funct('finalization', finalization)
    
_me.insert_funct('clipboard_accepted_text', clipboard_accepted_text)
_me.insert_funct('clipboard_find_info', clipboard_find_info)

3. Notification

The notification is a crucial part of this gadget. It will verify regularly a condition, and execute an action in case the condition is met.

In our gadget the verification will be "Is there new text in the clipboard?" and the action will be "Read the new text."

• Now select the "Codes" tab and edit the notify.pyp file. Two function are already present in the source code: notify_checker and notify_actuator.
• Enter the following lines of code under notify_checker:

_me.get_funct('clipboard_find_info')()
if _me.get_param('last_text') != _me.get_param('current_text'):
    _me.set_param('last_text', _me.get_param('current_text'))
    return True
else:
    return False

_me.get_funct('clipboard_find_info')() executes the declared function in init.pyp and will search for the last selected text in the clipboard. Next, we verify if the text in the clipboard is the same as the one already read.

• In the notify_actuator function: Remove the line with pass and add the following lines of code:
  

tux.event.on_head_bt_pushed = tux.tts.stop
text = _me.get_param('last_text')
tux.tts.select_voice(get_language_voice(text), 100)
tux.tts.speak(text)

tux.event.on_head_bt_pushed = tux.tts.stop  is the command to make the Text-To-Speech stop when pushing the head button of Tux. Next, the text to be read is retrieved and we select the Text-To-Speech voice according to the language of the clipboard text. And finally, the text is read with the Text-To-Speech.

The completed code for notify.pyp should look like this:

def notify_checker():
    """
    Checker function to start in the notification system.
    This function is executed in a loop. The duration between 2 loops is defined in the
    'notify_delay' setting.
    """
    _me.get_funct('clipboard_find_info')()
    if _me.get_param('last_text') != _me.get_param('current_text'):
        _me.set_param('last_text', _me.get_param('current_text'))
        return True
    else:
        return False

def notify_actuator():
    """
    If the 'notify_checker' function returns True, this function is executed with a high
    priority.
    """
    tux.event.on_head_bt_pushed = tux.tts.stop
    text = _me.get_param('last_text')
    tux.tts.select_voice(get_language_voice(text), 100)
    tux.tts.speak(text)

• Now save the code and close gedit.
• To configure the frequency to verify the clipboard content:
• Select the "Settings" tab and select the "notify_delay" entry in the "General" list.
• Change the value to 1 instead of 60 seconds.
• Click the "Modify" button to update the change.
  

This completes our second gadget. Save the gadget, close the Gadget Maker and try it out in the Gadget Manager.

For reference; get the completed clipboard gadget here.