Introduction

Sugarbot uses native Python code for its scriping. This makes the scripting engine simple, and allows developers to jump right in.

Script Files

Script files are simply normal Python files, with two special definitions:

• sugarActivityName must be defined, holding the name of the activity to be launched.
• Ex: sugarActivityName = 'Terminal'
• A function named sugarbot_main must be defined. It takes one argument, a dictionary of wrapped widget objects.
• Ex: def sugarbot_main(widgets): ...

Example Scripts

Two example scripts are provided, script_calculate.py and script_terminal.py.

Widget naming

Ideally, each widget that needs manipulation should be named by calling gtk.Widget.set_name(). However, in the event that a Widget is not properly named, sugarbot attempts to find a name for the widget. Every widget that is identified is written to the log (level DEBUG).

1219012631.000382 DEBUG sbGUI: Tracking widget id 147899052 by identifier sugarbot Activity
1219012631.874240 DEBUG sbGUI: Tracking widget id 147899372 by identifier Share with:
1219012631.904340 DEBUG sbGUI: Tracking widget id 147899772 by identifier Keep
1219012631.963212 DEBUG sbGUI: Tracking widget id 147922052 by identifier x2
1219012631.965442 DEBUG sbGUI: Tracking widget id 147922172 by identifier √x
1219012631.981071 DEBUG sbGUI: Tracking widget id 147946508 by identifier sin
1219012631.983531 DEBUG sbGUI: Tracking widget id 147946788 by identifier cos
1219012631.985861 DEBUG sbGUI: Tracking widget id 147957316 by identifier tan

Manipulating Widgets

Widget manipulation has been greatly simplified due to several convenience properties. In order to implement these accessors, the widget objects have been wrapped by another class. In order to access a widget with a given name (which is set by gtk.widget.set_name or heuristically determined at run-time), simply subscript the widget dictionary.

def sugarbot_main(widgets):
  myWidget = widgets['SomeWidget']

Accessing the gtk.Widget object

The actual gtk.Widget object for the given widget is available via the widget attribiute (e.g. widgets['x'].widget).

Convenience Properties

The convenience properties allow quick and easy access to simple, common widget attributes and functions.

Text, Label, Title

Returns the text contained by the Widget. If the widget does not have any text, it attempts to fetch the label, title, or other information about the widget that may be used in lieu of text.

Example:

assert widget['entryBox'].text == 'Some text' 
widget['entryBox'].text = 'Some other text'

Note: The text attribute will first attempt to get any text contained by the Widget, then attempt to get the title or label if the widget cannot contain text. The title and label attributes will only attempt to get the title and label.

Click

Simulates a user click.

Example: widgets['A Button'].click()

Selected

Chooses an item from a gtk.ComboBox or sugar.graphics.ToolComboBox.

Example:

assert widgets['Share with:'].selected == "Private"
widgets['Share with:'].selected = "My Neighborhood"
assert widgets['Share with:'].selected == "My Neighborhood" 

typeText, delete, backspace

Simulates a user typing or deleting text at the cursor insertion place.

Example:

widget['editBox'].typeText('blah') 
widget['editBox'].backspace()
assert widget['editBox'].text == "bla"