1Gtk2::UniqueApp(3) User Contributed Perl Documentation Gtk2::UniqueApp(3)
2
6 Gtk2::UniqueApp - Base class for singleton applications
7
9 my $app = Gtk2::UniqueApp->new(
10 "org.example.UnitTets", undef,
11 foo => $COMMAND_FOO,
12 bar => $COMMAND_BAR,
13 );
14 if ($app->is_running) {
15 # The application is already running, send it a message
16 $app->send_message_by_name('foo', text => "Hello world");
17 }
18 else {
19 my $window = Gtk2::Window->new();
20 my $label = Gtk2::Label->new("Waiting for a message");
21 $window->add($label);
22 $window->set_size_request(480, 120);
23 $window->show_all();
24 $window->signal_connect(delete_event => sub {
26 Gtk2->main_quit();
27 return TRUE;
28 });
29 # Watch the main window and register a handler that will be called each time
31 # that there's a new message.
32 $app->watch_window($window);
33 $app->signal_connect('message-received' => sub {
34 my ($app, $command, $message, $time) = @_;
35 $label->set_text($message->get_text);
36 return 'ok';
37 });
38 Gtk2->main();
40 }
41
43 Gtk2::UniqueApp is the base class for single instance applications. You
44 can either create an instance of UniqueApp via "Gtk2::UniqueApp->new()"
45 and "Gtk2::UniqueApp->_with_commands()"; or you can subclass
46 Gtk2::UniqueApp with your own application class.
47 A Gtk2::UniqueApp instance is guaranteed to either be the first running
49 at the time of creation or be able to send messages to the currently
50 running instance; there is no race possible between the creation of the
51 Gtk2::UniqueApp instance and the call to
52 "Gtk2::UniqueApp::is_running()".
53 The usual method for using the Gtk2::UniqueApp API is to create a new
55 instance, passing an application-dependent name as construction-only
56 property; the "Gtk2::UniqueApp:name" property is required, and should
57 be in the form of a domain name, like org.gnome.YourApplication.
58 After the creation, you should check whether an instance of your
60 application is already running, using "Gtk2::UniqueApp::is_running()";
61 if this method returns "FALSE" the usual application construction
62 sequence can continue; if it returns "TRUE" you can either exit or send
63 a message using Gtk2::UniqueMessageData and
64 "Gtk2::UniqueMessageData::send_message()".
65 You can define custom commands using "Gtk2::UniqueApp::add_command()":
67 you need to provide an arbitrary integer and a string for the command.
68
70 Glib::Object
71 +----Gtk2::UniqueApp
72
74 uniqueapp = Gtk2::UniqueApp->new ($name, $startup_id, ...)
75 · $name (string)
76 · $startup_id (string or undef)
78 · ... (list)
80 Creates a new Gtk2::UniqueApp instance for name passing a start-up
82 notification id startup_id. The name must be a unique identifier for
83 the application, and it must be in form of a domain name, like
84 org.gnome.YourApplication.
85 If startup_id is "undef" the DESKTOP_STARTUP_ID environment variable
87 will be check, and if that fails a "fake" startup notification id will
88 be created.
89 Once you have created a Gtk2::UniqueApp instance, you should check if
91 any other instance is running, using "Gtk2::UniqueApp::is_running()".
92 If another instance is running you can send a command to it, using the
93 "Gtk2::UniqueApp::send_message()" function; after that, the second
94 instance should quit. If no other instance is running, the usual logic
95 for creating the application can follow.
96 uniqueapp = Gtk2::UniqueApp->new_with_commands ($name, $startup_id, ...)
98 · $name (string)
99 · $startup_id (string or undef)
101 · ... (list)
103 An alias for "Gtk2::UniqueApp->new()".
105 $app->add_command ($command_name, $command_id)
107 · $command_name (string)
108 · $command_id (integer)
110 Adds command_name as a custom command that can be used by app. You must
112 call "Gtk2::UniqueApp::add_command()" before
113 "Gtk2::UniqueApp::send_message()" in order to use the newly added
114 command.
115 The command name is used internally: you need to use the command's
117 logical id in "Gtk2::UniqueApp::send_message()" and inside the message-
118 received signal.
119 boolean = $app->is_running
121 Checks whether another instance of app is running.
122 uniqueresponse = $app->send_message ($command, ...)
124 · $command (scalar)
125 · ... (list)
127 Same as "Gkt2::UniqueApp::send_message_by_name()", but uses a message
129 id instead of a name.
130 uniqueresponse = $app->send_message_by_name ($command, ...)
132 · $command (scalar)
133 · ... (list)
135 Sends command to a running instance of app. If you need to pass data to
137 the instance, you have to indicate the type of message that will be
138 passed. The accepted types are:
139 text
141 A plain text message
142 data
144 Rad data
145 filename
147 A file name
148 uris
150 URI, multiple values can be passed
151 The running application will receive a message-received signal and will
153 call the various signal handlers attach to it. If any handler returns a
154 "Gtk2::UniqueResponse" different than "ok", the emission will stop.
155 Usages:
157 $app->send_message_by_name(write => data => $data);
159 $app->send_message_by_name(greet => text => "Hello World!");
160 $app->send_message_by_name(open => uris =>
161 'http://search.cpan.org/',
162 'http://www.gnome.org/',
163 );
164 NOTE: If you prefer to use an ID instead of a message name then use the
166 function "Gkt2::UniqueApp::send_message()". The usage is the same as
167 this one.
168 $app->watch_window ($window)
170 · $window (Gtk2::Window)
171 Makes app "watch" a window. Every watched window will receive startup
173 notification changes automatically.
174
176 'is-running' (boolean : default false : readable / private)
177 Whether another instance is running
178 'name' (string : default undef : readable / writable / construct-only /
180 private)
181 The unique name of the application
182 'screen' (Gtk2::Gdk::Screen : default undef : readable / writable /
184 construct / private)
185 The GdkScreen of the application
186 'startup-id' (string : default undef : readable / writable / construct-
188 only / private)
189 The startup notification id for the application
190
192 Gtk2::UniqueResponse = message-received (Gtk2::UniqueApp, integer,
193 Gtk2::UniqueMessageData, Glib::UInt)
194
196 enum Gtk2::UniqueResponse
197 · 'invalid' / 'UNIQUE_RESPONSE_INVALID'
198 · 'ok' / 'UNIQUE_RESPONSE_OK'
200 · 'cancel' / 'UNIQUE_RESPONSE_CANCEL'
202 · 'fail' / 'UNIQUE_RESPONSE_FAIL'
204 · 'passthrough' / 'UNIQUE_RESPONSE_PASSTHROUGH'
206
208 Gtk2::Unique, Glib::Object
209
211 Copyright (C) 2009-2010 by Emmanuel Rodriguez
212perl v5.30.1 2020-01-30 Gtk2::UniqueApp(3)