Migrating from libunique to GApplication or GtkApplication
libunique offers 'unique application' support as well as ways to
communicate with a running application instance. This is implemented
in various ways, either using D-Bus, or socket-based communication.
Starting with GLib 2.26, D-Bus support has been integrated into GIO
in the form of GDBus, and #GApplication has been added to provide
the same level of application support as libunique.
A unique application
Here is a simple application using libunique:
int
main (int argc, char *argv[])
{
UniqueApp *app;
GtkWidget *window;
gtk_init (&argc, &argv);
app = unique_app_new ("org.gtk.TestApplication", NULL);
if (unique_app_is_running (app))
{
UniqueResponse response;
response = unique_app_send_message (app, UNIQUE_ACTIVATE, NULL);
g_object_unref (app);
return response == UNIQUE_RESPONSE_OK ? 0 : 1;
}
window = create_my_window ();
unique_app_watch_window (app, GTK_WINDOW (window));
gtk_widget_show (window);
gtk_main ();
g_object_unref (app);
return 0;
}
The same application using GtkApplication:
static void
activate (GtkApplication *app)
{
GList *list;
GtkWidget *window;
list = gtk_application_get_windows (app);
if (list)
{
gtk_window_present (GTK_WINDOW (list->data));
}
else
{
window = create_my_window ();
gtk_window_set_application (GTK_WINDOW (window), app);
gtk_widget_show (window);
}
}
int
main (int argc, char *argv[])
{
GtkApplication *app;
gint status;
app = gtk_application_new ("org.gtk.TestApplication", 0);
g_signal_connect (app, "activate", G_CALLBACK (activate), NULL);
status = g_application_run (G_APPLICATION (app), argc, argv);
g_object_unref (app);
return status;
}
Uniqueness
Instead of creating a #UniqueApp with unique_app_new(), create
a #GApplication with g_application_new() or a #GtkApplication
with gtk_application_new(). The @name that was used with
unique_app_new() is very likely usable as the @application_id for
g_application_new() without any changes, and GtkApplication passes
the DESKTOP_STARTUP_ID environment variable
automatically.
While libunique expects you to check for an already running instance
yourself and activate it manually, GApplication handles all this on
its own in g_application_run(). If you still need to find out if there
is a running instance of your application, use
g_application_get_is_remote() instead of unique_app_is_running().
Commands and Messages
libunique lets you send messages with commands to a running
instance using unique_app_send_message(). The commands can be either
predefined or custom. Some of the predefined libunique commands have
equivalents in GApplication. Instead of sending the %UNIQUE_ACTIVATE
command, call g_application_activate(), instead of sending the
%UNIQUE_OPEN command, call g_application_open(). The
%UNIQUE_NEW and %UNIQUE_CLOSE and user-defined commands don't
have direct replacement at this time.
As a replacement for custom commands, GApplication implements the
#GActionGroup interface and lets you add a group of actions with
g_application_set_action_group(). The actions can then be invoked,
either by using the D-Bus interface for #GAction directly, or by
calling g_action_group_activate_action() from another instance of
the GApplication. The #GApplication documentation contains an
example for using GApplication with actions.
For more complex needs, GApplication supports passing entire
commandlines to the running instance.