Permalink
Cannot retrieve contributors at this time
Menus | |
===== | |
.. note:: :class:`Gtk.UIManager`, :class:`Gtk.Action`, and :class:`Gtk.ActionGroup` | |
have been deprecated since GTK+ version 3.10 and should not be used in | |
newly-written code. Use the :ref:`application` framework instead. | |
GTK+ comes with two different types of menus, :class:`Gtk.MenuBar` and | |
:class:`Gtk.Toolbar`. :class:`Gtk.MenuBar` is a standard menu bar which contains | |
one or more :class:`Gtk.MenuItem` instances or one of its subclasses. | |
:class:`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 | |
:class:`Gtk.ToolItem` or one of its subclasses. | |
Actions | |
------- | |
Although, there are specific APIs to create menus and toolbars, you should | |
use :class:`Gtk.UIManager` and create :class:`Gtk.Action` instances. | |
Actions are organised into groups. A :class:`Gtk.ActionGroup` is essentially a | |
map from names to :class:`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: | |
* :class:`Gtk.Action`: An action which can be triggered by a menu or toolbar | |
item | |
* :class:`Gtk.ToggleAction`: An action which can be toggled between two states | |
* :class:`Gtk.RadioAction`: An action of which only one in a group can be | |
active | |
* :class:`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 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 :class:`Gtk.ActionGroup` by calling | |
:meth:`Gtk.ActionGroup.add_action` or :meth:`Gtk.ActionGroup.add_action_with_accel`, | |
or by calling one of the convenience functions: | |
* :meth:`Gtk.ActionGroup.add_actions`, | |
* :meth:`Gtk.ActionGroup.add_toggle_actions` | |
* :meth:`Gtk.ActionGroup.add_radio_actions`. | |
Note that you must specify actions for sub menus as well as menu items. | |
UI Manager | |
---------- | |
:class:`Gtk.UIManager` provides an easy way of creating menus and toolbars using | |
an `XML-like description <https://developer.gnome.org/gtk3/stable/GtkUIManager.html#XML-UI>`_. | |
First of all, you should add the :class:`Gtk.ActionGroup` to the UI Manager with | |
:meth:`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 | |
:meth:`Gtk.UIManager.get_accel_group` and :meth:`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 :meth:`Gtk.UIManager.get_widget` | |
and add the widget to a container such as :class:`Gtk.Box`. | |
Example | |
------- | |
.. image:: ../images/menu_example.png | |
.. literalinclude:: ../examples/menu_example.py | |
:linenos: |