Application

#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

class Application : Application {

this(void* ptr, Flag!"Take" take);

static GType _getGType();

GType _gType [@property getter];

Application self();

static ApplicationGidBuilder builder();

gtk.window.Window activeWindow [@property getter];

gio.menu_model.MenuModel appMenu [@property getter];

gio.menu_model.MenuModel appMenu [@property setter];

gio.menu_model.MenuModel menubar [@property getter];

gio.menu_model.MenuModel menubar [@property setter];

bool registerSession [@property getter];

bool registerSession [@property setter];

bool screensaverActive [@property getter];

this(string applicationId, gio.types.ApplicationFlags flags);

void addAccelerator(string accelerator, string actionName, glib.variant.Variant parameter);

void addWindow(gtk.window.Window window);

string[] getAccelsForAction(string detailedActionName);

string[] getActionsForAccel(string accel);

gtk.window.Window getActiveWindow();

gio.menu_model.MenuModel getAppMenu();

gio.menu.Menu getMenuById(string id);

gio.menu_model.MenuModel getMenubar();

gtk.window.Window getWindowById(uint id);

gtk.window.Window[] getWindows();

uint inhibit(gtk.window.Window window, gtk.types.ApplicationInhibitFlags flags, string reason);

bool isInhibited(gtk.types.ApplicationInhibitFlags flags);

string[] listActionDescriptions();

bool prefersAppMenu();

void removeAccelerator(string actionName, glib.variant.Variant parameter);

void removeWindow(gtk.window.Window window);

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

void setAppMenu(gio.menu_model.MenuModel appMenu);

void setMenubar(gio.menu_model.MenuModel menubar);

void uninhibit(uint cookie);

gulong connectQueryEnd(T callback, Flag!"After" after);

gulong connectWindowAdded(T callback, Flag!"After" after);

gulong connectWindowRemoved(T callback, Flag!"After" after);

}

Constructors

this this(void* ptr, Flag!"Take" take)
this this(string applicationId, gio.types.ApplicationFlags flags): Creates a new #GtkApplication instance.

Members

Functions

