15. Menus

GTK+ comes with two different types of menus, Gtk.MenuBar and Gtk.Toolbar. Gtk.MenuBar is a standard menu bar which contains one or more Gtk.MenuItem instances or one of its subclasses. Gtk.Toolbar widgets are used for quick accessibility to commonly used functions of an application. Examples include creating a new document, printing a page or undoing an operation. It contains one or more instances of Gtk.ToolItem or one of its subclasses.

15.1. Actions

Although, there are specific APIs to create menus and toolbars, you should use Gtk.UIManager and create Gtk.Action instances. Actions are organised into groups. A Gtk.ActionGroup is essentially a map from names to Gtk.Action objects. All actions that would make sense to use in a particular context should be in a single group. Multiple action groups may be used for a particular user interface. In fact, it is expected that most non-trivial applications will make use of multiple groups. For example, in an application that can edit multiple documents, one group holding global actions (e.g. quit, about, new), and one group per document holding actions that act on that document (eg. save, cut/copy/paste, etc). Each window’s menus would be constructed from a combination of two action groups.

Different classes representing different types of actions exist:

• Gtk.Action: An action which can be triggered by a menu or toolbar item
• Gtk.ToggleAction: An action which can be toggled between two states
• Gtk.RadioAction: An action of which only one in a group can be active
• Gtk.RecentAction: An action of which represents a list of recently used files

Actions represent operations that the user can be perform, along with some information how it should be presented in the interface, including its name (not for display), its label (for display), an accelerator, whether a label indicates a stock item, a tooltip, as well as the callback that is called when the action gets activated.

You can create actions by either calling one of the constructors directly and adding them to a Gtk.ActionGroup by calling Gtk.ActionGroup.add_action() or Gtk.ActionGroup.add_action_with_accel(), or by calling one of the convenience functions:

• Gtk.ActionGroup.add_actions(),
• Gtk.ActionGroup.add_toggle_actions()
• Gtk.ActionGroup.add_radio_actions().

Note that you must specify actions for sub menus as well as menu items.

15.1.1. Action Objects

class Gtk.Action(name, label, tooltip, stock_id)

name must be a unique name of the action.

If label is not None, it is displayed in menu items and on buttons.

If tooltip is not None, it is used as tooltip for the action.

If stock_id is not None, it is used to lookup the stock item to display in widgets representing the action.

class Gtk.ToggleAction(name, label, tooltip, stock_id)

The arguments are the same as for the Gtk.Action constructor.

class Gtk.RadioAction(name, label, tooltip, stock_id, value)

The first four arguments are the same as for the Gtk.Action constructor.

value indicates the value which get_current_value() should return if this action is selected.

get_current_value()

Obtains the “value” property of the currently active member of the group to which this action belongs.

join_group(group_source)

Joins this radio action object to the group of the group_source radio action object.

group_source must be a radio action object whose group we are joining, or None to remove the radio action from its group.

class Gtk.ActionGroup(name)

Creates a new Gtk.ActionGroup instance. The name of the action group is used when associating keybindings with the actions.

add_action(action)

Adds an Gtk.Action object to the action group.

Note that this method does not set up the accelerator path of the action, use add_action_with_accel() instead.

add_action_with_accel(action, accelerator)

Adds an Gtk.Action object to the action group and sets up the accelerator.

accelerator must be in the format understood by Gtk.accelerator_parse(), or "" for no accelerator, or None to use the stock accelerator.

add_actions(entries[, user_data])

This is a convenience function to create a number of Gtk.Action objects and add them to this action group.

entries is a list of tuples which can vary in size from one to six items with the following information:

• The name of the action (mandatory)
• The stock item of the action (default: None)
• The label for the action (default: None)
• The accelerator for the action, in the format understood by the Gtk.accelerator_parse() function (default: None)
• The tooltip of the action (default: None)
• The callback function invoked when the action is activated (default: None)

The “activate” signals of the actions are connected to the callbacks.

If user_data is not None, it is passed to the callback function (if specified).

add_toggle_actions(entries[, user_data])

This is a convenience function to create a number of Gtk.ToggleAction objects and add them to this action group.

entries is a list of tuples which can vary in size from one to seven items with the following information:

• The name of the action (mandatory)
• The stock item of the action (default: None)
• The label for the action (default: None)
• The accelerator for the action, in the format understood by the Gtk.accelerator_parse() function (default: None)
• The tooltip of the action (default: None)
• The callback function invoked when the action is activated (default: None)
• A Boolean indicating whether the toggle action is active (default: False)

