Application

gtk.Application 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 gtk.Windows, it is recommended to use it together with gtk.ApplicationWindow

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 Action.groupActivateAction. The same applies to actions associated with gtk.ApplicationWindow and to the “activate” and “open” gtk.Application methods.

Automatic resources

gtk.Application will automatically load menus from the gtk.Builder resource located at "gtk/menus.ui", relative to the application's resource base path (see 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 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 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 Application.setAppMenu and Application.setMenubar.

gtk.Application 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 IconTheme.addResourcePath for more information.

If there is a resource located at "gtk/help-overlay.ui" which defines a gtk.ShortcutsWindow with ID "help_overlay" then GtkApplication associates an instance of this shortcuts window with each gtk.ApplicationWindow 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

A simple example

GtkApplication optionally registers with a session manager of the users session (if you set the 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 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.

class Application : GioApplication {

protected

GtkApplication* gtkApplication;

GtkApplication* getGtkApplicationStruct(bool transferOwnership);

void* getStruct();

this(GtkApplication* gtkApplication, bool ownedRef);

void setAccelsForAction(string detailedActionName, string[] accels);

static GType getType();

this(string applicationId, GApplicationFlags flags);

void addAccelerator(string accelerator, string actionName, Variant parameter);

void addWindow(Window window);

string[] getAccelsForAction(string detailedActionName);

string[] getActionsForAccel(string accel);

Window getActiveWindow();

MenuModel getAppMenu();

Menu getMenuById(string id);

MenuModel getMenubar();

Window getWindowById(uint id);

ListG getWindows();

uint inhibit(Window window, GtkApplicationInhibitFlags flags, string reason);

bool isInhibited(GtkApplicationInhibitFlags flags);

string[] listActionDescriptions();

bool prefersAppMenu();

void removeAccelerator(string actionName, Variant parameter);

void removeWindow(Window window);

void setAppMenu(MenuModel appMenu);

void setMenubar(MenuModel menubar);

void uninhibit(uint cookie);

gulong addOnQueryEnd(void delegate(Application) dlg, ConnectFlags connectFlags);

gulong addOnWindowAdded(void delegate(Window, Application) dlg, ConnectFlags connectFlags);

gulong addOnWindowRemoved(void delegate(Window, Application) dlg, ConnectFlags connectFlags);

}

Constructors

this this(GtkApplication* gtkApplication, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(string applicationId, GApplicationFlags flags): Creates a new gtk.Application instance.

Members

Functions

addAccelerator void addAccelerator(string accelerator, string actionName, Variant parameter): Installs an accelerator that will cause the named action to be activated when the key combination specificed by accelerator is pressed.
addOnQueryEnd gulong addOnQueryEnd(void delegate(Application) dlg, ConnectFlags connectFlags): Emitted when the session manager is about to end the session, only if register-session is TRUE. Applications can connect to this signal and call Application.inhibit with GTK_APPLICATION_INHIBIT_LOGOUT to delay the end of the session until state has been saved.
addOnWindowAdded gulong addOnWindowAdded(void delegate(Window, Application) dlg, ConnectFlags connectFlags): Emitted when a gtk.Window is added to application through Application.addWindow.
addOnWindowRemoved gulong addOnWindowRemoved(void delegate(Window, Application) dlg, ConnectFlags connectFlags): Emitted when a gtk.Window is removed from application, either as a side-effect of being destroyed or explicitly through Application.removeWindow.
addWindow void addWindow(Window window): Adds a window to application.
getAccelsForAction string[] getAccelsForAction(string detailedActionName): Gets the accelerators that are currently associated with the given action.
getActionsForAccel string[] getActionsForAccel(string 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.
getActiveWindow Window getActiveWindow(): Gets the “active” window for the application.
getAppMenu MenuModel getAppMenu(): Returns the menu model that has been set with Application.setAppMenu.
getGtkApplicationStruct GtkApplication* getGtkApplicationStruct(bool transferOwnership): Get the main Gtk struct
getMenuById Menu getMenuById(string id): Gets a menu from automatically loaded resources. See [Automatic resources][automatic-resources] for more information.
getMenubar MenuModel getMenubar(): Returns the menu model that has been set with Application.setMenubar.
getStruct void* getStruct(): the main Gtk struct as a void*
getWindowById Window getWindowById(uint id): Returns the gtk.ApplicationWindow with the given ID.
getWindows ListG getWindows(): Gets a list of the gtk.Windows associated with application.
inhibit uint inhibit(Window window, GtkApplicationInhibitFlags flags, string reason): 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.
isInhibited bool isInhibited(GtkApplicationInhibitFlags flags): Determines if any of the actions specified in flags are currently inhibited (possibly by another application).
listActionDescriptions string[] listActionDescriptions(): Lists the detailed action names which have associated accelerators. See Application.setAccelsForAction.
prefersAppMenu bool prefersAppMenu(): Determines if the desktop environment in which the application is running would prefer an application menu be shown.
removeAccelerator void removeAccelerator(string actionName, Variant parameter): Removes an accelerator that has been previously added with Application.addAccelerator.
removeWindow void removeWindow(Window window): Remove a window from application.
setAccelsForAction void setAccelsForAction(string detailedActionName, string[] accels): 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.
setAppMenu void setAppMenu(MenuModel appMenu): Sets or unsets the application menu for application.
setMenubar void setMenubar(MenuModel menubar): Sets or unsets the menubar for windows of application.
uninhibit void uninhibit(uint cookie): Removes an inhibitor that has been established with Application.inhibit. Inhibitors are also cleared when the application exits.

Static functions

getType GType getType()

Variables

gtkApplication GtkApplication* gtkApplication;: the main Gtk struct