Application

gtk.application.Application 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, gtk.application.Application 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 gtk.application.Application works fine with plain gtk.window.Windows, it is recommended to use it together with gtk.application_window.ApplicationWindow.

Automatic resources

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

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.Application.setMenubar.

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

If there is a resource located at gtk/help-overlay.ui which defines a gtk.shortcuts_window.ShortcutsWindow with ID help_overlay then gtk.application.Application associates an instance of this shortcuts window with each gtk.application_window.ApplicationWindow and sets up the keyboard accelerator <kbd>Control</kbd>+<kbd>?</kbd> 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

gtk.application.Application optionally registers with a session manager of the users session (if you set the property@Gtk.Application: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

HowDoI: Using GtkApplication, Getting Started with GTK: Basics

Constructors

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

Creates a new gtk.application.Application instance.

Members

Functions

addWindow
void addWindow(gtk.window.Window window)

Adds a window to application.

connectQueryEnd
ulong connectQueryEnd(T callback, Flag!"After" after)

Connect to QueryEnd signal.

connectWindowAdded
ulong connectWindowAdded(T callback, Flag!"After" after)

Connect to WindowAdded signal.

connectWindowRemoved
ulong 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.

getActiveWindow
gtk.window.Window getActiveWindow()

Gets the “active” window for the application.

getMenuById
gio.menu.Menu getMenuById(string id)

Gets a menu from automatically loaded resources.

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 gtk.application_window.ApplicationWindow with the given ID.

getWindows
gtk.window.Window[] getWindows()

Gets a list of the gtk.window.Window instances 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.

listActionDescriptions
string[] listActionDescriptions()

Lists the detailed action names which have associated accelerators.

removeWindow
void removeWindow(gtk.window.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.

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 previously established.

Inherited Members

From Application

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.ObjectG 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.ObjectG 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
ulong connectActivate(T callback, Flag!"After" after)

Connect to Activate signal.

connectCommandLine
ulong connectCommandLine(T callback, Flag!"After" after)

Connect to CommandLine signal.

connectHandleLocalOptions
ulong connectHandleLocalOptions(T callback, Flag!"After" after)

Connect to HandleLocalOptions signal.

connectNameLost
ulong connectNameLost(T callback, Flag!"After" after)

Connect to NameLost signal.

connectOpen
ulong connectOpen(T callback, Flag!"After" after)

Connect to Open signal.

connectShutdown
ulong connectShutdown(T callback, Flag!"After" after)

Connect to Shutdown signal.

connectStartup
ulong connectStartup(T callback, Flag!"After" after)

Connect to Startup signal.