Description [src]

class Gtk.Application : Gio.Application
  implements Gio.ActionGroup, Gio.ActionMap {
  /* No available fields */

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 g_action_group_activate_action(). 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 g_application_set_resource_base_path()). 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_get_menu_by_id() 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_prefers_app_menu(). 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_set_app_menu() and gtk_application_set_menubar().

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_add_resource_path() 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

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


hierarchy this GtkApplication implements_0 GActionGroup this--implements_0 implements_1 GActionMap this--implements_1 ancestor_0 GApplication ancestor_0--this ancestor_1 GObject ancestor_1--ancestor_0




Creates a new GtkApplication instance.

since: 3.0

Instance methods


Installs an accelerator that will cause the named action to be activated when the key combination specificed by accelerator is pressed.

deprecated: 3.14 since: 3.4


Adds a window to application.

since: 3.0


Gets the accelerators that are currently associated with the given action.

since: 3.12


Returns the list of actions (possibly empty) that accel maps to. Each item in the list is a detailed action name in the usual form.

since: 3.14


Gets the “active” window for the application.

since: 3.6


Returns the menu model that has been set with gtk_application_set_app_menu().

since: 3.4


Gets a menu from automatically loaded resources. See [Automatic resources][automatic-resources] for more information.

since: 3.14


Returns the menu model that has been set with gtk_application_set_menubar().

since: 3.4


Returns the GtkApplicationWindow with the given ID.

since: 3.6


Gets a list of the GtkWindows associated with application.

since: 3.0


Inform the session manager that certain types of actions should be inhibited. This is not guaranteed to work on all platforms and for all types of actions.

since: 3.4


Determines if any of the actions specified in flags are currently inhibited (possibly by another application).

since: 3.4


Lists the detailed action names which have associated accelerators. See gtk_application_set_accels_for_action().

since: 3.12


Determines if the desktop environment in which the application is running would prefer an application menu be shown.

since: 3.14


Removes an accelerator that has been previously added with gtk_application_add_accelerator().

deprecated: 3.14 since: 3.4


Remove a window from application.

since: 3.0


Sets zero or more keyboard accelerators that will trigger the given action. The first item in accels will be the primary accelerator, which may be displayed in the UI.

since: 3.12


Sets or unsets the application menu for application.

since: 3.4


Sets or unsets the menubar for windows of application.

since: 3.4


Removes an inhibitor that has been established with gtk_application_inhibit(). Inhibitors are also cleared when the application exits.

since: 3.4

Methods inherited from GApplication (34)

Please see GApplication for a full list of methods.

Methods inherited from GObject (43)

Please see GObject for a full list of methods.

Methods inherited from GActionGroup (14)

Emits the GActionGroup::action-added signal on action_group.

since: 2.28


Emits the GActionGroup::action-enabled-changed signal on action_group.

since: 2.28


Emits the GActionGroup::action-removed signal on action_group.

since: 2.28


Emits the GActionGroup::action-state-changed signal on action_group.

since: 2.28


Activate the named action within action_group.

since: 2.28


Request for the state of the named action within action_group to be changed to value.

since: 2.28


Checks if the named action within action_group is currently enabled.

since: 2.28


Queries the type of the parameter that must be given when activating the named action within action_group.

since: 2.28


Queries the current state of the named action within action_group.

since: 2.28


Requests a hint about the valid range of values for the state of the named action within action_group.

since: 2.28


Queries the type of the state of the named action within action_group.

since: 2.28


Checks if the named action exists within action_group.

since: 2.28


Lists the actions contained within action_group.

since: 2.28


Queries all aspects of the named action within an action_group.

since: 2.32

Methods inherited from GActionMap (4)

Adds an action to the action_map.

since: 2.32


A convenience function for creating multiple GSimpleAction instances and adding them to a GActionMap.

since: 2.32


Looks up the action with the name action_name in action_map.

since: 2.32


Removes the named action from the action map.

since: 2.32


No description available.

No description available.

No description available.


Set this property to TRUE to register with the session manager.

since: 3.4


This property is TRUE if GTK+ believes that the screensaver is currently active. GTK+ only tracks session state (including this) when GtkApplication::register-session is set to TRUE.

since: 3.24

Properties inherited from GApplication (8)
No description available.

No description available.

No description available.

No description available.


Whether the application is currently marked as busy through g_application_mark_busy() or g_application_bind_busy_property().

since: 2.44

No description available.

No description available.

No description available.



Emitted when the session manager is about to end the session, only if GtkApplication::register-session is TRUE. Applications can connect to this signal and call gtk_application_inhibit() with GTK_APPLICATION_INHIBIT_LOGOUT to delay the end of the session until state has been saved.

unstable since: 3.24.8


Emitted when a GtkWindow is added to application through gtk_application_add_window().

since: 3.2


Emitted when a GtkWindow is removed from application, either as a side-effect of being destroyed or explicitly through gtk_application_remove_window().

since: 3.2

Signals inherited from GApplication (7)

The ::activate signal is emitted on the primary instance when an activation occurs. See g_application_activate().


The ::command-line signal is emitted on the primary instance when a commandline is not handled locally. See g_application_run() and the GApplicationCommandLine documentation for more information.


The ::handle-local-options signal is emitted on the local instance after the parsing of the commandline options has occurred.

since: 2.40


The ::name-lost signal is emitted only on the registered primary instance when a new instance has taken over. This can only happen if the application is using the G_APPLICATION_ALLOW_REPLACEMENT flag.

since: 2.60


The ::open signal is emitted on the primary instance when there are files to open. See g_application_open() for more information.


The ::shutdown signal is emitted only on the registered primary instance immediately after the main loop terminates.


The ::startup signal is emitted on the primary instance immediately after registration. See g_application_register().

Signals inherited from GObject (1)

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

Signals inherited from GActionGroup (4)

Signals that a new action was just added to the group. This signal is emitted after the action has been added and is now visible.

since: 2.28


Signals that the enabled status of the named action has changed.

since: 2.28


Signals that an action is just about to be removed from the group. This signal is emitted before the action is removed, so the action is still visible and can be queried from the signal handler.

since: 2.28


Signals that the state of the named action has changed.

since: 2.28

Class structure

struct GtkApplicationClass {
  GApplicationClass parent_class;
  void (* window_added) (
    GtkApplication* application,
    GtkWindow* window
  void (* window_removed) (
    GtkApplication* application,
    GtkWindow* window
No description available.
Class members
parent_class: GApplicationClass

The parent class.

window_added: void (* window_added) ( GtkApplication* application, GtkWindow* window )
No description available.
window_removed: void (* window_removed) ( GtkApplication* application, GtkWindow* window )
No description available.

Virtual methods

No description available.

No description available.