Pileus Git - ~andy/gtk/blob - docs/reference/gtk/migrating-unique-GtkApplication.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   4 ]>
   5 <chapter id="gtk-migrating-unique-GtkApplication">
   6
   7   <title>Migrating from libunique to GApplication or GtkApplication</title>
   8
   9   <para>
  10     libunique offers 'unique application' support as well as ways to
  11     communicate with a running application instance. This is implemented
  12     in various ways, either using D-Bus, or socket-based communication.
  13   </para>
  14
  15   <para>
  16     Starting with GLib 2.26, D-Bus support has been integrated into GIO
  17     in the form of GDBus, and #GApplication has been added to provide
  18     the same level of application support as libunique.
  19   </para>
  20
  21   <example><title>A unique application</title>
  22   <para>Here is a simple application using libunique:
  23   <programlisting>
  24 int
  25 main (int argc, char *argv[])
  26 {
  27   UniqueApp *app;
  28   GtkWidget *window;
  29
  30   gtk_init (&amp;argc, &amp;argv);
  31
  32   app = unique_app_new ("org.gtk.TestApplication", NULL);
  33
  34   if (unique_app_is_running (app))
  35     {
  36       UniqueResponse response;
  37
  38       response = unique_app_send_message (app, UNIQUE_ACTIVATE, NULL);
  39       g_object_unref (app);
  40
  41       return response == UNIQUE_RESPONSE_OK ? 0 : 1;
  42     }
  43
  44   window = create_my_window ();
  45
  46   unique_app_watch_window (app, GTK_WINDOW (window));
  47
  48   gtk_widget_show (window);
  49
  50   gtk_main ();
  51
  52   g_object_unref (app);
  53
  54   return 0;
  55 }
  56 </programlisting>
  57 The same application using GtkApplication:
  58 <programlisting>
  59 static void
  60 activate (GtkApplication *app)
  61 {
  62   GList *list;
  63   GtkWidget *window;
  64
  65   list = gtk_application_get_windows (app);
  66
  67   if (list)
  68     {
  69       gtk_window_present (GTK_WINDOW (list->data));
  70     }
  71   else
  72     {
  73       window = create_my_window ();
  74       gtk_window_set_application (GTK_WINDOW (window), app);
  75       gtk_widget_show (window);
  76     }
  77 }
  78
  79 int
  80 main (int argc, char *argv[])
  81 {
  82   GtkApplication *app;
  83   gint status;
  84
  85   app = gtk_application_new ("org.gtk.TestApplication", 0);
  86   g_signal_connect (app, "activate", G_CALLBACK (activate), NULL);
  87
  88   status = g_application_run (app);
  89
  90   g_object_unref (app);
  91
  92   return status;
  93 }
  94 </programlisting>
  95 </para>
  96 </example>
  97   <section><title>Uniqueness</title>
  98     <para>
  99       Instead of creating a #UniqueApp with unique_app_new(), create
 100       a #GApplication with g_application_new() or a #GtkApplication
 101       with gtk_application_new(). The @name that was used with
 102       unique_app_new() is very likely usable as the @application_id for
 103       g_application_new() without any changes, and GtkApplication passes
 104       the <envar>DESKTOP_STARTUP_ID</envar> environment variable
 105       automatically.
 106     </para>
 107     <para>
 108       While libunique expects you to check for an already running instance
 109       yourself and activate it manually, GApplication handles all this on
 110       its own in g_application_run(). If you still need to find out if there
 111       is a running instance of your application, use
 112       g_application_get_is_remote() instead of unique_app_is_running().
 113     </para>
 114   </section>
 115
 116   <section><title>Commands and Messages</title>
 117     <para>
 118       libunique lets you send messages with commands to a running
 119       instance using unique_app_send_message(). The commands can be either
 120       predefined or custom. Some of the predefined libunique commands have
 121       equivalents in GApplication. Instead of sending the %UNIQUE_ACTIVATE
 122       command, call g_application_activate(), instead of sending the
 123       %UNIQUE_OPEN command, call g_application_open(). The
 124       %UNIQUE_NEW and %UNIQUE_CLOSE and user-defined commands don't
 125       have direct replacement at this time.
 126     </para>
 127
 128     <para>
 129       As a replacement for custom commands, GApplication implements the
 130       #GActionGroup interface and lets you add a group of actions with
 131       g_application_set_action_group(). The actions can then be invoked,
 132       either by using the D-Bus interface for #GAction directly, or by
 133       calling g_action_group_activate_action() from another instance of
 134       the GApplication. The #GApplication documentation contains an
 135       example for using GApplication with actions.
 136     </para>
 137
 138     <para>
 139       For more complex needs, GApplication supports passing entire
 140       commandlines to the running instance.
 141     </para>
 142   </section>
 143 </chapter>