The “activate” signals of the actions are connected to the callbacks.

If user_data is not None, it is passed to the callback function (if specified).

add_radio_actions(entries[, value[, on_change[, user_data]]])

This is a convenience routine to create a group of Gtk.RadioAction objects and add them to this action group.

entries is a list of tuples which can vary in size from one to six items with the following information:

• The name of the action (mandatory)
• The stock item of the action (default: None)
• The label for the action (default: None)
• The accelerator for the action, in the format understood by the Gtk.accelerator_parse() function (default: None)
• The tooltip of the action (default: None)
• The value to set on the radio action (default: 0)

value specifies the radio action that should be set active.

The “changed” signal of the first radio action is connected to the on_change callback (if specified).

If user_data is not None, it is passed to the callback function (if specified).

Gtk.accelerator_parse(accelerator)

Parses a string representing an accelerator. The format looks like “<Control>a” or “<Shift><Alt>F1” or “<Release>z” (the last one is for key release). The parser is fairly liberal and allows lower or upper case, and also abbreviations such as “<Ctl>” and “<Ctrl>”. For character keys the name is not the symbol, but the lowercase name, e.g. one would use “<Ctrl>minus” instead of “<Ctrl>-”.

Returns a tuple (accelerator_key, accelerator_mods), where the latter represents the accelerator modifier mask and the first the accelerator keyval. Both values will be set to 0 (zero) if parsing failed.

15.2. UI Manager

Gtk.UIManager provides an easy way of creating menus and toolbars using an XML-like description.

First of all, you should add the Gtk.ActionGroup to the UI Manager with Gtk.UIManager.insert_action_group(). At this point is also a good idea to tell the parent window to respond to the specified keyboard shortcuts, by using Gtk.UIManager.get_accel_group() and Gtk.Window.add_accel_group().

Then, you can define the actual visible layout of the menus and toolbars, and add the UI layout. This “ui string” uses an XML format, in which you should mention the names of the actions that you have already created. Remember that these names are just the identifiers that we used when creating the actions. They are not the text that the user will see in the menus and toolbars. We provided those human-readable names when we created the actions.

Finally, you retrieve the root widget with Gtk.UIManager.get_widget() and add the widget to a container such as Gtk.Box.

15.2.1. UIManager Objects

class Gtk.UIManager

insert_action_group(action_group[, pos])

Inserts an action group into the list of action groups associated with this manager. Actions in earlier groups hide actions with the same name in later groups.

pos is the position at which the group will be inserted. If omitted, it will be appended.

get_accel_group()

Returns the group of global keyboard accelerators associated with this manager.

get_widget(path)

Looks up a widget by following a path. The path consists of the names specified in the XML description of the UI. separated by ‘/’. Elements which don’t have a name or action attribute in the XML (e.g. <popup>) can be addressed by their XML element name (e.g. “popup”). The root element (“/ui”) can be omitted in the path.

Returns the widget found by following the path, or None if no widget was found.

add_ui_from_string(text)

Parses text containing a UI definition and merges it with the current contents of manager. An enclosing <ui> element is added if it is missing.

Returns the merge id for the merged UI.

Throws an exception if an error occurred.

15.3. Example

from gi.repository import Gtk, Gdk

UI_INFO = """
<ui>
  <menubar name='MenuBar'>
    <menu action='FileMenu'>
      <menu action='FileNew'>
        <menuitem action='FileNewStandard' />
        <menuitem action='FileNewFoo' />
        <menuitem action='FileNewGoo' />
      </menu>
      <separator />
      <menuitem action='FileQuit' />
    </menu>
    <menu action='EditMenu'>
      <menuitem action='EditCopy' />
      <menuitem action='EditPaste' />
      <menuitem action='EditSomething' />
    </menu>
    <menu action='ChoicesMenu'>
      <menuitem action='ChoiceOne'/>
      <menuitem action='ChoiceTwo'/>
      <separator />
      <menuitem action='ChoiceThree'/>
    </menu>
  </menubar>
  <toolbar name='ToolBar'>
    <toolitem action='FileNewStandard' />
    <toolitem action='FileQuit' />
  </toolbar>
  <popup name='PopupMenu'>
    <menuitem action='EditCopy' />
    <menuitem action='EditPaste' />
    <menuitem action='EditSomething' />
  </popup>
</ui>
"""

