UniqueApp

UniqueApp — Base class for singleton applications

Functions

Properties

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

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── UniqueApp

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.

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

Functions

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.

Parameters

name

the name of the application's instance

 

startup_id

the startup notification id, or NULL

 

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

Parameters

name

the name of the application

 

startup_id

startup notification id, or NULL

 

first_command_name

first custom command

 

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.

Parameters

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.

Parameters

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.

Parameters

app

a UniqueApp

 

Returns

TRUE if there already is an instance 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.

Parameters

app

a UniqueApp

 

command_id

command to send

 

message_data

UniqueMessageData, or NULL

 

Returns

The UniqueResponse returned by the running instance

Types and Values

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

Members

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.

Members

message_received ()

Signal class closure for the UniqueApp::message_received signal.

 

enum UniqueResponse

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

Members

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

 

Property Details

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

Signal Details

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.

Parameters

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.

 

Flags: No Hooks