Gtk2::UniqueApp(3pm)

1Gtk2::UniqueApp(3)    User Contributed Perl Documentation   Gtk2::UniqueApp(3)
2
3
4

NAME

6       Gtk2::UniqueApp - Base class for singleton applications
7

SYNOPSIS

9           use Gtk2 '-init';
10           use Gtk2::Unique;
11
12           my $COMMAND_FOO = 1;
13           my $COMMAND_BAR = 2;
14
15               my $app = Gtk2::UniqueApp->new(
16                       "org.example.UnitTets", undef,
17                       foo => $COMMAND_FOO,
18                       bar => $COMMAND_BAR,
19               );
20               if ($app->is_running) {
21                       # The application is already running, send it a message
22                       $app->send_message_by_name('foo', text => "Hello world");
23               }
24               else {
25                       my $window = Gtk2::Window->new();
26                       my $label = Gtk2::Label->new("Waiting for a message");
27                       $window->add($label);
28                       $window->set_size_request(480, 120);
29                       $window->show_all();
30
31                       $window->signal_connect(delete_event => sub {
32                               Gtk2->main_quit();
33                               return TRUE;
34                       });
35
36                       # Watch the main window and register a handler that will be called each time
37                       # that there's a new message.
38                       $app->watch_window($window);
39                       $app->signal_connect('message-received' => sub {
40                               my ($app, $command, $message, $time) = @_;
41                               $label->set_text($message->get_text);
42                               return 'ok';
43                       });
44
45                       Gtk2->main();
46               }
47

DESCRIPTION

49       Gtk2::UniqueApp is the base class for single instance applications. You
50       can either create an instance of UniqueApp via "Gtk2::UniqueApp->new()"
51       and "Gtk2::UniqueApp->_with_commands()"; or you can subclass
52       Gtk2::UniqueApp with your own application class.
53
54       A Gtk2::UniqueApp instance is guaranteed to either be the first running
55       at the time of creation or be able to send messages to the currently
56       running instance; there is no race possible between the creation of the
57       Gtk2::UniqueApp instance and the call to
58       "Gtk2::UniqueApp::is_running()".
59
60       The usual method for using the Gtk2::UniqueApp API is to create a new
61       instance, passing an application-dependent name as construction-only
62       property; the "Gtk2::UniqueApp:name" property is required, and should
63       be in the form of a domain name, like org.gnome.YourApplication.
64
65       After the creation, you should check whether an instance of your
66       application is already running, using "Gtk2::UniqueApp::is_running()";
67       if this method returns "FALSE" the usual application construction
68       sequence can continue; if it returns "TRUE" you can either exit or send
69       a message using Gtk2::UniqueMessageData and
70       "Gtk2::UniqueMessageData::send_message()".
71
72       You can define custom commands using "Gtk2::UniqueApp::add_command()":
73       you need to provide an arbitrary integer and a string for the command.
74

HIERARCHY

76         Glib::Object
77         +----Gtk2::UniqueApp
78

METHODS

80   uniqueapp = Gtk2::UniqueApp->new ($name, $startup_id, ...)
81       •   $name (string)
82
83       •   $startup_id (string or undef)
84
85       •   ... (list)
86
87       Creates a new Gtk2::UniqueApp instance for name passing a start-up
88       notification id startup_id. The name must be a unique identifier for
89       the application, and it must be in form of a domain name, like
90       org.gnome.YourApplication.
91
92       If startup_id is "undef" the DESKTOP_STARTUP_ID environment variable
93       will be check, and if that fails a "fake" startup notification id will
94       be created.
95
96       Once you have created a Gtk2::UniqueApp instance, you should check if
97       any other instance is running, using "Gtk2::UniqueApp::is_running()".
98       If another instance is running you can send a command to it, using the
99       "Gtk2::UniqueApp::send_message()" function; after that, the second
100       instance should quit. If no other instance is running, the usual logic
101       for creating the application can follow.
102
103   uniqueapp = Gtk2::UniqueApp->new_with_commands ($name, $startup_id, ...)
104       •   $name (string)
105
106       •   $startup_id (string or undef)
107
108       •   ... (list)
109
110       An alias for "Gtk2::UniqueApp->new()".
111
112   $app->add_command ($command_name, $command_id)
113       •   $command_name (string)
114
115       •   $command_id (integer)
116
117       Adds command_name as a custom command that can be used by app. You must
118       call "Gtk2::UniqueApp::add_command()" before
119       "Gtk2::UniqueApp::send_message()" in order to use the newly added
120       command.
121
122       The command name is used internally: you need to use the command's
123       logical id in "Gtk2::UniqueApp::send_message()" and inside the message-
124       received signal.
125
126   boolean = $app->is_running
127       Checks whether another instance of app is running.
128
129   uniqueresponse = $app->send_message ($command, ...)
130       •   $command (scalar)
131
132       •   ... (list)
133
134       Same as "Gkt2::UniqueApp::send_message_by_name()", but uses a message
135       id instead of a name.
136
137   uniqueresponse = $app->send_message_by_name ($command, ...)
138       •   $command (scalar)
139
140       •   ... (list)
141
142       Sends command to a running instance of app. If you need to pass data to
143       the instance, you have to indicate the type of message that will be
144       passed. The accepted types are:
145
146       text
147           A plain text message
148
149       data
150           Rad data
151
152       filename
153           A file name
154
155       uris
156           URI, multiple values can be passed
157
158       The running application will receive a message-received signal and will
159       call the various signal handlers attach to it. If any handler returns a
160       "Gtk2::UniqueResponse" different than "ok", the emission will stop.
161
162       Usages:
163
164               $app->send_message_by_name(write => data => $data);
165               $app->send_message_by_name(greet => text => "Hello World!");
166               $app->send_message_by_name(open  => uris =>
167                       'http://search.cpan.org/',
168                       'http://www.gnome.org/',
169               );
170
171       NOTE: If you prefer to use an ID instead of a message name then use the
172       function "Gkt2::UniqueApp::send_message()". The usage is the same as
173       this one.
174
175   $app->watch_window ($window)
176       •   $window (Gtk2::Window)
177
178       Makes app "watch" a window. Every watched window will receive startup
179       notification changes automatically.
180

PROPERTIES

182       'is-running' (boolean : default false : readable / private / static-
183       nick / static-blurb)
184           Whether another instance is running
185
186       'name' (string : default undef : readable / writable / construct-only /
187       private / static-nick / static-blurb)
188           The unique name of the application
189
190       'screen' (Gtk2::Gdk::Screen : default undef : readable / writable /
191       construct / private / static-nick / static-blurb)
192           The GdkScreen of the application
193
194       'startup-id' (string : default undef : readable / writable / construct-
195       only / private / static-nick / static-blurb)
196           The startup notification id for the application
197

SIGNALS

199       Gtk2::UniqueResponse = message-received (Gtk2::UniqueApp, integer,
200       Gtk2::UniqueMessageData, Glib::UInt)
201

ENUMS AND FLAGS

203   enum Gtk2::UniqueResponse
204       •   'invalid' / 'UNIQUE_RESPONSE_INVALID'
205
206       •   'ok' / 'UNIQUE_RESPONSE_OK'
207
208       •   'cancel' / 'UNIQUE_RESPONSE_CANCEL'
209
210       •   'fail' / 'UNIQUE_RESPONSE_FAIL'
211
212       •   'passthrough' / 'UNIQUE_RESPONSE_PASSTHROUGH'
213

COPYRIGHT

218       Copyright (C) 2009-2017 by Emmanuel Rodriguez
219
220
221
222perl v5.34.0                      2021-07-22                Gtk2::UniqueApp(3)