application.txt

.. _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