16.5.7 Adding tool bar buttons

As an alternative to creating new menu items, you can create new buttons on the tool bar, with a similar syntax, by using the <button> tag. As for the <menu> tag, it requires an action attribute which specifies what should be done when the button is pressed. The button is not created if no such action was created.

Within this tag, the tag <pixmap> can be used to indicate the location of an image file (of the type jpeg, png, gif or xpm) to be used as icon for the button. An empty <button> tag indicates a separator in the tool bar.

A title can also be specified with <title>. This will be visible only if the user choses to see both text and icons (or text only) in the tool bar. This title also acts as a tooltip (popup help message) when the button is displayed as an icon only.

The following example defines a new button:

     <?xml version="1.0" ?>
     <stats>
       <button action="execute my stats">
         <title>stats</title>
         <pixmap>/my_pixmaps/button.jpg</pixmap>
       </button>
     </stats>

The <button> tag allows you to create a simple button that the user can press to start an action. GPS also supports another type of button, a combo box, from which the user can choose among a list of choices. Such a combo box can be created with the <entry> tag.

This tag accepts the following arguments:

id (mandatory)

This should be a unique id for this combo box, and will be used later on to refer it, in particular from the scripting languages. It can be any string

label (default is "")

The text of a label to display on the left of the combo box. If this isn't specified, no text will be displayed

on-changed (default is "")

The name of a GPS action to execute whenever the user selects a new value in the combo box. This action is called with two parameters, the unique id of the combo box and the newly selected text respectively.

It also accepts any number of <choice> tags, each of which defines one of the values the user can choose from. These tags accepts one optional attribute, "on-selected", which is the name of a GPS action to call when that particular value is selected.

        <action name="animal_changed">
           <shell>echo A new animal was selected in combo $1: animal is $2</shell>
        </action>
        <action name="gnu-selected">
           <shell>echo Congratulations on choosing a Gnu</shell>
        </action>
        <entry id="foo" label="Animal" on-changed="animal_changed">
           <choice>Elephant</choice>
           <choice on-selected="gnu-selected">Gnu</choice>
        </entry>

A more convenient interface exists for Python, the GPS.Toolbar class, which gives you the same flexibility as above, but also gives you dynamic control over the entry, and allows placement of buttons at arbitrary positions in the toolbar. See the python documentation.