GtkUniqueApp

GtkUniqueApp — Base class for single instance applications

Synopsis




            GtkUniqueApp;
            GtkUniqueAppClass;
enum        GtkUniqueCommand;
enum        GtkUniqueResponse;
GtkUniqueApp* gtk_unique_app_new            (const gchar *name);
GtkUniqueApp* gtk_unique_app_new_with_id    (const gchar *name,
                                             const gchar *startup_id);
gboolean    gtk_unique_app_is_running       (GtkUniqueApp *app);
void        gtk_unique_app_add_window       (GtkUniqueApp *app,
                                             GtkWindow *window);
void        gtk_unique_app_remove_window    (GtkUniqueApp *app,
                                             GtkWindow *window);
GSList*     gtk_unique_app_list_windows     (GtkUniqueApp *app);
GtkUniqueResponse gtk_unique_app_send_message
                                            (GtkUniqueApp *app,
                                             GtkUniqueCommand command,
                                             const gchar *data);
GtkUniqueResponse gtk_unique_app_activate   (GtkUniqueApp *app);
GtkUniqueResponse gtk_unique_app_new_document
                                            (GtkUniqueApp *app);
GtkUniqueResponse gtk_unique_app_open_uri   (GtkUniqueApp *app,
                                             const gchar *uri);


Object Hierarchy


  GObject
   +----GtkUniqueApp

Properties


  "name"                 gchararray            : Read / Write / Construct Only
  "screen"               GdkScreen             : Read / Write / Construct
  "startup-id"           gchararray            : Read / Write / Construct Only
  "workspace"            guint                 : Read / Write / Construct

Signals


"message"   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

Description

GtkUniqueApp is the base class for creating single instance applications.

You should create a new GtkUniqueApp and check whether there is another instance with the same name running using gtk_unique_app_is_running(). If none is running, you can go on with the usual application initialization sequence. If another instance is running, instead, you can send it a message using gtk_unique_app_send_message() or one of its wrapper functions and then exit.

A typical GtkUniqueApp based application is shown in the example:

Example 1. Using GtkUniqueApp.

  static GtkUniqueResponse
  app_message_cb (GtkUniqueApp *app,
                  GtkUniqueCommand  command,
                  const gchar      *command_data,
                  const gchar      *startup_id,
                  GdkScreen        *screen,
                  guint             workspace,
                  gpointer          user_data)
  {
    GtkWidget *main_window = GTK_WINDOW (user_data);

    switch (command)
      {
      case GTK_UNIQUE_NEW:
        /* create a new window, set the parent */
        break;
      case GTK_UNIQUE_ACTIVATE:
        /* move the main window to the screen and call
         * gtk_window_present()
         */
        break;
      case GTK_UNIQUE_OPEN:
        /* unhandled */
        return GTK_UNIQUE_RESPONSE_CANCEL;
      default:
        /* error */
        return GTK_UNIQUE_RESPONSE_ABORT;
      }

    return GTK_UNIQUE_RESPONSE_OK;
  }

  int
  main (int argc, char *argv)
  {
    GtkUniqueApp *app;

    gtk_init (&argc, &argv);

    app = gtk_unique_app_new ("org.gnome.MyApplication");
    if (gtk_unique_app_is_running (app))
      {
        /* this will send a message to the running instance */
        GtkUniqueResponse response;

        response = gtk_unique_app_send_message (app, GTK_UNIQUE_ACTIVATE);
        exit (response == GTK_UNIQUE_RESPONSE_OK);
      }
    else
      {
        /* continue the loading of you application */
        GtkWidget *main_window;
  
        main_window = create_main_window();
        gtk_unique_app_add_window (app, GTK_WINDOW (main_window));
        gtk_widget_show_all (main_window);

        g_signal_connect (app, "message",
                          G_CALLBACK (app_message_cb),
                          main_window);
      }

    gtk_main();

    g_object_unref (app);

    return 0;
  }

Details

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

GTK_UNIQUE_ACTIVATE Bring the application upfront (mostly using gtk_window_present())
GTK_UNIQUE_NEW Create a new window
GTK_UNIQUE_OPEN Open a document
GTK_UNIQUE_CUSTOM Custom command
GTK_UNIQUE_INVALID Reserved for debug and internal usage

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_RESPONSE_OK The command was successfully executed
GTK_UNIQUE_RESPONSE_CANCEL The command was cancelled by the user
GTK_UNIQUE_RESPONSE_ABORT The command was cancelled by the system
GTK_UNIQUE_RESPONSE_FAIL The command was not sent due to a communication failure; this is used internally and should not be used by applications
GTK_UNIQUE_RESPONSE_INVALID Reserved for debug and internal usage

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.

name : the name of the application's instance
Returns : the newly created GtkUniqueApp instance.

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

name : the name of the application
startup_id : the startup id or NULL
Returns : the newly created GtkUniqueApp instance. Use g_object_unref() when finished.

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.

app : a GtkUniqueApp
Returns : TRUE if another instance is 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.

app : a GtkUniqueApp
window : a GtkWindow

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.

app : a GtkUniqueApp
window : a GtkWindow

gtk_unique_app_list_windows ()

GSList*     gtk_unique_app_list_windows     (GtkUniqueApp *app);

Retrieves the list of windows watched by app.

app : a GtkUniqueApp
Returns : a list of windows. You should free the list with g_slist_free() when done.

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.

app : a GtkUniqueApp
command : a command you want to send
data : optional data for the command, or NULL
Returns : a GtkUniqueResponse

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.

app : a GtkUniqueApp
Returns : a GtkUniqueResponse

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.

app : a GtkUniqueApp
Returns : a GtkUniqueResponse

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.

app : a GtkUniqueApp
uri : a valid URI, or NULL
Returns : a GtkUniqueResponse

Property Details

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

Signal Details

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.

app : the object that received the signal
command : the command received
command_data : data passed to the command or NULL
startup_id : start-up id of the instance sending us the command
screen : the GdkScreen of the instance sending us the command
workspace : workspace of the instance sending us the command
user_data : user data set when the signal handler was connected.
Returns : a GtkUniqueResponse value, depending on how the GtkUniqueCommand received was handled.