Development Team/Almanac/sugar.graphics.toolbutton

  Development Team/Almanac

  For Developers: almanac · api · bugs · gitorious · cgit · download · people · OLPC: wiki · activities · trac · cgit · build index · repository · firmware · Fedora: packages

Class: ToolButton (gtk.ToolButton)

Sugar tool buttons can be added to toolbars and used to control various activity processes. Some common tool button tasks are outlined below.

How do I create my own custom tool button?

There are several steps you need to follow in order to create a tool button:

1. Import the ToolButton class from the sugar.graphics.toolbutton package.
2. If you intend to have an icon for your tool button, then create an "icons" directory in your activity directory and put the icon (which is a .svg file) in to that directory. For example, the code below uses an icon called "edit-custom" that accesses an edit-custom.svg file saved in the icons directory for the activity. Here is a link with information on how to create the svg files you will need: Making_Sugar_Icons
3. Use the code below to guide you on how to then create your button programmatically and add it to a tool bar (we add it to an EditToolbar object that was presumably created already in our code).

       from sugar.graphics.toolbutton import ToolButton
       ...
       #### CUSTOM TOOL BUTTON  
       #Create a custom tool button and add it to the edit toolbar
       customButton = ToolButton('edit-custom')
       customButton.set_tooltip(_('Custom'))
       self._edit_toolbar.insert(customButton, -1)
       customButton.show()

How do I connect my tool button to a callback?

The following code fragment connects a button to a callback ...

       #When the customButton fires a "clicked" event, call self._custom_clicked_cb
       customButton.connect('clicked', self._custom_clicked_cb)

... which is then defined elsewhere in the class.

   #CALLBACK METHOD
   def _custom_clicked_cb(self, widget):
       #Begin any callback code here

What is a tooltip and how do I set it for my tool button?

A tooltip is a brief textual description of a tool button that pops up when the mouse cursor is on the toolbutton and the user right-clicks. It is meant to be descriptive so that a user understands what a toolbutton does if it isn't immediately obvious from the icon. (Note that in the example below, the gettext syntax is used so that the tooltip will be included in the POT file for the project and thus it can be localized.)

     #Set the tooltip for the customButton to "Custom"
     customButton.set_tooltip(_('Custom'))

How do I reset the icon displayed for my tool button?

Your first argument to the constructor for the ToolButton class will set the initial icon used for your tool button. If you decide to change your tool button's icon later, then you must get a handle on the tool button object and do the following:

       #Reset the icon displayed for customButton
       customButton.set_icon("edit-custom");

How do I add a keyboard shortcut to my tool button?

In the example below, we add the Ctrl-b short cut to our custom button. (Activity authors are encouraged to use <ctrl> for most shortcuts.)

       #Add keyboard shortcut for customButton
       customButton.props.accelerator = '<ctrl>b'

If you want to enable translators to override the shortcut, use the gettext syntax so that an entry in the POT file is generated (See Development_Team/Almanac/Internationalization for details):

       customButton.props.accelerator = _('<ctrl>b')

If you want to use symbols in you shortcuts, you'll need to refer to the X11 keysymdefs (/usr/include/X11/keysymdef.h), e.g., to use a "+" as a shortcut, you'd refer to #define XK_plus 0x002b /* U+002B PLUS SIGN */ and use the string after the XK_:

       customButton.props.accelerator = _('<ctrl>plus')

How do I set the default toolbar menu?

Use the set_expanded() method of the ToolbarButton class.

       my_toolbar_button.set_expanded(True)

When using pre-0.86 toolbars, use the set_current_toolbar() method:

       self.toolbox.set_current_toolbar(1)

How do I set the icon search path for my toolbar button?

By default, the Sugar system icon folders and the icons subdirectory of your activity are searched. You can add additional directories to search as follows:

       icon_theme = gtk.icon_theme_get_default()
       icon_theme.append_search_path(your_icon_path)