Gtk.Application
Description: Reference for Gtk.Application

### Class

# GtkApplication

#### Description [src]

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

`GtkApplication` is a high-level API for writing applications.

It supports many aspects of writing a GTK application in a convenient fashion, without enforcing a one-size-fits-all 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 `GtkWindow`s, it is recommended to use it together with `GtkApplicationWindow`.

## 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 “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.

Note that automatic resource loading uses the resource base path that is set at construction time and will not work if the resource base path is changed at a later time.

It is also possible to provide the menubar manually using `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 the keyboard accelerator `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

A simple example is available in the GTK source code repository

`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

HowDoI: Using GtkApplication, Getting Started with GTK: Basics.

#### Hierarchy

#### Ancestors

- GApplication
- GObject

#### Implements

- GActionGroup
- GActionMap

#### Constructors

###### gtk_application_new

Creates a new `GtkApplication` instance.

#### Instance methods

###### gtk_application_add_window

Adds a window to `application`.

###### gtk_application_get_accels_for_action

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

###### gtk_application_get_actions_for_accel

Returns the list of actions (possibly empty) that `accel` maps to.

###### gtk_application_get_active_window

Gets the “active” window for the application.

###### gtk_application_get_menu_by_id

Gets a menu from automatically loaded resources.

###### gtk_application_get_menubar

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

###### gtk_application_get_window_by_id

Returns the `GtkApplicationWindow` with the given ID.

###### gtk_application_get_windows

Gets a list of the `GtkWindow` instances associated with `application`.

###### gtk_application_inhibit

Inform the session manager that certain types of actions should be inhibited.

###### gtk_application_list_action_descriptions

Lists the detailed action names which have associated accelerators.

###### gtk_application_remove_window

Remove a window from `application`.

###### gtk_application_set_accels_for_action

Sets zero or more keyboard accelerators that will trigger the given action.

###### gtk_application_set_menubar

Sets or unsets the menubar for windows of `application`.

###### gtk_application_uninhibit

Removes an inhibitor that has been previously established.

##### Methods inherited from GApplication (36)

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)

###### g_action_group_action_added

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

###### g_action_group_action_enabled_changed

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

###### g_action_group_action_removed

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

###### g_action_group_action_state_changed

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

###### g_action_group_activate_action

Activate the named action within `action_group`.

###### g_action_group_change_action_state

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

###### g_action_group_get_action_enabled

Checks if the named action within `action_group` is currently enabled.

###### g_action_group_get_action_parameter_type

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

###### g_action_group_get_action_state

Queries the current state of the named action within `action_group`.

###### g_action_group_get_action_state_hint

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

###### g_action_group_get_action_state_type

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

###### g_action_group_has_action

Checks if the named action exists within `action_group`.

###### g_action_group_list_actions

Lists the actions contained within `action_group`.

###### g_action_group_query_action

Queries all aspects of the named action within an `action_group`.

##### Methods inherited from GActionMap (5)

###### g_action_map_add_action

Adds an action to the `action_map`.

###### g_action_map_add_action_entries

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

###### g_action_map_lookup_action

Looks up the action with the name `action_name` in `action_map`.

###### g_action_map_remove_action

Removes the named action from the action map.

###### g_action_map_remove_action_entries

Remove actions from a `GActionMap`. This is meant as the reverse of g_action_map_add_action_entries().

#### Properties

###### Gtk.Application:active-window

The currently focused window of the application.

###### Gtk.Application:menubar

The `GMenuModel` to be used for the application’s menu bar.

###### Gtk.Application:register-session

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

###### Gtk.Application:screensaver-active

This property is `TRUE` if GTK believes that the screensaver is currently active.

##### Properties inherited from GApplication (9)

###### Gio.Application:action-group

The group of actions that the application exports.

###### Gio.Application:application-id

The unique identifier for the application.

###### Gio.Application:flags

Flags specifying the behaviour of the application.

###### Gio.Application:inactivity-timeout

Time (in milliseconds) to stay alive after becoming idle.

###### Gio.Application:is-busy

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

###### Gio.Application:is-registered

Whether `g_application_register()` has been called.

###### Gio.Application:is-remote

Whether this application instance is remote.

###### Gio.Application:resource-base-path

The base resource path for the application.

###### Gio.Application:version

The human-readable version number of the application.

#### Signals

###### Gtk.Application::query-end

Emitted when the session manager is about to end the session.

###### Gtk.Application::window-added

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

###### Gtk.Application::window-removed

Emitted when a `GtkWindow` is removed from `application`.

##### Signals inherited from GApplication (7)

###### GApplication::activate

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

###### GApplication::command-line

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.

###### GApplication::handle-local-options

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

###### GApplication::name-lost

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.

###### GApplication::open

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

###### GApplication::shutdown

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

###### GApplication::startup

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

##### Signals inherited from GObject (1)

###### GObject::notify

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)

###### GActionGroup::action-added

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.

###### GActionGroup::action-enabled-changed

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

###### GActionGroup::action-removed

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.

###### GActionGroup::action-state-changed

Signals that the state of the named action has changed.

#### 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 )`

  Signal emitted when a `GtkWindow` is added to application through gtk_application_add_window().

`window_removed: void (* window_removed) ( GtkApplication* application, GtkWindow* window )`

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

#### Virtual methods

###### Gtk.ApplicationClass.window_added

Signal emitted when a `GtkWindow` is added to application through gtk_application_add_window().

###### Gtk.ApplicationClass.window_removed

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