Class
GtkApplication
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 win.show-help-overlay.
A simple application ## {#gtkapplication}
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.
Instance methods
gtk_application_add_accelerator
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
gtk_application_get_accels_for_action
Gets the accelerators that are currently associated with the given action.
since: 3.12
gtk_application_get_actions_for_accel
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
gtk_application_get_app_menu
Returns the menu model that has been set with gtk_application_set_app_menu().
since: 3.4
gtk_application_get_menu_by_id
Gets a menu from automatically loaded resources. See [Automatic resources][automatic-resources] for more information.
since: 3.14
gtk_application_get_menubar
Returns the menu model that has been set with gtk_application_set_menubar().
since: 3.4
gtk_application_inhibit
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
gtk_application_is_inhibited
Determines if any of the actions specified in flags
are
currently inhibited (possibly by another application).
since: 3.4
gtk_application_list_action_descriptions
Lists the detailed action names which have associated accelerators. See gtk_application_set_accels_for_action().
since: 3.12
gtk_application_prefers_app_menu
Determines if the desktop environment in which the application is running would prefer an application menu be shown.
since: 3.14
gtk_application_remove_accelerator
Removes an accelerator that has been previously added with gtk_application_add_accelerator().
deprecated: 3.14 since: 3.4
gtk_application_set_accels_for_action
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
gtk_application_uninhibit
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 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:register-session
Set this property to TRUE
to register with the session manager.
since: 3.4
Gtk.Application:screensaver-active
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)
Gio.Application:action-group
Gio.Application:application-id
Gio.Application:flags
Gio.Application:inactivity-timeout
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
Gio.Application:is-remote
Gio.Application:resource-base-path
Signals
Gtk.Application::query-end
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
Gtk.Application::window-added
Emitted when a GtkWindow
is added to application
through gtk_application_add_window().
since: 3.2
Gtk.Application::window-removed
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)
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().