Class
GioApplication
since: 2.28
Description [src]
class Gio.Application : GObject.Object
implements Gio.ActionGroup, Gio.ActionMap {
/* No available fields */
}
GApplication
is the core class for application support.
A GApplication
is the foundation of an application. It wraps some
low-level platform-specific services and is intended to act as the
foundation for higher-level application classes such as
GtkApplication
or MxApplication
. In general, you should not use
this class outside of a higher level framework.
GApplication
provides convenient life-cycle management by maintaining
a “use count” for the primary application instance. The use count can
be changed using g_application_hold()
and
g_application_release()
. If it drops to zero, the application
exits. Higher-level classes such as GtkApplication
employ the use count
to ensure that the application stays alive as long as it has any opened windows.
Another feature that GApplication
(optionally) provides is process
uniqueness. Applications can make use of this functionality by
providing a unique application ID. If given, only one application
with this ID can be running at a time per session. The session
concept is platform-dependent, but corresponds roughly to a graphical
desktop login. When your application is launched again, its
arguments are passed through platform communication to the already
running program. The already running instance of the program is
called the “primary instance”; for non-unique applications this is
always the current instance. On Linux, the D-Bus session bus
is used for communication.
The use of GApplication
differs from some other commonly-used
uniqueness libraries (such as libunique) in important ways. The
application is not expected to manually register itself and check
if it is the primary instance. Instead, the main()
function of a
GApplication
should do very little more than instantiating the
application instance, possibly connecting signal handlers, then
calling g_application_run()
. All checks for uniqueness are done
internally. If the application is the primary instance then the
startup signal is emitted and the mainloop runs. If the application
is not the primary instance then a signal is sent to the primary
instance and g_application_run()
promptly returns. See the code
examples below.
If used, the expected form of an application identifier is the
same as that of a
D-Bus well-known bus name.
Examples include: com.example.MyApp
, org.example.internal_apps.Calculator
,
org._7_zip.Archiver
.
For details on valid application identifiers, see g_application_id_is_valid()
.
On Linux, the application identifier is claimed as a well-known bus name
on the user’s session bus. This means that the uniqueness of your
application is scoped to the current session. It also means that your
application may provide additional services (through registration of other
object paths) at that bus name. The registration of these object paths
should be done with the shared GDBus session bus. Note that due to the
internal architecture of GDBus, method calls can be dispatched at any time
(even if a main loop is not running). For this reason, you must ensure that
any object paths that you wish to register are registered before GApplication
attempts to acquire the bus name of your application (which happens in
g_application_register()
). Unfortunately, this means that you cannot
use GApplication:is-remote
to decide if you want to register
object paths.
GApplication
also implements the GActionGroup
and GActionMap
interfaces and lets you easily export actions by adding them with
g_action_map_add_action()
. When invoking an action by calling
g_action_group_activate_action()
on the application, it is always
invoked in the primary instance. The actions are also exported on
the session bus, and GIO provides the GDBusActionGroup
wrapper to
conveniently access them remotely. GIO provides a GDBusMenuModel
wrapper
for remote access to exported GMenuModel
s.
Note: Due to the fact that actions are exported on the session bus,
using maybe
parameters is not supported, since D-Bus does not support
maybe
types.
There is a number of different entry points into a GApplication
:
-
via ‘Activate’ (i.e. just starting the application)
-
via ‘Open’ (i.e. opening some files)
-
by handling a command-line
-
via activating an action
The GApplication::startup
signal lets you handle the application
initialization for all of these in a single place.
Regardless of which of these entry points is used to start the
application, GApplication
passes some ‘platform data’ from the
launching instance to the primary instance, in the form of a
GVariant
dictionary mapping strings to variants. To use platform
data, override the Gio.ApplicationClass.before_emit
or
Gio.ApplicationClass.after_emit
virtual functions
in your GApplication
subclass. When dealing with
GApplicationCommandLine
objects, the platform data is
directly available via g_application_command_line_get_cwd()
,
g_application_command_line_get_environ()
and
g_application_command_line_get_platform_data()
.
As the name indicates, the platform data may vary depending on the
operating system, but it always includes the current directory (key
cwd
), and optionally the environment (ie the set of environment
variables and their values) of the calling process (key environ
).
The environment is only added to the platform data if the
G_APPLICATION_SEND_ENVIRONMENT
flag is set. GApplication
subclasses
can add their own platform data by overriding the
Gio.ApplicationClass.add_platform_data
virtual function. For instance,
GtkApplication
adds startup notification data in this way.
To parse commandline arguments you may handle the
GApplication::command-line
signal or override the
Gio.ApplicationClass.local_command_line
virtual function, to parse them in
either the primary instance or the local instance, respectively.
For an example of opening files with a GApplication
, see
gapplication-example-open.c.
For an example of using actions with GApplication
, see
gapplication-example-actions.c.
For an example of using extra D-Bus hooks with GApplication
, see
gapplication-example-dbushooks.c.
Available since: 2.28
Instance methods
g_application_add_main_option_entries
Adds main option entries to be handled by application
.
since: 2.40
g_application_add_option_group
Adds a GOptionGroup
to the commandline handling of application
.
since: 2.40
g_application_bind_busy_property
Marks application
as busy (see g_application_mark_busy()) while
property
on object
is TRUE
.
since: 2.44
g_application_get_dbus_connection
Gets the GDBusConnection
being used by the application, or NULL
.
since: 2.34
g_application_get_dbus_object_path
Gets the D-Bus object path being used by the application, or NULL
.
since: 2.34
g_application_get_inactivity_timeout
Gets the current inactivity timeout for the application.
since: 2.28
g_application_get_is_busy
Gets the application’s current busy state, as set through
g_application_mark_busy()
or g_application_bind_busy_property().
since: 2.44
g_application_send_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.
since: 2.40
g_application_set_action_group
This used to be how actions were associated with a GApplication
.
Now there is GActionMap
for that.
deprecated: 2.32 since: 2.28
g_application_set_default
Sets or unsets the default application for the process, as returned by g_application_get_default().
since: 2.32
g_application_set_inactivity_timeout
Sets the current inactivity timeout for the application.
since: 2.28
g_application_set_option_context_description
Adds a description to the application
option context.
since: 2.56
g_application_set_option_context_parameter_string
Sets the parameter string to be used by the commandline handling of application
.
since: 2.56
g_application_set_option_context_summary
Adds a summary to the application
option context.
since: 2.56
g_application_set_resource_base_path
Sets (or unsets) the base resource path of application
.
since: 2.42
g_application_set_version
Sets the version number of application
. This will be used to implement
a --version
command line argument.
since: 2.80
g_application_unbind_busy_property
Destroys a binding between property
and the busy state of
application
that was previously created with g_application_bind_busy_property().
since: 2.44
g_application_withdraw_notification
Withdraws a notification that was sent with g_application_send_notification().
since: 2.40
Methods inherited from GActionGroup (14)
g_action_group_action_added
Emits the GActionGroup::action-added
signal on action_group
.
since: 2.28
g_action_group_action_enabled_changed
Emits the GActionGroup::action-enabled-changed
signal on action_group
.
since: 2.28
g_action_group_action_removed
Emits the GActionGroup::action-removed
signal on action_group
.
since: 2.28
g_action_group_action_state_changed
Emits the GActionGroup::action-state-changed
signal on action_group
.
since: 2.28
g_action_group_activate_action
Activate the named action within action_group
.
since: 2.28
g_action_group_change_action_state
Request for the state of the named action within action_group
to be
changed to value
.
since: 2.28
g_action_group_get_action_enabled
Checks if the named action within action_group
is currently enabled.
since: 2.28
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
.
since: 2.28
g_action_group_get_action_state
Queries the current state of the named action within action_group
.
since: 2.28
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
.
since: 2.28
g_action_group_get_action_state_type
Queries the type of the state of the named action within
action_group
.
since: 2.28
g_action_group_has_action
Checks if the named action exists within action_group
.
since: 2.28
g_action_group_list_actions
Lists the actions contained within action_group
.
since: 2.28
g_action_group_query_action
Queries all aspects of the named action within an action_group
.
since: 2.32
Methods inherited from GActionMap (5)
g_action_map_add_action
Adds an action to the action_map
.
since: 2.32
g_action_map_add_action_entries
A convenience function for creating multiple GSimpleAction
instances and adding them to a GActionMap
.
since: 2.32
g_action_map_lookup_action
Looks up the action with the name action_name
in action_map
.
since: 2.32
g_action_map_remove_action
Removes the named action from the action map.
since: 2.32
g_action_map_remove_action_entries
Remove actions from a GActionMap
. This is meant as the reverse of
g_action_map_add_action_entries()
.
since: 2.78
Properties
Gio.Application:action-group
The group of actions that the application exports.
deprecated: 2.32 since: 2.28
Gio.Application:inactivity-timeout
Time (in milliseconds) to stay alive after becoming idle.
since: 2.28
Gio.Application:is-busy
Whether the application is currently marked as busy through
g_application_mark_busy()
or g_application_bind_busy_property().
since: 2.44
Signals
Gio.Application::activate
The ::activate signal is emitted on the primary instance when an activation occurs. See g_application_activate().
Gio.Application::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.
Gio.Application::handle-local-options
The ::handle-local-options signal is emitted on the local instance after the parsing of the commandline options has occurred.
since: 2.40
Gio.Application::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.
since: 2.60
Gio.Application::open
The ::open signal is emitted on the primary instance when there are
files to open. See g_application_open()
for more information.
Gio.Application::shutdown
The ::shutdown signal is emitted only on the registered primary instance immediately after the main loop terminates.
Gio.Application::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.
since: 2.28
GActionGroup::action-enabled-changed
Signals that the enabled status of the named action has changed.
since: 2.28
GActionGroup::action-removed
Signals that an action is just about to be removed from the group.
since: 2.28
GActionGroup::action-state-changed
Signals that the state of the named action has changed.
since: 2.28
Class structure
struct GioApplicationClass {
void (* startup) (
GApplication* application
);
void (* activate) (
GApplication* application
);
void (* open) (
GApplication* application,
GFile** files,
gint n_files,
const gchar* hint
);
int (* command_line) (
GApplication* application,
GApplicationCommandLine* command_line
);
gboolean (* local_command_line) (
GApplication* application,
gchar*** arguments,
int* exit_status
);
void (* before_emit) (
GApplication* application,
GVariant* platform_data
);
void (* after_emit) (
GApplication* application,
GVariant* platform_data
);
void (* add_platform_data) (
GApplication* application,
GVariantBuilder* builder
);
void (* quit_mainloop) (
GApplication* application
);
void (* run_mainloop) (
GApplication* application
);
void (* shutdown) (
GApplication* application
);
gboolean (* dbus_register) (
GApplication* application,
GDBusConnection* connection,
const gchar* object_path,
GError** error
);
void (* dbus_unregister) (
GApplication* application,
GDBusConnection* connection,
const gchar* object_path
);
gint (* handle_local_options) (
GApplication* application,
GVariantDict* options
);
gboolean (* name_lost) (
GApplication* application
);
}
Virtual function table for GApplication
.
Class members
startup: void (* startup) ( GApplication* application )
Invoked on the primary instance immediately after registration.
activate: void (* activate) ( GApplication* application )
Invoked on the primary instance when an activation occurs.
open: void (* open) ( GApplication* application, GFile** files, gint n_files, const gchar* hint )
Invoked on the primary instance when there are files to open.
command_line: int (* command_line) ( GApplication* application, GApplicationCommandLine* command_line )
Invoked on the primary instance when a command-line is not handled locally.
local_command_line: gboolean (* local_command_line) ( GApplication* application, gchar*** arguments, int* exit_status )
Invoked (locally). The virtual function has the chance to inspect (and possibly replace) command line arguments. See
g_application_run()
for more information. Also see theGApplication::handle-local-options
signal, which is a simpler alternative to handling some commandline options locally.before_emit: void (* before_emit) ( GApplication* application, GVariant* platform_data )
Invoked on the primary instance before ‘activate’, ‘open’, ‘command-line’ or any action invocation, gets the ‘platform data’ from the calling instance.
after_emit: void (* after_emit) ( GApplication* application, GVariant* platform_data )
Invoked on the primary instance after ‘activate’, ‘open’, ‘command-line’ or any action invocation, gets the ‘platform data’ from the calling instance.
add_platform_data: void (* add_platform_data) ( GApplication* application, GVariantBuilder* builder )
Invoked (locally) to add ‘platform data’ to be sent to the primary instance when activating, opening or invoking actions.
quit_mainloop: void (* quit_mainloop) ( GApplication* application )
Used to be invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested). Not used anymore since 2.32.
run_mainloop: void (* run_mainloop) ( GApplication* application )
Used to be invoked on the primary instance from
g_application_run()
if the use-count is non-zero. Since 2.32, GApplication is iterating the main context directly and is not usingrun_mainloop
anymore.shutdown: void (* shutdown) ( GApplication* application )
Invoked only on the registered primary instance immediately after the main loop terminates.
dbus_register: gboolean (* dbus_register) ( GApplication* application, GDBusConnection* connection, const gchar* object_path, GError** error )
Invoked locally during registration, if the application is using its D-Bus backend. You can use this to export extra objects on the bus, that need to exist before the application tries to own the bus name. The function is passed the
GDBusConnection
to to session bus, and the object path thatGApplication
will use to export its D-Bus API. If this function returnsTRUE
, registration will proceed; otherwise registration will abort. Since: 2.34.dbus_unregister: void (* dbus_unregister) ( GApplication* application, GDBusConnection* connection, const gchar* object_path )
Invoked locally during unregistration, if the application is using its D-Bus backend. Use this to undo anything done by the
dbus_register
vfunc. Since: 2.34.handle_local_options: gint (* handle_local_options) ( GApplication* application, GVariantDict* options )
Invoked locally after the parsing of the commandline options has occurred. Since: 2.40.
name_lost: gboolean (* name_lost) ( GApplication* application )
Invoked when another instance is taking over the name. Since: 2.60.
Virtual methods
Gio.ApplicationClass.add_platform_data
Invoked (locally) to add ‘platform data’ to be sent to the primary instance when activating, opening or invoking actions.
Gio.ApplicationClass.after_emit
Invoked on the primary instance after ‘activate’, ‘open’, ‘command-line’ or any action invocation, gets the ‘platform data’ from the calling instance.
Gio.ApplicationClass.before_emit
Invoked on the primary instance before ‘activate’, ‘open’, ‘command-line’ or any action invocation, gets the ‘platform data’ from the calling instance.
Gio.ApplicationClass.command_line
Invoked on the primary instance when a command-line is not handled locally.
Gio.ApplicationClass.dbus_register
Invoked locally during registration, if the application is
using its D-Bus backend. You can use this to export extra objects on the
bus, that need to exist before the application tries to own the bus name.
The function is passed the GDBusConnection
to to session bus, and the
object path that GApplication
will use to export its D-Bus API.
If this function returns TRUE
, registration will proceed; otherwise
registration will abort. Since: 2.34.
Gio.ApplicationClass.dbus_unregister
Invoked locally during unregistration, if the application
is using its D-Bus backend. Use this to undo anything done by
the dbus_register
vfunc. Since: 2.34.
Gio.ApplicationClass.handle_local_options
Invoked locally after the parsing of the commandline options has occurred. Since: 2.40.
Gio.ApplicationClass.local_command_line
This virtual function is always invoked in the local instance. It
gets passed a pointer to a NULL
-terminated copy of argv
and is
expected to remove arguments that it handled (shifting up remaining arguments).
Gio.ApplicationClass.quit_mainloop
Used to be invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested). Not used anymore since 2.32.
Gio.ApplicationClass.run_mainloop
Used to be invoked on the primary instance from
g_application_run()
if the use-count is non-zero. Since 2.32,
GApplication is iterating the main context directly and is not
using run_mainloop
anymore.
Gio.ApplicationClass.shutdown
Invoked only on the registered primary instance immediately after the main loop terminates.