![]() |
![]() |
![]() |
GtkUnique Reference Manual | ![]() |
---|---|---|---|---|
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);
"name" gchararray : Read / Write / Construct Only "screen" GdkScreen : Read / Write / Construct "startup-id" gchararray : Read / Write / Construct Only "workspace" guint : Read / Write / Construct
"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
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; }
typedef struct _GtkUniqueApp GtkUniqueApp;
The GtkUniqueApp structure contains only private data and should not be directly accessed.
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;
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 |
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()
.
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. |
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.
|
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.
|
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 |
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 |
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.
|
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 |
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 |
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 |
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 |
name
" property"name" gchararray : Read / Write / Construct Only
The unique name of the GtkUniqueApp object.
Default value: NULL
screen
" property"screen" GdkScreen : Read / Write / Construct
The GdkScreen of the application.
startup-id
" property"startup-id" gchararray : Read / Write / Construct Only
The startup notification id used by the application instance.
Default value: NULL
workspace
" property"workspace" guint : Read / Write / Construct
The workspace of the application.
Default value: 0
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. |