Permalink
Cannot retrieve contributors at this time
74 lines (54 sloc)
2.93 KB
.. _application: | |
Application | |
=========== | |
:class:`Gtk.Application` encompasses many repetitive tasks that a modern | |
application needs such as handling multiple instances, D-Bus activation, | |
opening files, command line parsing, startup/shutdown, menu management, | |
window management, and more. | |
Actions | |
------- | |
:class:`Gio.Action` is a way to expose any single task your application or widget | |
does by a name. These actions can be disabled/enabled at runtime and they can | |
either be activated or have a state changed (if they contain state). | |
The reason to use actions is to separate out the logic from the UI. For example | |
this allows using a menubar on OSX and a gear menu on GNOME both simply | |
referencing the name of an action. The main implementation of this you will | |
be using is :class:`Gio.SimpleAction` which will be demonstrated later. | |
Many classes such as :class:`Gio.MenuItem` and :class:`Gtk.ModelButton` support | |
properties to set an action name. | |
These actions can be grouped together into a :class:`Gio.ActionGroup` and | |
when these groups are added to a widget with :meth:`Gtk.Widget.insert_action_group()` | |
they will gain a prefix. Such as "win" when added to a :class:`Gtk.ApplicationWindow`. | |
You will use the full action name when referencing it such as "app.about" but when | |
you create the action it will just be "about" until added to the application. | |
You can also very easily make keybindings for actions by setting the `accel` | |
property in the :class:`Gio.Menu` file or by using :meth:`Gtk.Application.set_accels_for_action()`. | |
Menus | |
----- | |
Your menus should be defined in XML using :class:`Gio.Menu` and would reference | |
the previously mentioned actions you defined. :class:`Gtk.Application` allows you | |
to set a menu either via :meth:`Gtk.Application.set_app_menu()` | |
or :meth:`Gtk.Application.set_menubar()`. If you make use of :class:`Gio.Resource` | |
this can automatically use the correct menu based on platform, otherwise you can | |
set them manually. A detailed example is shown below. | |
Command Line | |
------------ | |
When creating your application it takes a flag property of :class:`Gio.ApplicationFlags`. | |
Using this you can let it handle everything itself or have more custom behavior. | |
You can use `HANDLES_COMMAND_LINE` to allow custom behavior in :meth:`Gio.Application.do_command_line()`. | |
In combination with :meth:`Gio.Application.add_main_option()` to add custom options. | |
Using `HANDLES_OPEN` will do the work of simply taking file arguments for you and | |
let you handle it in :meth:`Gio.Application.do_open()`. | |
If your application is already open these will all be sent to the existing instance | |
unless you use `NON_UNIQUE` to allow multiple instances. | |
Example | |
------- | |
.. image:: ../images/application_example.png | |
.. literalinclude:: ../examples/application_example.py | |
:linenos: | |
See Also | |
-------- | |
- https://wiki.gnome.org/HowDoI/GtkApplication | |
- https://wiki.gnome.org/HowDoI/GAction | |
- https://wiki.gnome.org/HowDoI/ApplicationMenu | |
- https://wiki.gnome.org/HowDoI/GMenu |