GApplication

GApplication — Core application class

Synopsis

                    GApplication;
                    GApplicationClass;
GApplication *      g_application_new                   (const gchar *appid,
                                                         int argc,
                                                         char **argv);
gboolean            g_application_register              (GApplication *application);
GApplication *      g_application_try_new               (const gchar *appid,
                                                         int argc,
                                                         char **argv,
                                                         GError **error);
GApplication *      g_application_unregistered_try_new  (const gchar *appid,
                                                         int argc,
                                                         char **argv,
                                                         GError **error);
GApplication *      g_application_get_instance          (void);
const gchar *       g_application_get_id                (GApplication *application);
void                g_application_add_action            (GApplication *application,
                                                         const gchar *name,
                                                         const gchar *description);
void                g_application_remove_action         (GApplication *application,
                                                         const gchar *name);
gchar **            g_application_list_actions          (GApplication *application);
void                g_application_set_action_enabled    (GApplication *application,
                                                         const gchar *name,
                                                         gboolean enabled);
gboolean            g_application_get_action_enabled    (GApplication *application,
                                                         const gchar *name);
const gchar *       g_application_get_action_description
                                                        (GApplication *application,
                                                         const gchar *name);
void                g_application_invoke_action         (GApplication *application,
                                                         const gchar *name,
                                                         GVariant *platform_data);
void                g_application_run                   (GApplication *application);
gboolean            g_application_quit_with_data        (GApplication *application,
                                                         GVariant *platform_data);
gboolean            g_application_is_remote             (GApplication *application);

Object Hierarchy

  GObject
   +----GApplication

Implemented Interfaces

GApplication implements GInitable.

Properties

  "application-id"           gchar*                : Read / Write / Construct Only
  "argv"                     GVariant              : Read / Write / Construct Only
  "default-quit"             gboolean              : Read / Write / Construct Only
  "is-remote"                gboolean              : Read
  "platform-data"            GVariant              : Read / Write / Construct Only
  "register"                 gboolean              : Read / Write / Construct Only

Signals

  "action-with-data"                               : Run First / No Recursion / Has Details
  "prepare-activation"                             : Run Last
  "quit-with-data"                                 : Run Last

Description

A GApplication is the foundation of an application, unique for a given application identifier. The GApplication 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. By default, g_application_register_with_data() will invoke g_error() if it is run in a context where it cannot support its core features. Note that g_error() is by default fatal.

One of the core features that GApplication provides is process uniqueness, in the context of a "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.

In addition, GApplication provides support for 'actions', which can be presented to the user in a platform-specific way (e.g. Windows 7 jump lists). Note that these are just simple actions without parameters. For more flexible scriptability, implementing a a separate D-Bus interface is recommended, see e.g. Highlevel D-Bus Support.

Finally, GApplication acts as a basic lifecycle root; see the g_application_run() and g_application_quit_with_data() methods.

Before using GApplication, you must choose an "application identifier". The expected form of an application identifier is very close to that of of a DBus bus name. Examples include: "com.example.MyApp" "org.example.internal-apps.Calculator" For convenience, the restrictions on application identifiers are reproduced here:

  • Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit.
  • Application identifiers must contain at least one '.' (period) character (and thus at least two elements).
  • Application identifiers must not begin with a '.' (period) character.
  • Application identifiers must not exceed 255 characters.

D-Bus implementation

On UNIX systems using D-Bus, GApplication is implemented by claiming the application identifier as a bus name on the session bus. The implementation exports an object at the object path that is created by replacing '.' with '/' in the application identifier (e.g. the object path for the application id 'org.gtk.TestApp' is '/org/gtk/TestApp'). The object implements the org.gtk.Application interface.

 org.gtk.Application {
  void Activate(in aay arguments,
                in a{sv} data);

  void InvokeAction(in action,
                    in a{sv} data);

  a{s(sb)} ListActions();
  void Quit(in a{sv} data);
  Signal void ActionsChanged();
}

