UniqueApp

## UniqueApp UniqueApp — Base class for singleton applications |

## Synopsis

    enum                UniqueCommand;
    struct              UniqueApp;
    struct              UniqueAppClass;
    UniqueApp *         unique_app_new                      (const gchar *name,
                                                             const gchar *startup_id);
    UniqueApp *         unique_app_new_with_commands        (const gchar *name,
                                                             const gchar *startup_id,
                                                             const gchar *first_command_name,
                                                             ...);
    void                unique_app_add_command              (UniqueApp *app,
                                                             const gchar *command_name,
                                                             gint command_id);
    void                unique_app_watch_window             (UniqueApp *app,
                                                             GtkWindow *window);
    gboolean            unique_app_is_running               (UniqueApp *app);
    enum                UniqueResponse;
    UniqueResponse      unique_app_send_message             (UniqueApp *app,
                                                             gint command_id,
                                                             UniqueMessageData *message_data);

## Object Hierarchy

      GObject
       +----UniqueApp

## Properties

      "is-running"               gboolean              : Read
      "name"                     gchar*                : Read / Write / Construct Only
      "screen"                   GdkScreen*            : Read / Write / Construct
      "startup-id"               gchar*                : Read / Write / Construct Only

## Signals

      "message-received"                               : No Hooks

## Description

UniqueApp is the base class for single instance applications. You can either create an instance of UniqueApp via `unique_app_new()` and `unique_app_new_with_commands()`; or you can subclass UniqueApp with your own application class.

A UniqueApp instance is guaranteed to either be the first running at the time of creation or be able to send messages to the currently running instance; there is no race possible between the creation of the UniqueApp instance and the call to `unique_app_is_running()`.

The usual method for using the UniqueApp API is to create a new instance, passing an application-dependent name as construction-only property; the UniqueApp:name property is required, and should be in the form of a domain name, like `org.gnome.YourApplication`.

After the creation, you should check whether an instance of your application is already running, using `unique_app_is_running()`; if this method returns `FALSE` the usual application construction sequence can continue; if it returns `TRUE` you can either exit or send a message using UniqueMessageData and `unique_app_send_message()`.

You can define custom commands using `unique_app_add_command()`: you need to provide an arbitrary integer and a string for the command.

### Note

You need to initialize GTK+ in order to use UniqueApp.

## Details

### enum UniqueCommand

    typedef enum { /*< prefix=UNIQUE >*/
      UNIQUE_INVALID  = 0,
      UNIQUE_ACTIVATE = -1,
      UNIQUE_NEW      = -2,
      UNIQUE_OPEN     = -3,
      UNIQUE_CLOSE    = -4
    } UniqueCommand;

Command to send to a currently active instance. User defined commands should be positive integers, and should be added using the `unique_app_add_command()` function after creating a UniqueApp instance

`UNIQUE_INVALID` | used internally
`UNIQUE_ACTIVATE` | request to activate a currently active instance; this usually means calling `gtk_window_present()` on the application window.
`UNIQUE_NEW` | request to create a new file.
`UNIQUE_OPEN` | request to open a file.
`UNIQUE_CLOSE` | requests to close the currently running instance.

### struct UniqueApp

    struct UniqueApp;

The base class for every single instance application. The UniqueApp structure contains only private data and should be manipulated only with the provided functions.

### struct UniqueAppClass

    struct UniqueAppClass {
      UniqueResponse (* message_received) (UniqueApp         *app,
                                           gint               command,
                                           UniqueMessageData *message_data,
                                           guint              time_);
    };

Base class for every single instance application.

`message_received` () | Signal class closure for the UniqueApp::message_received signal.

### unique_app_new ()

    UniqueApp *         unique_app_new                      (const gchar *name,
                                                             const gchar *startup_id);

Creates a new UniqueApp instance for `name` passing a start-up notification id `startup_id`. The name must be a unique identifier for the application, and it must be in form of a domain name, like `org.gnome.YourApplication`.

If `startup_id` is `NULL` the `DESKTOP_STARTUP_ID` environment variable will be check, and if that fails a "fake" startup notification id will be created.

Once you have created a UniqueApp instance, you should check if any other instance is running, using `unique_app_is_running()`. If another instance is running you can send a command to it, using the `unique_app_send_message()` function; after that, the second instance should quit. If no other instance is running, the usual logic for creating the application can follow.

`name` : | the name of the application's instance
`startup_id` : | the startup notification id, or `NULL`. [allow-none]
Returns : | the newly created UniqueApp instance.

