1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<chapter id="gtk-migrating-GtkApplication">
<title>Migrating from libunique to GApplication or GtkApplication</title>
<para>
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.
</para>
<para>
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.
</para>
<example><title>A unique application</title>
<para>Here is a simple application using libunique:
<programlisting>
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;
}
</programlisting>
The same application using GtkApplication:
<programlisting>
static void
activate (GtkApplication *app)
{
GtkWidget *window;
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 (app);
g_object_unref (app);
return status;
}
</programlisting>
</para>
</example>
<section><title>Uniqueness</title>
<para>
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 <envar>DESKTOP_STARTUP_ID</envar> environment variable
automatically.
</para>
<para>
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().
</para>
</section>
<section><title>Commands and Messages</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
For more complex needs, GApplication supports passing entire
commandlines to the running instance.
</para>
</section>
</chapter>
|