The Activate function is called on the existing application instance when a second instance fails to take the bus name. arguments contains the commandline arguments given to the second instance and data contains platform-specific additional data.

On all platforms, data will have a key "cwd" of type signature "ay" which contains the working directory of the invoked executable; this data is defined to be in the default GLib filesystem encoding for the platform. See g_filename_to_utf8().

The InvokeAction function can be called to invoke one of the actions exported by the application. On X11 platforms, the platform_data argument should have a "timestamp" parameter of type "u" with the server time of the initiating event.

The ListActions function returns a dictionary with the exported actions of the application. The keys of the dictionary are the action names, and the values are structs containing the description for the action and a boolean that represents if the action is enabled or not.

The Quit function can be called to terminate the application. The data parameter contains platform-specific data. On X11 platforms, the platform_data argument should have a "timestamp" parameter of type "u" with the server time of the initiating event.

The ActionsChanged signal is emitted when the exported actions change (i.e. an action is added, removed, enabled, disabled, or otherwise changed).

GApplication is supported since Gio 2.26.

Details

GApplication

typedef struct _GApplication GApplication;

The GApplication structure contains private data and should only be accessed using the provided API

Since 2.26


GApplicationClass

typedef struct {
  /* signals */
  void        (* action_with_data) (GApplication *application,
				    const gchar  *action_name,
				    GVariant     *platform_data);
  gboolean    (* quit_with_data)   (GApplication *application,
				    GVariant     *platform_data);
  void        (* prepare_activation)   (GApplication  *application,
                                        GVariant      *arguments,
                                        GVariant      *platform_data);

  /* vfuncs */
  void        (* run)    (GApplication *application);
} GApplicationClass;

The GApplicationClass structure contains private data only

action_with_data ()

class handler for the "action-with-data" signal

quit_with_data ()

class handler for the "quit-with-data" signal

prepare_activation ()

class handler for the "prepare-activation" signal

run ()

virtual function, called by g_application_run()

Since 2.26


g_application_new ()

GApplication *      g_application_new                   (const gchar *appid,
                                                         int argc,
                                                         char **argv);

Create a new GApplication. This uses a platform-specific mechanism to ensure the current process is the unique owner of the application (as defined by the appid). If successful, the "is-remote" property will be FALSE, and it is safe to continue creating other resources such as graphics windows.

If the given appid is already running in another process, the the GApplication::activate_with_data signal will be emitted in the remote process, with the data from argv and other platform-specific data available. Subsequently the "default-quit" property will be evaluated. If it's TRUE, then the current process will terminate. If FALSE, then the application remains in the "is-remote" state, and you can e.g. call g_application_invoke_action(). Note that proxy instances should not call g_application_add_action().

This function may do synchronous I/O to obtain unique ownership of the application id, and will block the calling thread in this case.

If the environment does not support the basic functionality of GApplication, this function will invoke g_error(), which by default is a fatal operation. This may arise for example on UNIX systems using D-Bus when the session bus is not available.

As a convenience, this function is defined to call g_type_init() as its very first action.

appid :

System-dependent application identifier

argc :

Number of arguments in argv

argv :

Argument vector, usually from the argv parameter of main() . allow-none. array length=argc.

Returns :

An application instance . transfer full.

Since 2.26


g_application_register ()

gboolean            g_application_register              (GApplication *application);

By default, GApplication ensures process uniqueness when initialized, but this behavior is controlled by the GApplication:register property. If it was given as FALSE at construction time, this function allows you to later attempt to ensure uniqueness.

application :

a GApplication

Returns :

TRUE if registration was successful

g_application_try_new ()

GApplication *      g_application_try_new               (const gchar *appid,
                                                         int argc,
                                                         char **argv,
                                                         GError **error);

This function is similar to g_application_new(), but allows for more graceful fallback if the environment doesn't support the basic GApplication functionality.

appid :

System-dependent application identifier

argc :

Number of arguments in argv

argv :

