Contents
GApplication D-Bus APIs
GApplication uses D-Bus to implement application uniqueness and other features. To do so, it employs a number of D-Bus interfaces. These interfaces are currently considered private implementation details of GApplication and subject to change - therefore they are not documented in the GIO documentation. This page attempts to fill that gap, and to accumulate material for an official specification of these interfaces.
For most uses, it is best to use the GIO APIs to export actions and menus on the bus or access those that have been exported by others. To export actions, use g_dbus_connection_export_action_group. To export menus, use g_dbus_connection_export_menu_model. To access exported actions, use GDBusActionGroup. To access exported menus, use GDBusMenuModel.
org.gtk.Application
Overview
The org.gtk.Application interface offers a number of different "entry points" into a running (or not yet running) application:
- The application can be activated - it is started if it is not running
- The application can be asked to open one or more files - of course, this only makes sense if the application deals with files
- The application can be asked to execute a "commandline"
All of the org.gtk.Application methods take a dictionary of "platform data" as their final argument. Platform data specifies additional data required to complete an action but not directly related to that action. The following pieces of data are currently sent by GApplication:
cwd (ay): the current directory of the caller
environ (aay): the process environment of the caller (optional)
desktop-startup-id (s): the startup notification id (added by GtkApplication).
If the startup notification id is not available, this can be just "_TIMEtime", where time is the time stamp from the event triggering the call.
Methods
Activate :: (a{sv}) → ()Activates the application.
The sole parameter (a{sv}) is a list of "platform data".
Open :: (assa{sv}) → ()Opens one or more files in the application. If the application is not running, it will be started first.
The first parameter (as) is the list of uris to open.
The second parameter (s) is an optional "hint" about the mode in which the files should be opened. It is up to the application to define what modes it supports, typical examples would be "view" or "edit".
The final parameter (a{sv}) is a list of "platform data".
CommandLine :: (oaaya{sv}) → (i)Executes a "command-line" in application.
The first parameter (o) is an object path where an object implementing the org.gtk.private.CommandLine interface has been exported.
The second parameter (aay) is the "argv" array representing the command-line to be executed.
The final parameter (a{sv}) is a list of "platform data".
The function returns the "exit code" of the command-line execution.
org.gtk.private.CommandLine
Overview
An object implementing the org.gtk.private.CommandLine interface is exported by the caller while a command-line is executed in the primary application instance. If the execution of the command-line produces output to stdout or stderr, it will be sent back to the caller via this object.
Methods
Print :: (s) → ()
Prints a string to stdout.
PrintError :: (s) → ()
Prints a string to stderr.
org.gtk.Actions
Overview
The org.gtk.Actions interface describes a group of actions.
Each action:
- has a unique string name
- can be activated
- optionally has a parameter type that must be given to the activation
- has an enabled state that may be true or false
- optionally has a state which can change value, but not type
When activating an action or changing its state, the caller can provide "platform data". Platform data specifies additional data required to complete an action but not directly related to that action. The platform data can include the same keys as org.gtk.Application platform data, most commonly it contains just
desktop-startup-id (s): the startup notification id.
If the startup notification id is not available, this can be just "_TIMEtime", where time is the time stamp from the event triggering the call.
Methods
List :: () → (as)
Lists the names of the actions exported at this object path.
Describe :: (s) → (bgav)
Describes a single action, or a given name.
The return value has the following components:
b specifies if the action is currently enabled. This is a hint that attempting to interact with the action will produce no effect.
g specifies the optional parameter type. If not "", the string specifies the type of argument that must be passed to the activation.
av specifies the optional state. If not empty, the array contains the current value of the state as a variant
DescribeAll :: () → (a{s(bgav)})Describes all actions in a single round-trip.
The dictionary maps action name strings to their descriptions (in the format discussed above).
Activate :: (sava{sv}) → ()Requests activation of the named action.
The action is named by the first parameter (s).
If the action activation requires a parameter then this parameter must be given in the second parameter (av). If there is no parameter to be specified, the array must be empty.
The final parameter (a{sv}) is a list of "platform data".
This method is not guaranteed to have any particular effect. The implementation may take some action (including changing the state of the action, if it is stateful) or it may take none at all. In particular, callers should expect their request to be completely ignored when the enabled flag is false (but even this is not guaranteed).
SetState :: (sva{sv}) → ()Requests the state of an action to be changed to the given value.
The action is named by the first parameter (s).
The requested new state is given in the second parameter (v). It must be equal in type to the existing state.
The final parameter (a{sv}) is a list of "platform data".
This method is not guaranteed to have any particular effect. The implementation of an action can choose to ignore the requested state change, or choose to change its state to something else or to trigger other side effects. In particular, callers should expect their request to be completely ignored when the enabled flag is false (but even this is not guaranteed).
Signals
Changed :: (asa{sb}a{sv}a{s(bgav)})Signals that some change has occurred to the action group.
Four separate types of changes are possible, and the 4 parameters of the change signal reflect these possibilities:
as a list of removed actions
a{sb} a list of actions that had their enabled flag changed
a{sv} a list of actions that had their state changed
a{s(bgav)} a list of new actions added in the same format as the return value of the DescribeAll method
org.gtk.Menus
Overview
The org.gtk.Menus interface is primarily concerned with three things:
- communicating menus to the client
- establishing links between menus and other menus
- notifying clients of changes
As a basic principle, it is recognised that the menu structure of an application is often large. It is also recognised that some menus are liable to frequently change without the user ever having opened the menu. For both of these reasons, the individual menus are arranged into subscription groups. Each subscription group is specified by an unsigned integer. The assignment of integers need not be consecutive.
Within a subscription group there are multiple menus. Each menu is identified with an unsigned integer, unique to its subscription group.
By convention, the primary menu is numbered 0 without subscription group 0.
Actionable menu items (ie: those that produce some effect in the application when they are activated) have a related action, specified by a string. This string specifies the name of the action, according to the org.gtk.Actions interface, at the same object path as the menu.
Methods
Start :: (au) → (a(uuaa{sv}))The Start method is used to indicate that a client is interested in tracking and displaying the content of the menus of a particular list of subscription groups.
Most typically, the client will request subscription group 0 to start.
The call has two effects. First, it replies with all menus defined within the requested subscription groups. The format of the reply is an array of tuples, where the items in each tuple are:
the subscription group of the menu (u)
the number of the menu within that group (u)
an array of menu items (aa{sv})
Each menu item is a dictionary of attributes (a{sv}).
Secondly, this call has a side effect: it atomically requests that the Changed signal start to be emitted for the requested subscription group. Each group has a subscription count and only signals changes on itself when this count is greater than zero.
If a group is specified multiple times then the result is that the contents of that group is only returned once, but the subscription count is increased multiple times.
If a client disconnects from the bus while holding subscriptions then its subscriptions will be cancelled. This prevents "leaking" subscriptions in the case of crashes and is also useful for applications that want to exit without manually cleaning up.
End :: (au)
The End method reverses the previous effects of a call to Start.
When clients are no longer interested in the contents of a subscription group, they should call the End method.
The parameter lists the subscription groups. A subscription group needs to be cancelled the same number of times as it was requested. For this reason, it might make sense to specify the same subscription group multiple times (if multiple Start calls were made for this group).
Signals
Changed :: (a(uuuuaa{sv}))The Changed signal indicates changes to a particular menu.
The changes come as an array of tuples where the items in each tuple are:
the subscription group of the menu (u)
the number of the menu within that group (u)
the position in the menu at which to make the change (u)
the number of items to delete from that position (u)
a list of new items to insert at that position (aa{sv})
Each new menu item is a dictionary of attributes (a{sv}).
Attributes
Menu items can have other attributes besides the "standard" attributes that are listed below, such as id or accel. Consumers need to be prepared to ignore attributes that they have no use for.
label (s): the label to display
action (s): the name of the action
target (v): the parameter to pass when activating the action
section ((uu)): the menu to populate a section, specified as pair of subscription group and menu within that group
submenu ((uu)): the menu to use as a submenu, specified as pair of subscription group and menu within that group
org.gtk.Notification
Overview
An application that wants to use this protocol must be reachable and activatable on the well-known D-Bus name that corresponds to the basename of its .desktop file. It must also support the org.freedesktop.Application interface.
Methods
AddNotification :: (ssa{sv}) → ()Adds a notification for an application.
The first parameter (s) is the application id.
The second parameter (s) is the notification id; if a notification with the same id already exists, it is replaced.
The final parameter (a{sv}) is a description of the notification, and consists of a dictionary with the following key/value pairs:
title (s): the title of the notification
body (s): [optional] body text of the notification
icon (*): [optional] an icon associated with the notification (serialized GIcon)
urgent (b): [optional] whether the notification should be displayed as urgent (boolean)
default-action (s): [optional] the action that should be invoked when activated the notification. Must start with 'app.'
default-action-target: *: [optional] the parameter that default-action is invoked with
buttons (aa{sv}): an array of buttons, each a dictionary with label (s), action (s), and optional target (*)
RemoveNotification :: (ss) → ()
Removes a notification for an application.
The first parameter (s) is the application id.
The second parameter (s) is the notification id.
GApplication D-Bus object paths
Application
GApplication claims the application id as a well-known name on the session bus. It exports an object at the path that is created by converting the application id into an object path in the "obvious way". E.g. an application with id
org.gtk.Test.bloatpad
will export its application object at
/org/gtk/Test/bloatpad
The object implements both the org.gtk.Application interface and the org.gtk.Actions interface (for the application-wide actions).
Menus
When you use gtk_application_set_app_menu() or gtk_application_set_menubar(), GtkApplication also exports the menu models as objects on the bus. The object paths for these can be found in X window properties on each window of the application:
_GTK_APP_MENU_OBJECT_PATH _GTK_MENUBAR_OBJECT_PATH
Currently, they end up being (continuing the earlier example):
/org/gtk/Test/bloatpad/menus/AppMenu /org/gtk/Test/bloatpad/menus/MenuBar
These objects implement the org.gtk.Menus interface.
An important point to notice here is that these menu models contain references to actions by name. They can refer to both application-wide or per-window actions. To differentiate the two, the names are prefixed with "app." or "win.". The exported actions do not carry these prefixes, and it is the responsibility of the desktop shell to "merge" the application-wide and per-window actions and take these prefixes into account.
Another important point is that references to window-specific actions are supposed to be interpreted relative to the currently active window.
Windows
When using GtkApplication together with GtkApplicationWindow, the window-specific actions are also exported on the bus. The object path for this object can be found in an X property on the window:
_GTK_WINDOW_OBJECT_PATH
Currently, the object paths look like this:
/org/gtk/Test/bloatpad/windows/0 /org/gtk/Test/bloatpad/windows/1 ...
These objects implement the org.gtk.Actions interface.
The application id and the corresponding unique bus name are available in X window properties of GtkApplicationWindows as well, to assist desktop shells in matching windows to desktop files and applications:
_GTK_APPLICATION_ID _GTK_UNIQUE_BUS_NAME
The object path for the main application object (which is where the application actions are exported) is also available in an X window property:
_GTK_APPLICATION_OBJECT_PATH