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.

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.

enum 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

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.

enum UniqueResponse

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

The “is-running” property

  “is-running”               gboolean

Whether another instance of the application is running.

Flags: Read

Default value: FALSE

The “name” property

  “name”                     gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL

The “screen” property

  “screen”                   GdkScreen *

The GdkScreen of the application.

Flags: Read / Write / Construct

The “startup-id” property

  “startup-id”               gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL

The “message-received” signal

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

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.

Flags: No Hooks