### unique_app_new_with_commands ()

    UniqueApp *         unique_app_new_with_commands        (const gchar *name,
                                                             const gchar *startup_id,
                                                             const gchar *first_command_name,
                                                             ...);

Creates a new UniqueApp instance, with `name` and `startup_id`, and registers a list of custom commands. See `unique_app_new()` and `unique_app_add_command()`.

`name` : | the name of the application
`startup_id` : | startup notification id, or `NULL`. [allow-none]
`first_command_name` : | first custom command
`...` : | `NULL` terminated list of command names and command ids
Returns : | the newly created UniqueApp instance.

### unique_app_add_command ()

    void                unique_app_add_command              (UniqueApp *app,
                                                             const gchar *command_name,
                                                             gint command_id);

Adds `command_name` as a custom command that can be used by `app`. You must call `unique_app_add_command()` before `unique_app_send_message()` in order to use the newly added command.

The command name is used internally: you need to use the command's logical id in `unique_app_send_message()` and inside the UniqueApp::message-received signal.

`app` : | a UniqueApp
`command_name` : | command name
`command_id` : | command logical id

### unique_app_watch_window ()

    void                unique_app_watch_window             (UniqueApp *app,
                                                             GtkWindow *window);

Makes `app` "watch" a window. Every watched window will receive startup notification changes automatically.

`app` : | a UniqueApp
`window` : | the GtkWindow to watch

### unique_app_is_running ()

    gboolean            unique_app_is_running               (UniqueApp *app);

Checks whether another instance of `app` is running.

`app` : | a UniqueApp
Returns : | `TRUE` if there already is an instance running

### enum UniqueResponse

    typedef enum { /*< prefix=UNIQUE_RESPONSE >*/
      UNIQUE_RESPONSE_INVALID = 0,
      UNIQUE_RESPONSE_OK,
      UNIQUE_RESPONSE_CANCEL,
      UNIQUE_RESPONSE_FAIL,
      UNIQUE_RESPONSE_PASSTHROUGH
    } UniqueResponse;

Response that a currently active instance of the application should return to the caller which sent a command.

`UNIQUE_RESPONSE_INVALID` | Internal error code, should never be used.
`UNIQUE_RESPONSE_OK` | The command was successfully executed.
`UNIQUE_RESPONSE_CANCEL` | The command was cancelled by the user.
`UNIQUE_RESPONSE_FAIL` | The command failed due to a IPC failure.
`UNIQUE_RESPONSE_PASSTHROUGH` | The command was not handled

### unique_app_send_message ()

    UniqueResponse      unique_app_send_message             (UniqueApp *app,
                                                             gint command_id,
                                                             UniqueMessageData *message_data);

Sends `command` to a running instance of `app`. If you need to pass data to the instance, you should create a UniqueMessageData object using `unique_message_data_new()` and then fill it with the data you intend to pass.

The running application will receive a UniqueApp::message-received signal and will call the various signal handlers attach to it. If any handler returns a UniqueResponse different than `UNIQUE_RESPONSE_OK`, the emission will stop.

`app` : | a UniqueApp
`command_id` : | command to send
`message_data` : | UniqueMessageData, or `NULL`. [allow-none]
Returns : | The UniqueResponse returned by the running instance

## Property Details

### The `"is-running"` property

      "is-running"               gboolean              : Read

Whether another instance of the application is running.

Default value: FALSE

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

The unique name of the application. It must be in form of a domain-like string, like `org.gnome.MyApplication`.

Default value: NULL

### The `"screen"` property

      "screen"                   GdkScreen*            : Read / Write / Construct

The GdkScreen of the application.

### The `"startup-id"` property

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

The startup notification id, needed to complete the startup notification sequence. If not set, a default id will be automatically given.

Default value: NULL

## Signal Details

### The `"message-received"` signal

    UniqueResponse      user_function                      (UniqueApp         *app,
                                                            gint               command,
                                                            UniqueMessageData *message_data,
                                                            guint              time_,
                                                            gpointer           user_data)         : No Hooks

The ::message-received signal is emitted each time a second instance of UniqueApp with the same name as `app` is launched and sends a message using `unique_app_send_message()`. The currently running instance should check `command` for the action to execute and `message_data` for eventual other parameters (see UniqueMessageData).

The signal handler should return a UniqueResponse value depending on whether the command was successfully completed or not. If the `UNIQUE_RESPONSE_PASSTHROUGH` return value is used, the signal emission chain will continue until another handler will return another response code.

`app` : | the object which received the signal
`command` : | command received
`message_data` : | message data
`time_` : | timestamp of the command
`user_data` : | user data set when the signal handler was connected.
Returns : | a UniqueResponse