Argument vector, usually from the argv parameter of main() . allow-none. array length=argc.

error :

a GError

Returns :

An application instance . transfer full.

Since 2.26


g_application_unregistered_try_new ()

GApplication *      g_application_unregistered_try_new  (const gchar *appid,
                                                         int argc,
                                                         char **argv,
                                                         GError **error);

This function is similar to g_application_try_new(), but also sets the GApplication:register property to FALSE. You can later call g_application_register() to complete initialization.

appid :

System-dependent application identifier

argc :

Number of arguments in argv

argv :

Argument vector, usually from the argv parameter of main() . allow-none. array length=argc.

error :

a GError

Returns :

An application instance . transfer full.

Since 2.26


g_application_get_instance ()

GApplication *      g_application_get_instance          (void);

In the normal case where there is exactly one GApplication instance in this process, return that instance. If there are multiple, the first one created will be returned. Otherwise, return NULL.

Returns :

The primary instance of GApplication, or NULL if none is set . transfer none.

Since 2.26


g_application_get_id ()

const gchar *       g_application_get_id                (GApplication *application);

Retrieves the platform-specific identifier for the GApplication.

application :

a GApplication

Returns :

The platform-specific identifier. The returned string is owned by the GApplication instance and it should never be modified or freed

Since 2.26


g_application_add_action ()

void                g_application_add_action            (GApplication *application,
                                                         const gchar *name,
                                                         const gchar *description);

Adds an action name to the list of exported actions of application.

It is an error to call this function if application is a proxy for a remote application.

You can invoke an action using g_application_invoke_action().

The newly added action is enabled by default; you can call g_application_set_action_enabled() to disable it.

application :

a GApplication

name :

the action name

description :

the action description; can be a translatable string

Since 2.26


g_application_remove_action ()

void                g_application_remove_action         (GApplication *application,
                                                         const gchar *name);

Removes the action name from the list of exported actions of application.

It is an error to call this function if application is a proxy for a remote application.

application :

a GApplication

name :

the name of the action to remove

Since 2.26


g_application_list_actions ()

gchar **            g_application_list_actions          (GApplication *application);

Retrieves the list of action names currently exported by application.

It is an error to call this function if application is a proxy for a remote application.

application :

a GApplication

Returns :

a newly allocation, NULL-terminated array of strings containing action names; use g_strfreev() to free the resources used by the returned array . transfer full.

Since 2.26


g_application_set_action_enabled ()

void                g_application_set_action_enabled    (GApplication *application,
                                                         const gchar *name,
                                                         gboolean enabled);

Sets whether the action name inside application should be enabled or disabled.

It is an error to call this function if application is a proxy for a remote application.

Invoking a disabled action will not result in the "action" signal being emitted.

application :

a GApplication

name :

the name of the application

enabled :

whether to enable or disable the action name

Since 2.26


g_application_get_action_enabled ()

gboolean            g_application_get_action_enabled    (GApplication *application,
                                                         const gchar *name);

Retrieves whether the action name is enabled or not.

See g_application_set_action_enabled().

It is an error to call this function if application is a proxy for a remote application.

application :

a GApplication

name :

the name of the action

Returns :

TRUE if the action was enabled, and FALSE otherwise

Since 2.26


g_application_get_action_description ()

const gchar *       g_application_get_action_description
                                                        (GApplication *application,
                                                         const gchar *name);

Gets the description of the action name.

It is an error to call this function if application is a proxy for a remote application.

application :

a GApplication

name :

Action name

Returns :

Description for the given action named name

Since 2.26


g_application_invoke_action ()

void                g_application_invoke_action         (GApplication *application,
                                                         const gchar *name,
                                                         GVariant *platform_data);

Invokes the action name of the passed GApplication.

This function has different behavior depending on whether application is acting as a proxy for another process. In the normal case where the current process is hosting the application, and the specified action exists and is enabled, the "action" signal will be emitted.

If application is a proxy, then the specified action will be invoked in the remote process. It is not necessary to call g_application_add_action() in the current process in order to invoke one remotely.

