# Gio::Application Class Reference

TODO. More...

`#include <giomm/application.h>`

Inheritance diagram for Gio::Application:
[legend]

List of all members.

## Public Member Functions

virtual | ~Application ()
GApplication* | gobj ()
| Provides access to the underlying C GObject.
const GApplication* | gobj () const
| Provides access to the underlying C GObject.
GApplication* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
bool | register_application ()
| By default, Application ensures process uniqueness when initialized, but this behavior is controlled by the GApplication:register property.
Glib::ustring | get_id () const
| Retrieves the platform-specific identifier for the Application.
void | add_action (const Glib::ustring& name, const Glib::ustring& description)
| Adds an action name to the list of exported actions of application.
void | remove_action (const Glib::ustring& name)
| Removes the action name from the list of exported actions of application.
Glib::StringArrayHandle | list_actions () const
| Retrieves the list of action names currently exported by application.
void | set_action_enabled (const Glib::ustring& name, bool enabled=true)
| Sets whether the action name inside application should be enabled or disabled.
bool | get_action_enabled (const Glib::ustring& name) const
| Retrieves whether the action name is enabled or not.
Glib::ustring | get_action_description (const Glib::ustring& name)
| Gets the description of the action name.
void | invoke_action (const Glib::ustring& name, const Glib::VariantBase& platform_data)
| Invokes the action name of the passed Application.
void | run ()
| Starts the application.
bool | quit_with_data (const Glib::VariantBase& platform_data)
| Request that the application quits.
bool | is_remote () const
| Returns whether the object represents a proxy for a remote application.

## Static Public Member Functions

static Glib::RefPtr< Application > | create (const Glib::ustring& appid, int argc, char** argv)
| Create a new Application.
static Glib::RefPtr< Application > | create (const Glib::ustring& appid)
static Glib::RefPtr< Application > | create_try (const Glib::ustring& appid, int argc, char** argv)
| This function is similar to g_application_new(), but allows for more graceful fallback if the environment doesn't support the basic Application functionality.
static Glib::RefPtr< Application > | create_try (const Glib::ustring& appid)
static Glib::RefPtr< Application > | create_unregistered_try (const Glib::ustring& appid, int argc, char** argv)
| This function is similar to g_application_try_new(), but also sets the GApplication:register property to `false`.
static Glib::RefPtr< Application > | create_unregistered_try (const Glib::ustring& appid)
static Glib::RefPtr< Application > | get_instance ()
| In the normal case where there is exactly one Application instance in this process, return that instance.

## Protected Member Functions