addAccelerator void addAccelerator(string accelerator, string actionName, glib.variant.Variant parameter): Installs an accelerator that will cause the named action to be activated when the key combination specificed by accelerator is pressed.
addWindow void addWindow(gtk.window.Window window): Adds a window to application.
connectQueryEnd gulong connectQueryEnd(T callback, Flag!"After" after): Connect to QueryEnd signal.
connectWindowAdded gulong connectWindowAdded(T callback, Flag!"After" after): Connect to WindowAdded signal.
connectWindowRemoved gulong connectWindowRemoved(T callback, Flag!"After" after): Connect to WindowRemoved signal.
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 gtk.window.Window getActiveWindow(): Gets the “active” window for the application.
getAppMenu gio.menu_model.MenuModel getAppMenu(): Returns the menu model that has been set with gtk.application.Application.setAppMenu.
getMenuById gio.menu.Menu getMenuById(string id): Gets a menu from automatically loaded resources. See [Automatic resources][automatic-resources] for more information.
getMenubar gio.menu_model.MenuModel getMenubar(): Returns the menu model that has been set with gtk.application.Application.setMenubar.
getWindowById gtk.window.Window getWindowById(uint id): Returns the #GtkApplicationWindow with the given ID.
getWindows gtk.window.Window[] getWindows(): Gets a list of the #GtkWindows associated with application.
inhibit uint inhibit(gtk.window.Window window, gtk.types.ApplicationInhibitFlags 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(gtk.types.ApplicationInhibitFlags 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 gtk.application.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, glib.variant.Variant parameter): Removes an accelerator that has been previously added with gtk.application.Application.addAccelerator.
removeWindow void removeWindow(gtk.window.Window window): Remove a window from application.
self Application self(): Returns this, for use in with statements.
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(gio.menu_model.MenuModel appMenu): Sets or unsets the application menu for application.
setMenubar void setMenubar(gio.menu_model.MenuModel menubar): Sets or unsets the menubar for windows of application.
uninhibit void uninhibit(uint cookie): Removes an inhibitor that has been established with gtk.application.Application.inhibit. Inhibitors are also cleared when the application exits.

Properties

_gType GType _gType [@property getter]
activeWindow gtk.window.Window activeWindow [@property getter]
appMenu gio.menu_model.MenuModel appMenu [@property getter]
appMenu gio.menu_model.MenuModel appMenu [@property setter]
menubar gio.menu_model.MenuModel menubar [@property getter]
menubar gio.menu_model.MenuModel menubar [@property setter]
registerSession bool registerSession [@property getter]: Get registerSession property.
registerSession bool registerSession [@property setter]: Set registerSession property.
screensaverActive bool screensaverActive [@property getter]: Get screensaverActive property.

Static functions

_getGType GType _getGType()
builder ApplicationGidBuilder builder(): Get builder for gtk.application.Application

Inherited Members

From Application

_getGType GType _getGType()
_gType GType _gType [@property getter]
self Application self(): Returns this, for use in with statements.
builder ApplicationGidBuilder builder(): Get builder for gio.application.Application
actionGroup gio.action_group.ActionGroup actionGroup [@property setter]: Set actionGroup property.
applicationId string applicationId [@property getter]: Get applicationId property.
applicationId string applicationId [@property setter]: Set applicationId property.
flags gio.types.ApplicationFlags flags [@property getter]: Get flags property.
flags gio.types.ApplicationFlags flags [@property setter]: Set flags property.
inactivityTimeout uint inactivityTimeout [@property getter]: Get inactivityTimeout property.
inactivityTimeout uint inactivityTimeout [@property setter]: Set inactivityTimeout property.
isBusy bool isBusy [@property getter]: Get isBusy property.
isRegistered bool isRegistered [@property getter]: Get isRegistered property.
isRemote bool isRemote [@property getter]: Get isRemote property.
resourceBasePath string resourceBasePath [@property getter]: Get resourceBasePath property.
resourceBasePath string resourceBasePath [@property setter]: Set resourceBasePath property.
version_ string version_ [@property getter]: Get version_ property.
version_ string version_ [@property setter]: Set version_ property.
getDefault gio.application.Application getDefault(): Returns the default #GApplication instance for this process.
idIsValid bool idIsValid(string applicationId): Checks if application_id is a valid application identifier.
activate void activate(): Activates the application.
addMainOption void addMainOption(string longName, char shortName, glib.types.OptionFlags flags, glib.types.OptionArg arg, string description, string argDescription): Add an option to be handled by application.
addMainOptionEntries void addMainOptionEntries(glib.types.OptionEntry[] entries): Adds main option entries to be handled by application.
addOptionGroup void addOptionGroup(glib.option_group.OptionGroup group): Adds a #GOptionGroup to the commandline handling of application.
bindBusyProperty void bindBusyProperty(gobject.object.ObjectWrap object, string property): Marks application as busy (see gio.application.Application.markBusy) while property on object is true.
getApplicationId string getApplicationId(): Gets the unique identifier for application.
getDbusConnection gio.dbus_connection.DBusConnection getDbusConnection(): Gets the #GDBusConnection being used by the application, or null.
getDbusObjectPath string getDbusObjectPath(): Gets the D-Bus object path being used by the application, or null.
getFlags gio.types.ApplicationFlags getFlags(): Gets the flags for application.
getInactivityTimeout uint getInactivityTimeout(): Gets the current inactivity timeout for the application.
getIsBusy bool getIsBusy(): Gets the application's current busy state, as set through gio.application.Application.markBusy or gio.application.Application.bindBusyProperty.
getIsRegistered bool getIsRegistered(): Checks if application is registered.
getIsRemote bool getIsRemote(): Checks if application is remote.
getResourceBasePath string getResourceBasePath(): Gets the resource base path of application.
getVersion string getVersion(): Gets the version of application.
hold void hold(): Increases the use count of application.
markBusy void markBusy(): Increases the busy count of application.
open void open(gio.file.File[] files, string hint): Opens the given files.
quit void quit(): Immediately quits the application.
register bool register(gio.cancellable.Cancellable cancellable): Attempts registration of the application.
release void release(): Decrease the use count of application.
run int run(string[] argv): Runs the application.
sendNotification void sendNotification(string id, gio.notification.Notification notification): Sends a notification on behalf of application to the desktop shell. There is no guarantee that the notification is displayed immediately, or even at all.
setActionGroup void setActionGroup(gio.action_group.ActionGroup actionGroup): This used to be how actions were associated with a #GApplication. Now there is #GActionMap for that.
setApplicationId void setApplicationId(string applicationId): Sets the unique identifier for application.
setDefault void setDefault(): Sets or unsets the default application for the process, as returned by gio.application.Application.getDefault.
setFlags void setFlags(gio.types.ApplicationFlags flags): Sets the flags for application.
setInactivityTimeout void setInactivityTimeout(uint inactivityTimeout): Sets the current inactivity timeout for the application.
setOptionContextDescription void setOptionContextDescription(string description): Adds a description to the application option context.
setOptionContextParameterString void setOptionContextParameterString(string parameterString): Sets the parameter string to be used by the commandline handling of application.
setOptionContextSummary void setOptionContextSummary(string summary): Adds a summary to the application option context.
setResourceBasePath void setResourceBasePath(string resourcePath): Sets (or unsets) the base resource path of application.
setVersion void setVersion(string version_): Sets the version number of application. This will be used to implement a --version command line argument
unbindBusyProperty void unbindBusyProperty(gobject.object.ObjectWrap object, string property): Destroys a binding between property and the busy state of application that was previously created with gio.application.Application.bindBusyProperty.
unmarkBusy void unmarkBusy(): Decreases the busy count of application.
withdrawNotification void withdrawNotification(string id): Withdraws a notification that was sent with gio.application.Application.sendNotification.
connectActivate gulong connectActivate(T callback, Flag!"After" after): Connect to Activate signal.
connectCommandLine gulong connectCommandLine(T callback, Flag!"After" after): Connect to CommandLine signal.
connectHandleLocalOptions gulong connectHandleLocalOptions(T callback, Flag!"After" after): Connect to HandleLocalOptions signal.
connectNameLost gulong connectNameLost(T callback, Flag!"After" after): Connect to NameLost signal.
connectOpen gulong connectOpen(T callback, Flag!"After" after): Connect to Open signal.
connectShutdown gulong connectShutdown(T callback, Flag!"After" after): Connect to Shutdown signal.
connectStartup gulong connectStartup(T callback, Flag!"After" after): Connect to Startup signal.

gtk application classes