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 unique_command_register() before creating the UniqueApp instance.

UniqueApp

typedef struct _UniqueApp 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.

UniqueAppClass

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

Base class for every single instance application.

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.

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

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.

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.

unique_app_is_running ()

gboolean            unique_app_is_running               (UniqueApp *app);

Checks whether another instance of app is running.

enum UniqueResponse

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

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

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.

The "is-running" property

  "is-running"               gboolean              : Read

Whether another instance of the application is running.

Default value: FALSE

The "name" property

  "name"                     gchararray            : 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"               gchararray            : 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

The "message-received" signal

UniqueResponse      user_function                      (UniqueApp         *app,
                                                        gint               command,
                                                        UniqueMessageData *message_data,
                                                        guint              time_,
                                                        gpointer           user_data)         : Run Last / No Recursion / 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.