| Application ()

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr< Gio::Application > | wrap (GApplication* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

TODO.

Since glibmm 2.26:

## Constructor & Destructor Documentation

virtual Gio::Application::~Application | ( |  | ) | `[virtual]`

Gio::Application::Application | ( |  | ) | `[protected]`

## Member Function Documentation

void Gio::Application::add_action | ( | const Glib::ustring& | name,
|  | const Glib::ustring& | 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.

Since glibmm 2.26:

Parameters:

  | name | The action name.
  | description | The action description; can be a translatable string.

static Glib::RefPtr<Application> Gio::Application::create | ( | const Glib::ustring& | appid | ) | `[static]`

static Glib::RefPtr<Application> Gio::Application::create | ( | const Glib::ustring& | appid,
|  | int | argc,
|  | char ** | argv |
| ) |  |  | `[static]`

Create a new Application.

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 Application: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 Application:default-quit property will be evaluated. If it's `true`, then the current process will terminate. If `false`, then the application remains in the Application: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 Application, this function will invoke Glib::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 Glib::type_init() as its very first action.

Since glibmm 2.26:

Parameters:

  | appid | System-dependent application identifier.
  | argc | Number of arguments in argv.
  | argv | Argument vector, usually from the <parameter>argv</parameter> parameter of main().

Returns:
  An application instance.

static Glib::RefPtr<Application> Gio::Application::create_try | ( | const Glib::ustring& | appid | ) | `[static]`

static Glib::RefPtr<Application> Gio::Application::create_try | ( | const Glib::ustring& | appid,
|  | int | argc,
|  | char ** | argv |
| ) |  |  | `[static]`

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

Since glibmm 2.26:

Parameters:

  | appid | System-dependent application identifier.
  | argc | Number of arguments in argv.
  | argv | Argument vector, usually from the <parameter>argv</parameter> parameter of main().

Returns:
  An application instance.

static Glib::RefPtr<Application> Gio::Application::create_unregistered_try | ( | const Glib::ustring& | appid | ) | `[static]`

static Glib::RefPtr<Application> Gio::Application::create_unregistered_try | ( | const Glib::ustring& | appid,
|  | int | argc,
|  | char ** | argv |
| ) |  |  | `[static]`

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.

Since glibmm 2.26:

Parameters:

  | appid | System-dependent application identifier.
  | argc | Number of arguments in argv.
  | argv | Argument vector, usually from the <parameter>argv</parameter> parameter of main().

Returns:
  An application instance.

Glib::ustring Gio::Application::get_action_description | ( | const Glib::ustring& | 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.

Since glibmm 2.26:

Parameters:

  | name | Action name.

Returns:
  Description for the given action named name.

bool Gio::Application::get_action_enabled | ( | const Glib::ustring& | name | ) | const

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.

Since glibmm 2.26:

Parameters:

  | name | The name of the action.

Returns:
  `true` if the action was enabled, and `false` otherwise.

Glib::ustring Gio::Application::get_id | ( |  | ) | const

Retrieves the platform-specific identifier for the Application.

Since glibmm 2.26:

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

static Glib::RefPtr<Application> Gio::Application::get_instance | ( |  | ) | `[static]`

In the normal case where there is exactly one Application instance in this process, return that instance.

If there are multiple, the first one created will be returned. Otherwise, return `0`.

Since glibmm 2.26:

Returns:
  The primary instance of Application, or `0` if none is set.

const GApplication* Gio::Application::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

GApplication* Gio::Application::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

GApplication* Gio::Application::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

void Gio::Application::invoke_action | ( | const Glib::ustring& | name,
|  | const Glib::VariantBase& | platform_data |
| ) |  |  |

Invokes the action name of the passed Application.

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

Since glibmm 2.26:

Parameters:

  | name | The name of the action to invoke.
  | platform_data | Platform-specific event data.

bool Gio::Application::is_remote | ( |  | ) | const

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

Returns:
  `true` if this object represents a proxy for a remote application.

Glib::StringArrayHandle Gio::Application::list_actions | ( |  | ) | const

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.

Since glibmm 2.26:

Returns:
  A newly allocation, `0`-terminated array of strings containing action names; use Glib::strfreev() to free the resources used by the returned array.

bool Gio::Application::quit_with_data | ( | const Glib::VariantBase& | 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.

Since glibmm 2.26:

Parameters:

  | platform_data | Platform-specific data.

Returns:
  `true` if the application accepted the request, `false` otherwise.

bool Gio::Application::register_application | ( |  | ) |

By default, Application 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. Note that the GApplication:default-quit property no longer applies at this point; if this function returns `false`, platform activation will occur, but the current process will not be terminated.

It is an error to call this function more than once. It is also an error to call this function if the GApplication:register property was `true` at construction time.

Returns:
  `true` if registration was successful.

void Gio::Application::remove_action | ( | const Glib::ustring& | 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.

Since glibmm 2.26:

Parameters:

  | name | The name of the action to remove.

void Gio::Application::run | ( |  | ) |

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.

Since glibmm 2.26:

void Gio::Application::set_action_enabled | ( | const Glib::ustring& | name,
|  | bool | enabled = `true` |
| ) |  |  |

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 Application::action signal being emitted.

Since glibmm 2.26:

Parameters:

  | name | The name of the application.
  | enabled | Whether to enable or disable the action name.

## Friends And Related Function Documentation

Glib::RefPtr< Gio::Application > wrap | ( | GApplication * | object,
|  | bool | take_copy = `false` |
| ) |  |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  | object | The C instance.
  | take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.