class MenuExampleWindow(Gtk.Window):

    def __init__(self):
        Gtk.Window.__init__(self, title="Menu Example")

        self.set_default_size(200, 200)

        action_group = Gtk.ActionGroup("my_actions")

        self.add_file_menu_actions(action_group)
        self.add_edit_menu_actions(action_group)
        self.add_choices_menu_actions(action_group)

        uimanager = self.create_ui_manager()
        uimanager.insert_action_group(action_group)

        menubar = uimanager.get_widget("/MenuBar")

        box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
        box.pack_start(menubar, False, False, 0)

        toolbar = uimanager.get_widget("/ToolBar")
        box.pack_start(toolbar, False, False, 0)

        eventbox = Gtk.EventBox()
        eventbox.connect("button-press-event", self.on_button_press_event)
        box.pack_start(eventbox, True, True, 0)

        label = Gtk.Label("Right-click to see the popup menu.")
        eventbox.add(label)

        self.popup = uimanager.get_widget("/PopupMenu")

        self.add(box)

    def add_file_menu_actions(self, action_group):
        action_filemenu = Gtk.Action("FileMenu", "File", None, None)
        action_group.add_action(action_filemenu)

        action_filenewmenu = Gtk.Action("FileNew", None, None, Gtk.STOCK_NEW)
        action_group.add_action(action_filenewmenu)

        action_new = Gtk.Action("FileNewStandard", "_New",
            "Create a new file", Gtk.STOCK_NEW)
        action_new.connect("activate", self.on_menu_file_new_generic)
        action_group.add_action_with_accel(action_new, None)

        action_group.add_actions([
            ("FileNewFoo", None, "New Foo", None, "Create new foo",
             self.on_menu_file_new_generic),
            ("FileNewGoo", None, "_New Goo", None, "Create new goo",
             self.on_menu_file_new_generic),
        ])

        action_filequit = Gtk.Action("FileQuit", None, None, Gtk.STOCK_QUIT)
        action_filequit.connect("activate", self.on_menu_file_quit)
        action_group.add_action(action_filequit)

    def add_edit_menu_actions(self, action_group):
        action_group.add_actions([
            ("EditMenu", None, "Edit"),
            ("EditCopy", Gtk.STOCK_COPY, None, None, None,
             self.on_menu_others),
            ("EditPaste", Gtk.STOCK_PASTE, None, None, None,
             self.on_menu_others),
            ("EditSomething", None, "Something", "<control><alt>S", None,
             self.on_menu_others)
        ])

    def add_choices_menu_actions(self, action_group):
        action_group.add_action(Gtk.Action("ChoicesMenu", "Choices", None, None))

        action_group.add_radio_actions([
            ("ChoiceOne", None, "One", None, None, 1),
            ("ChoiceTwo", None, "Two", None, None, 2)
        ], 1, self.on_menu_choices_changed)

        three = Gtk.ToggleAction("ChoiceThree", "Three", None, None)
        three.connect("toggled", self.on_menu_choices_toggled)
        action_group.add_action(three)

    def create_ui_manager(self):
        uimanager = Gtk.UIManager()

        # Throws exception if something went wrong
        uimanager.add_ui_from_string(UI_INFO)

        # Add the accelerator group to the toplevel window
        accelgroup = uimanager.get_accel_group()
        self.add_accel_group(accelgroup)
        return uimanager

    def on_menu_file_new_generic(self, widget):
        print "A File|New menu item was selected."

    def on_menu_file_quit(self, widget):
        Gtk.main_quit()

    def on_menu_others(self, widget):
        print "Menu item " + widget.get_name() + " was selected"

    def on_menu_choices_changed(self, widget, current):
        print current.get_name() + " was selected."

    def on_menu_choices_toggled(self, widget):
        if widget.get_active():
            print widget.get_name() + " activated"
        else:
            print widget.get_name() + " deactivated"

    def on_button_press_event(self, widget, event):
        # Check if right mouse button was preseed
        if event.type == Gdk.EventType.BUTTON_PRESS and event.button == 3:
            self.popup.popup(None, None, None, None, event.button, event.time)
            return True # event has been handled

window = MenuExampleWindow()        
window.connect("delete-event", Gtk.main_quit)
window.show_all()
Gtk.main()