application :

a GApplication

name :

the name of the action to invoke

platform_data :

platform-specific event data. allow-none.

Since 2.26


g_application_run ()

void                g_application_run                   (GApplication *application);

Starts the application.

The default implementation of this virtual function will simply run a main loop.

It is an error to call this function if application is a proxy for a remote application.

application :

a GApplication

Since 2.26


g_application_quit_with_data ()

gboolean            g_application_quit_with_data        (GApplication *application,
                                                         GVariant *platform_data);

Request that the application quits.

This function has different behavior depending on whether application is acting as a proxy for another process. In the normal case where the current process is hosting the application, the default implementation will quit the main loop created by g_application_run().

If application is a proxy, then the remote process will be asked to quit.

application :

a GApplication

platform_data :

platform-specific data. allow-none.

Returns :

TRUE if the application accepted the request, FALSE otherwise

Since 2.26


g_application_is_remote ()

gboolean            g_application_is_remote             (GApplication *application);

Returns whether the object represents a proxy for a remote application.

application :

a GApplication

Returns :

TRUE if this object represents a proxy for a remote application.

Property Details

The "application-id" property

  "application-id"           gchar*                : Read / Write / Construct Only

The unique identifier for this application. See the documentation for GApplication for more information about this property.

Default value: NULL


The "argv" property

  "argv"                     GVariant              : Read / Write / Construct Only

The argument vector given to this application. It must be a GVariant with a type signature "aay".


The "default-quit" property

  "default-quit"             gboolean              : Read / Write / Construct Only

By default, if a different process is running this application, the process will be exited. Set this property to FALSE to allow custom interaction with the remote process.

Default value: TRUE


The "is-remote" property

  "is-remote"                gboolean              : Read

This property is TRUE if this application instance represents a proxy to the instance of this application in another process.

Default value: TRUE


The "platform-data" property

  "platform-data"            GVariant              : Read / Write / Construct Only

Platform-specific data retrieved from the operating system environment. It must be a GVariant with type signature "a{sv}".


The "register" property

  "register"                 gboolean              : Read / Write / Construct Only

If this property is FALSE, the application construction will not attempt to ensure process uniqueness, and the application is guaranteed to be in the remote state. See GApplication:is-remote.

Default value: TRUE

Signal Details

The "action-with-data" signal

void                user_function                      (GApplication *application,
                                                        gchar        *name,
                                                        GVariant      platform_data,
                                                        gpointer      user_data)          : Run First / No Recursion / Has Details

This signal is emitted when an action is activated. The action name is passed as the first argument, but also as signal detail, so it is possible to connect to this signal for individual actions.

The signal is never emitted for disabled actions.

application :

the object on which the signal is emitted

name :

The name of the activated action

platform_data :

Platform-specific data, or NULL

user_data :

user data set when the signal handler was connected.

The "prepare-activation" signal

void                user_function                      (GApplication *application,
                                                        GVariant      arguments,
                                                        GVariant      platform_data,
                                                        gpointer      user_data)          : Run Last

This signal is emitted when a non-primary process for a given application is invoked while your application is running; for example, when a file browser launches your program to open a file. The raw operating system arguments are passed in the arguments variant. Additional platform-dependent data is stored in platform_data.

application :

the object on which the signal is emitted

arguments :

A GVariant with the signature "aay"

platform_data :

A GVariant with the signature "a{sv}", or NULL

user_data :

user data set when the signal handler was connected.

The "quit-with-data" signal

gboolean            user_function                      (GApplication *application,
                                                        GVariant      platform_data,
                                                        gpointer      user_data)          : Run Last

This signal is emitted when the Quit action is invoked on the application.

The default handler for this signal exits the mainloop of the application.

application :

the object on which the signal is emitted

platform_data :

Platform-specific data, or NULL

user_data :

user data set when the signal handler was connected.

Returns :

TRUE if the signal has been handled, FALSE to continue signal emission