GtkUniqueApp

typedef struct _GtkUniqueApp GtkUniqueApp;

The GtkUniqueApp structure contains only private data and should not be directly accessed.

GtkUniqueAppClass

typedef struct {
  GObjectClass parent_class;

  /* signals */
  GtkUniqueResponse (*message) (GtkUniqueApp     *app,
                                GtkUniqueCommand  command,
                                const gchar      *command_data,
                                const gchar      *startup_id,
                                GdkScreen        *screen,
                                guint             workspace);

  /* padding for future expansion */
  void (*_gtk_unique1) (void);
  void (*_gtk_unique2) (void);
  void (*_gtk_unique3) (void);
  void (*_gtk_unique4) (void);
} GtkUniqueAppClass;

enum GtkUniqueCommand

typedef enum { /*< prefix=GTK_UNIQUE >*/
  GTK_UNIQUE_ACTIVATE,
  GTK_UNIQUE_NEW,
  GTK_UNIQUE_OPEN,
  GTK_UNIQUE_CUSTOM,

  GTK_UNIQUE_INVALID
} GtkUniqueCommand;

The available commands for gtk_unique_app_send_command().

enum GtkUniqueResponse

typedef enum { /*< prefix=GTK_UNIQUE_RESPONSE >*/
  GTK_UNIQUE_RESPONSE_OK,
  GTK_UNIQUE_RESPONSE_CANCEL,
  GTK_UNIQUE_RESPONSE_ABORT,
  GTK_UNIQUE_RESPONSE_FAIL,

  GTK_UNIQUE_RESPONSE_INVALID
} GtkUniqueResponse;

The available responses for gtk_unique_app_send_command().

gtk_unique_app_new ()

GtkUniqueApp* gtk_unique_app_new            (const gchar *name);

Creates a new GtkUniqueApp instance for name. The name must be a unique identifier for the application, and must be in form of a path, like /org/gnome/YourApplication. Once you have created a GtkUniqueApp instance you should check if any other instance is running, using gtk_unique_app_is_running(). If another instance is running you can send a command to it, using the gtk_unique_app_send_message() function or one of its convience wrappers.

gtk_unique_app_new_with_id ()

GtkUniqueApp* gtk_unique_app_new_with_id    (const gchar *name,
                                             const gchar *startup_id);

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

Once you have created a GtkUniqueApp instance you should check if any other instance is running, using gtk_unique_app_is_running(). If another instance is running you can send a command to it, using the gtk_unique_app_send_message() function or one of its convience wrappers; after that you should quit. If no other instance is running, you can follow the usual application instance sequence; when you create a top-level window for you application you must let the GtkUniqueApp instance "watch" it, by using the function gtk_unique_app_add_window().

gtk_unique_app_is_running ()

gboolean    gtk_unique_app_is_running       (GtkUniqueApp *app);

Checks whether an instance of GtkUniqueApp with the same name passed to gtk_unique_app_new() or gtk_unique_app_new_with_id() is already running.

gtk_unique_app_add_window ()

void        gtk_unique_app_add_window       (GtkUniqueApp *app,
                                             GtkWindow *window);

Adds window to the list of windows watched by app. You should add every newly created main window of your application to a GtkUniqueApp instance, and then remove it when the window is destroyed.

gtk_unique_app_remove_window ()

void        gtk_unique_app_remove_window    (GtkUniqueApp *app,
                                             GtkWindow *window);

Removes window from the list of windows watched by app.

gtk_unique_app_list_windows ()

GSList*     gtk_unique_app_list_windows     (GtkUniqueApp *app);

Retrieves the list of windows watched by app.

gtk_unique_app_send_message ()

GtkUniqueResponse gtk_unique_app_send_message
                                            (GtkUniqueApp *app,
                                             GtkUniqueCommand command,
                                             const gchar *data);

Sends command to an existing instance of GtkUniqueApp with the same name used to create app. If another instance exists it will receive the "message" signal with the corresponding command and data sent.

You should rarely use this function. Unless you wish to send a GTK_UNIQUE_CUSTOM command, you should use the convenience functions gtk_unique_app_new_document(), gtk_unique_app_open_uri() and gtk_unique_app_activate() instead.

gtk_unique_app_activate ()

GtkUniqueResponse gtk_unique_app_activate   (GtkUniqueApp *app);

Sends the GTK_UNIQUE_ACTIVATE command to an existing instance of a GtkUniqueApp with the same name used to create app.

gtk_unique_app_new_document ()

GtkUniqueResponse gtk_unique_app_new_document
                                            (GtkUniqueApp *app);

Sends the GTK_UNIQUE_NEW command to an existing instance of a GtkUniqueApp with the same name used to create app.

gtk_unique_app_open_uri ()

GtkUniqueResponse gtk_unique_app_open_uri   (GtkUniqueApp *app,
                                             const gchar *uri);

Sends the GTK_UNIQUE_OPEN command to an existing instance of a GtkUniqueApp with the same name used to create app.

The "name" property

  "name"                 gchararray            : Read / Write / Construct Only

The unique name of the GtkUniqueApp object.

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 used by the application instance.

Default value: NULL

The "workspace" property

  "workspace"            guint                 : Read / Write / Construct

The workspace of the application.

Default value: 0

The "message" signal

GtkUniqueResponse*user_function                  (GtkUniqueApp     *app,
                                            GtkUniqueCommand *command,
                                            gchar            *command_data,
                                            gchar            *startup_id,
                                            GdkScreen        *screen,
                                            guint             workspace,
                                            gpointer          user_data)         : Run last / No recursion / No hooks

This signal is emitted each time a GtkUniqueApp receives a command from another GtkUniqueApp instance with the same name. You should decide which action you application should implement for each GtkUniqueCommand it may receive. You may also use the workspace, screen and startup_id to handle the window screen positionment and the startup notification sequence.