This file is indexed.

/usr/lib/perl5/Gtk2/UniqueApp.pod is in libgtk2-unique-perl 0.05-1build2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
=head1 NAME

Gtk2::UniqueApp - Base class for singleton applications

=cut

=for position SYNOPSIS

=head1 SYNOPSIS

	my $app = Gtk2::UniqueApp->new(
		"org.example.UnitTets", undef,
		foo => $COMMAND_FOO,
		bar => $COMMAND_BAR,
	);
	if ($app->is_running) {
		# The application is already running, send it a message
		$app->send_message_by_name('foo', text => "Hello world");
	}
	else {
		my $window = Gtk2::Window->new();
		my $label = Gtk2::Label->new("Waiting for a message");
		$window->add($label);
		$window->set_size_request(480, 120);
		$window->show_all();

		$window->signal_connect(delete_event => sub {
			Gtk2->main_quit();
			return TRUE;
		});

		# Watch the main window and register a handler that will be called each time
		# that there's a new message.
		$app->watch_window($window);
		$app->signal_connect('message-received' => sub {
			my ($app, $command, $message, $time) = @_;
			$label->set_text($message->get_text);
			return 'ok';
		});

		Gtk2->main();
	}

=for position DESCRIPTION

=head1 DESCRIPTION

B<Gtk2::UniqueApp> is the base class for single instance applications. You can
either create an instance of UniqueApp via C<Gtk2::UniqueApp-E<gt>new()> and
C<Gtk2::UniqueApp-E<gt>_with_commands()>; or you can subclass Gtk2::UniqueApp
with your own application class.

A Gtk2::UniqueApp instance is guaranteed to either be the first running at the
time of creation or be able to send messages to the currently running instance;
there is no race possible between the creation of the Gtk2::UniqueApp instance
and the call to C<Gtk2::UniqueApp::is_running()>.

The usual method for using the Gtk2::UniqueApp API is to create a new instance,
passing an application-dependent name as construction-only property; the
C<Gtk2::UniqueApp:name> property is required, and should be in the form of a
domain name, like I<org.gnome.YourApplication>.

After the creation, you should check whether an instance of your application is
already running, using C<Gtk2::UniqueApp::is_running()>; if this method returns
C<FALSE> the usual application construction sequence can continue; if it returns
C<TRUE> you can either exit or send a message using L<Gtk2::UniqueMessageData>
and C<Gtk2::UniqueMessageData::send_message()>.

You can define custom commands using C<Gtk2::UniqueApp::add_command()>: you need
to provide an arbitrary integer and a string for the command.

=cut



=head1 HIERARCHY

  Glib::Object
  +----Gtk2::UniqueApp



=cut

=for object Gtk2::UniqueApp - Base class for singleton applications
=cut




=head1 METHODS

=head2 uniqueapp = Gtk2::UniqueApp-E<gt>B<new> ($name, $startup_id, ...)

=over

=item * $name (string) 

=item * $startup_id (string or undef) 

=item * ... (list) 

=back


Creates a new Gtk2::UniqueApp instance for name passing a start-up notification
id startup_id. The name must be a unique identifier for the application, and it
must be in form of a domain name, like I<org.gnome.YourApplication>.

If startup_id is C<undef> the DESKTOP_STARTUP_ID environment variable will be
check, and if that fails a "fake" startup notification id will be created.

Once you have created a Gtk2::UniqueApp instance, you should check if any other
instance is running, using C<Gtk2::UniqueApp::is_running()>. If another
instance is running you can send a command to it, using the
C<Gtk2::UniqueApp::send_message()> function; after that, the second instance
should quit. If no other instance is running, the usual logic for creating the
application can follow.


=head2 uniqueapp = Gtk2::UniqueApp-E<gt>B<new_with_commands> ($name, $startup_id, ...)

=over

=item * $name (string) 

=item * $startup_id (string or undef) 

=item * ... (list) 

=back


An alias for C<Gtk2::UniqueApp-E<gt>new()>.


=head2 $app-E<gt>B<add_command> ($command_name, $command_id)

=over

=item * $command_name (string) 

=item * $command_id (integer) 

=back


Adds command_name as a custom command that can be used by app. You must call
C<Gtk2::UniqueApp::add_command()> before C<Gtk2::UniqueApp::send_message()> in
order to use the newly added command.

The command name is used internally: you need to use the command's logical id in
C<Gtk2::UniqueApp::send_message()> and inside the I<message-received> signal.


=head2 boolean = $app-E<gt>B<is_running> 


Checks whether another instance of app is running.


=head2 uniqueresponse = $app-E<gt>B<send_message> ($command, ...)

=over

=item * $command (scalar) 

=item * ... (list) 

=back


Same as C<Gkt2::UniqueApp::send_message_by_name()>, but uses a message id
instead of a name.


=head2 uniqueresponse = $app-E<gt>B<send_message_by_name> ($command, ...)

=over

=item * $command (scalar) 

=item * ... (list) 

=back


Sends command to a running instance of app. If you need to pass data to the
instance, you have to indicate the type of message that will be passed. The
accepted types are:

=over

=item text

A plain text message

=item data

Rad data

=item filename

A file name

=item uris

URI, multiple values can be passed

=back

The running application will receive a I<message-received> signal and will call
the various signal handlers attach to it. If any handler returns a
C<Gtk2::UniqueResponse> different than C<ok>, the emission will stop.

Usages:

	$app->send_message_by_name(write => data => $data);
	$app->send_message_by_name(greet => text => "Hello World!");
	$app->send_message_by_name(open  => uris =>
		'http://search.cpan.org/',
		'http://www.gnome.org/',
	);

B<NOTE>: If you prefer to use an ID instead of a message name then use the
function C<Gkt2::UniqueApp::send_message()>. The usage is the same as this one.


=head2 $app-E<gt>B<watch_window> ($window)

=over

=item * $window (Gtk2::Window) 

=back


Makes app "watch" a window. Every watched window will receive startup notification changes automatically.




=cut


=head1 PROPERTIES

=over

=item 'is-running' (boolean : default false : readable / private)

Whether another instance is running

=item 'name' (string : default undef : readable / writable / construct-only / private)

The unique name of the application

=item 'screen' (Gtk2::Gdk::Screen : default undef : readable / writable / construct / private)

The GdkScreen of the application

=item 'startup-id' (string : default undef : readable / writable / construct-only / private)

The startup notification id for the application

=back



=cut


=head1 SIGNALS

=over

=item Gtk2::UniqueResponse = B<message-received> (Gtk2::UniqueApp, integer, Gtk2::UniqueMessageData, Glib::UInt)

=back



=cut


=head1 ENUMS AND FLAGS

=head2 enum Gtk2::UniqueResponse

=over

=item * 'invalid' / 'UNIQUE_RESPONSE_INVALID'

=item * 'ok' / 'UNIQUE_RESPONSE_OK'

=item * 'cancel' / 'UNIQUE_RESPONSE_CANCEL'

=item * 'fail' / 'UNIQUE_RESPONSE_FAIL'

=item * 'passthrough' / 'UNIQUE_RESPONSE_PASSTHROUGH'

=back




=cut


=head1 SEE ALSO

L<Gtk2::Unique>, L<Glib::Object>


=cut


=head1 COPYRIGHT

Copyright (C) 2009-2010 by Emmanuel Rodriguez


=cut