GApplication

GApplication — Core application class

Synopsis

                    GApplication;
                    GApplicationClass;
GApplication *      g_application_new                   (const gchar *appid);
GApplication *      g_application_new_and_register      (const gchar *appid,
                                                         gint argc,
                                                         gchar **argv);
void                g_application_register_with_data    (GApplication *application,
                                                         gint argc,
                                                         gchar **argv,
                                                         GVariant *platform_data);
void                g_application_format_activation_data
                                                        (GApplication *app,
                                                         GVariantBuilder *builder);
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,
                                                         guint timestamp);
void                g_application_run                   (GApplication *application);
gboolean            g_application_quit                  (GApplication *app,
                                                         guint timestamp);
gboolean            g_application_is_remote             (GApplication *application);

Object Hierarchy

  GObject
   +----GApplication

Properties

  "application-id"           gchar*                : Read / Write / Construct Only
  "default-quit"             gboolean              : Read / Write / Construct Only
  "is-remote"                gboolean              : Read

Signals

  "action"                                         : Run First / No Recursion / Has Details
  "prepare-activation"                             : Run Last
  "quit"                                           : 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; it's expected that most software will use a higher-level application class such as GtkApplication or MxApplication.

In addition to single-instance-ness, 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.

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 timestamp);

  a{s(sb)} ListActions();
  void Quit(in timestamp);
  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, see g_application_format_activation_data().

The InvokeAction function can be called to invoke one of the actions exported by the application. The timestamp parameter should be taken from the user event that triggered the method call (e.g. a button press 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 timestamp parameter should be taken from the user event that triggered the method call (e.g. a button press 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) (GApplication *application,
                          const gchar  *action_name,
                          guint         timestamp);
  gboolean    (* quit)   (GApplication *application,
                          guint         timestamp);
  void        (* prepare_activation)   (GApplication  *application,
                                        GVariant      *arguments,
                                        GVariant      *platform_data);

  /* vfuncs */
  void        (* run)    (GApplication *application);
  void        (*format_activation_data) (GApplication    *application,
                                         GVariantBuilder *builder);
} GApplicationClass;

The GApplicationClass structure contains private data only

action ()

class handler for the "action" signal

quit ()

class handler for the "quit" signal

prepare_activation ()

class handler for the "prepare-activation" signal

run ()

virtual function, called by g_application_run()

format_activation_data ()

virtual function, called by g_application_format_activation_data()

Since 2.26


g_application_new ()

GApplication *      g_application_new                   (const gchar *appid);

Create a new GApplication. The application is initially in "remote" mode. Almost certainly, you want to call g_application_register() immediately after this function, which will finish initialization.

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

appid :

System-dependent application identifier

Returns :

An application instance. [transfer full]

Since 2.26


g_application_new_and_register ()

GApplication *      g_application_new_and_register      (const gchar *appid,
                                                         gint argc,
                                                         gchar **argv);

This is a convenience function which combines g_application_new() with g_application_register_with_data(). Therefore, it may block the calling thread just like g_application_register_with_data().

appid :

An application identifier

argc :

System argument count

argv :

System argument vector. [array length=argc]

Returns :


g_application_register_with_data ()

void                g_application_register_with_data    (GApplication *application,
                                                         gint argc,
                                                         gchar **argv,
                                                         GVariant *platform_data);

Ensure the current process is the unique owner of the application. If successful, the "is-remote" property will be changed to 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 "default-exit" property will be evaluated. If it's TRUE, then a platform-specific action such as bringing any graphics windows associated with the application to the foreground may be initiated. After that, 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().

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

application :

A GApplication

argc :

System argument count

argv :

System argument vector. [array length=argc]

platform_data :

Arbitrary platform-specific data, must have signature "a{sv}". [allow-none]

g_application_format_activation_data ()

void                g_application_format_activation_data
                                                        (GApplication *app,
                                                         GVariantBuilder *builder);

app :

builder :


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,
                                                         guint timestamp);

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

timestamp :

the timestamp that is going to be passed to the "action" signal

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 ()

gboolean            g_application_quit                  (GApplication *app,
                                                         guint timestamp);

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.

app :

timestamp :

Platform-specific event timestamp, may be 0 for default

Returns :

TRUE if the application accepted the request, FALSE otherwise

Since 2.26


g_application_is_remote ()

gboolean            g_application_is_remote             (GApplication *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 "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

Signal Details

The "action" signal

void                user_function                      (GApplication *application,
                                                        gchar        *name,
                                                        gint          timestamp,
                                                        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

timestamp :

Platform-specific event timestamp, may be 0 for default

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}"

user_data :

user data set when the signal handler was connected.

The "quit" signal

gboolean            user_function                      (GApplication *application,
                                                        guint         timestamp,
                                                        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

timestamp :

Platform-specific event timestamp, may be 0 for default

user_data :

user data set when the signal handler was connected.

Returns :

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