#GtkApplication is a class that handles many important aspects
of a GTK+ application in a convenient fashion, without enforcing
a one-size-fits-all application model.
Currently, GtkApplication handles GTK+ initialization, application
uniqueness, session management, provides some basic scriptability and
desktop shell integration by exporting actions and menus and manages a
list of toplevel windows whose life-cycle is automatically tied to the
life-cycle of your application.
While GtkApplication works fine with plain #GtkWindows, it is recommended
to use it together with #GtkApplicationWindow.
When GDK threads are enabled, GtkApplication will acquire the GDK
lock when invoking actions that arrive from other processes. The GDK
lock is not touched for local action invocations. In order to have
actions invoked in a predictable context it is therefore recommended
that the GDK lock be held while invoking actions locally with
gio.action_group.ActionGroup.activateAction. The same applies to actions
associated with #GtkApplicationWindow and to the “activate” and
“open” #GApplication methods.
#GtkApplication will automatically load menus from the #GtkBuilder
resource located at "gtk/menus.ui", relative to the application's
resource base path (see gio.application.Application.setResourceBasePath). The
menu with the ID "app-menu" is taken as the application's app menu
and the menu with the ID "menubar" is taken as the application's
menubar. Additional menus (most interesting submenus) can be named
and accessed via gtk.application.Application.getMenuById which allows for
dynamic population of a part of the menu structure.
If the resources "gtk/menus-appmenu.ui" or "gtk/menus-traditional.ui" are
present then these files will be used in preference, depending on the value
of gtk.application.Application.prefersAppMenu. If the resource "gtk/menus-common.ui"
is present it will be loaded as well. This is useful for storing items that
are referenced from both "gtk/menus-appmenu.ui" and
"gtk/menus-traditional.ui".
#GtkApplication will also automatically setup an icon search path for
the default icon theme by appending "icons" to the resource base
path. This allows your application to easily store its icons as
resources. See gtk.icon_theme.IconTheme.addResourcePath for more
information.
If there is a resource located at "gtk/help-overlay.ui" which
defines a #GtkShortcutsWindow with ID "help_overlay" then GtkApplication
associates an instance of this shortcuts window with each
#GtkApplicationWindow and sets up keyboard accelerators (Control-F1
and Control-?) to open it. To create a menu item that displays the
shortcuts window, associate the item with the action win.show-help-overlay.
GtkApplication optionally registers with a session manager
of the users session (if you set the #GtkApplication:register-session
property) and offers various functionality related to the session
life-cycle.
An application can block various ways to end the session with
the gtk.application.Application.inhibit function. Typical use cases for
this kind of inhibiting are long-running, uninterruptible operations,
such as burning a CD or performing a disk backup. The session
manager may not honor the inhibitor, but it can be expected to
inform the user about the negative consequences of ending the
session while inhibitors are present.
#GtkApplication is a class that handles many important aspects of a GTK+ application in a convenient fashion, without enforcing a one-size-fits-all application model.
Currently, GtkApplication handles GTK+ initialization, application uniqueness, session management, provides some basic scriptability and desktop shell integration by exporting actions and menus and manages a list of toplevel windows whose life-cycle is automatically tied to the life-cycle of your application.
While GtkApplication works fine with plain #GtkWindows, it is recommended to use it together with #GtkApplicationWindow.
When GDK threads are enabled, GtkApplication will acquire the GDK lock when invoking actions that arrive from other processes. The GDK lock is not touched for local action invocations. In order to have actions invoked in a predictable context it is therefore recommended that the GDK lock be held while invoking actions locally with gio.action_group.ActionGroup.activateAction. The same applies to actions associated with #GtkApplicationWindow and to the “activate” and “open” #GApplication methods.
Automatic resources ## {#automatic-resources}
#GtkApplication will automatically load menus from the #GtkBuilder resource located at "gtk/menus.ui", relative to the application's resource base path (see gio.application.Application.setResourceBasePath). The menu with the ID "app-menu" is taken as the application's app menu and the menu with the ID "menubar" is taken as the application's menubar. Additional menus (most interesting submenus) can be named and accessed via gtk.application.Application.getMenuById which allows for dynamic population of a part of the menu structure.
If the resources "gtk/menus-appmenu.ui" or "gtk/menus-traditional.ui" are present then these files will be used in preference, depending on the value of gtk.application.Application.prefersAppMenu. If the resource "gtk/menus-common.ui" is present it will be loaded as well. This is useful for storing items that are referenced from both "gtk/menus-appmenu.ui" and "gtk/menus-traditional.ui".
It is also possible to provide the menus manually using gtk.application.Application.setAppMenu and gtk.application.Application.setMenubar.
#GtkApplication will also automatically setup an icon search path for the default icon theme by appending "icons" to the resource base path. This allows your application to easily store its icons as resources. See gtk.icon_theme.IconTheme.addResourcePath for more information.
If there is a resource located at "gtk/help-overlay.ui" which defines a #GtkShortcutsWindow with ID "help_overlay" then GtkApplication associates an instance of this shortcuts window with each #GtkApplicationWindow and sets up keyboard accelerators (Control-F1 and Control-?) to open it. To create a menu item that displays the shortcuts window, associate the item with the action win.show-help-overlay.
A simple application ## {#gtkapplication}
A simple example
GtkApplication optionally registers with a session manager of the users session (if you set the #GtkApplication:register-session property) and offers various functionality related to the session life-cycle.
An application can block various ways to end the session with the gtk.application.Application.inhibit function. Typical use cases for this kind of inhibiting are long-running, uninterruptible operations, such as burning a CD or performing a disk backup. The session manager may not honor the inhibitor, but it can be expected to inform the user about the negative consequences of ending the session while inhibitors are present.
## See Also ## {#seealso} HowDoI: Using GtkApplication, Getting Started with GTK+: Basics