Menus

Note

Gtk.UIManager, Gtk.Action, and Gtk.ActionGroup have been deprecated since GTK+ version 3.10 and should not be used in newly-written code. Use the Application framework instead.

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.

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 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 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:

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

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.

Example

_images/menu_example.png

 1importgi
 2
 3gi.require_version("Gtk", "3.0")
 4fromgi.repositoryimport Gtk, Gdk
 5
 6UI_INFO = """
 7<ui>
 8 <menubar name='MenuBar'>
 9 <menu action='FileMenu'>
 10 <menu action='FileNew'>
 11 <menuitem action='FileNewStandard' />
 12 <menuitem action='FileNewFoo' />
 13 <menuitem action='FileNewGoo' />
 14 </menu>
 15 <separator />
 16 <menuitem action='FileQuit' />
 17 </menu>
 18 <menu action='EditMenu'>
 19 <menuitem action='EditCopy' />
 20 <menuitem action='EditPaste' />
 21 <menuitem action='EditSomething' />
 22 </menu>
 23 <menu action='ChoicesMenu'>
 24 <menuitem action='ChoiceOne'/>
 25 <menuitem action='ChoiceTwo'/>
 26 <separator />
 27 <menuitem action='ChoiceThree'/>
 28 </menu>
 29 </menubar>
 30 <toolbar name='ToolBar'>
 31 <toolitem action='FileNewStandard' />
 32 <toolitem action='FileQuit' />
 33 </toolbar>
 34 <popup name='PopupMenu'>
 35 <menuitem action='EditCopy' />
 36 <menuitem action='EditPaste' />
 37 <menuitem action='EditSomething' />
 38 </popup>
 39</ui>
 40"""
 41
 42
 43classMenuExampleWindow(Gtk.Window):
 44 def__init__(self):
 45 super().__init__(title="Menu Example")
 46
 47 self.set_default_size(200, 200)
 48
 49 action_group = Gtk.ActionGroup(name="my_actions")
 50
 51 self.add_file_menu_actions(action_group)
 52 self.add_edit_menu_actions(action_group)
 53 self.add_choices_menu_actions(action_group)
 54
 55 uimanager = self.create_ui_manager()
 56 uimanager.insert_action_group(action_group)
 57
 58 menubar = uimanager.get_widget("/MenuBar")
 59
 60 box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
 61 box.pack_start(menubar, False, False, 0)
 62
 63 toolbar = uimanager.get_widget("/ToolBar")
 64 box.pack_start(toolbar, False, False, 0)
 65
 66 eventbox = Gtk.EventBox()
 67 eventbox.connect("button-press-event", self.on_button_press_event)
 68 box.pack_start(eventbox, True, True, 0)
 69
 70 label = Gtk.Label(label="Right-click to see the popup menu.")
 71 eventbox.add(label)
 72
 73 self.popup = uimanager.get_widget("/PopupMenu")
 74
 75 self.add(box)
 76
 77 defadd_file_menu_actions(self, action_group):
 78 action_filemenu = Gtk.Action(name="FileMenu", label="File")
 79 action_group.add_action(action_filemenu)
 80
 81 action_filenewmenu = Gtk.Action(name="FileNew", stock_id=Gtk.STOCK_NEW)
 82 action_group.add_action(action_filenewmenu)
 83
 84 action_new = Gtk.Action(
 85 name="FileNewStandard",
 86 label="_New",
 87 tooltip="Create a new file",
 88 stock_id=Gtk.STOCK_NEW,
 89 )
 90 action_new.connect("activate", self.on_menu_file_new_generic)
 91 action_group.add_action_with_accel(action_new, None)
 92
 93 action_group.add_actions(
 94 [
 95 (
 96 "FileNewFoo",
 97 None,
 98 "New Foo",
 99 None,
100 "Create new foo",
101 self.on_menu_file_new_generic,
102 ),
103 (
104 "FileNewGoo",
105 None,
106 "_New Goo",
107 None,
108 "Create new goo",
109 self.on_menu_file_new_generic,
110 ),
111 ]
112 )
113
114 action_filequit = Gtk.Action(name="FileQuit", stock_id=Gtk.STOCK_QUIT)
115 action_filequit.connect("activate", self.on_menu_file_quit)
116 action_group.add_action(action_filequit)
117
118 defadd_edit_menu_actions(self, action_group):
119 action_group.add_actions(
120 [
121 ("EditMenu", None, "Edit"),
122 ("EditCopy", Gtk.STOCK_COPY, None, None, None, self.on_menu_others),
123 ("EditPaste", Gtk.STOCK_PASTE, None, None, None, self.on_menu_others),
124 (
125 "EditSomething",
126 None,
127 "Something",
128 "<control><alt>S",
129 None,
130 self.on_menu_others,
131 ),
132 ]
133 )
134
135 defadd_choices_menu_actions(self, action_group):
136 action_group.add_action(Gtk.Action(name="ChoicesMenu", label="Choices"))
137
138 action_group.add_radio_actions(
139 [
140 ("ChoiceOne", None, "One", None, None, 1),
141 ("ChoiceTwo", None, "Two", None, None, 2),
142 ],
143 1,
144 self.on_menu_choices_changed,
145 )
146
147 three = Gtk.ToggleAction(name="ChoiceThree", label="Three")
148 three.connect("toggled", self.on_menu_choices_toggled)
149 action_group.add_action(three)
150
151 defcreate_ui_manager(self):
152 uimanager = Gtk.UIManager()
153
154 # Throws exception if something went wrong
155 uimanager.add_ui_from_string(UI_INFO)
156
157 # Add the accelerator group to the toplevel window
158 accelgroup = uimanager.get_accel_group()
159 self.add_accel_group(accelgroup)
160 return uimanager
161
162 defon_menu_file_new_generic(self, widget):
163 print("A File|New menu item was selected.")
164
165 defon_menu_file_quit(self, widget):
166 Gtk.main_quit()
167
168 defon_menu_others(self, widget):
169 print("Menu item " + widget.get_name() + " was selected")
170
171 defon_menu_choices_changed(self, widget, current):
172 print(current.get_name() + " was selected.")
173
174 defon_menu_choices_toggled(self, widget):
175 if widget.get_active():
176 print(widget.get_name() + " activated")
177 else:
178 print(widget.get_name() + " deactivated")
179
180 defon_button_press_event(self, widget, event):
181 # Check if right mouse button was preseed
182 if event.type == Gdk.EventType.BUTTON_PRESS and event.button == 3:
183 self.popup.popup(None, None, None, None, event.button, event.time)
184 return True # event has been handled
185
186
187window = MenuExampleWindow()
188window.connect("destroy", Gtk.main_quit)
189window.show_all()
190Gtk.main()