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               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
25                       $window->signal_connect(delete_event => sub {
26                               Gtk2->main_quit();
27                               return TRUE;
28                       });
29
30                       # 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
39                       Gtk2->main();
40               }
41

DESCRIPTION

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
48       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
54       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
59       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
66       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

HIERARCHY

70         Glib::Object
71         +----Gtk2::UniqueApp
72

METHODS

74   uniqueapp = Gtk2::UniqueApp->new ($name, $startup_id, ...)
75       ·   $name (string)
76
77       ·   $startup_id (string or undef)
78
79       ·   ... (list)
80
81       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
86       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
90       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
97   uniqueapp = Gtk2::UniqueApp->new_with_commands ($name, $startup_id, ...)
98       ·   $name (string)
99
100       ·   $startup_id (string or undef)
101
102       ·   ... (list)
103
104       An alias for "Gtk2::UniqueApp->new()".
105
106   $app->add_command ($command_name, $command_id)
107       ·   $command_name (string)
108
109       ·   $command_id (integer)
110
111       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
116       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
120   boolean = $app->is_running
121       Checks whether another instance of app is running.
122
123   uniqueresponse = $app->send_message ($command, ...)
124       ·   $command (scalar)
125
126       ·   ... (list)
127
128       Same as "Gkt2::UniqueApp::send_message_by_name()", but uses a message
129       id instead of a name.
130
131   uniqueresponse = $app->send_message_by_name ($command, ...)
132       ·   $command (scalar)
133
134       ·   ... (list)
135
136       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
140       text
141           A plain text message
142
143       data
144           Rad data
145
146       filename
147           A file name
148
149       uris
150           URI, multiple values can be passed
151
152       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
156       Usages:
157
158               $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
165       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
169   $app->watch_window ($window)
170       ·   $window (Gtk2::Window)
171
172       Makes app "watch" a window. Every watched window will receive startup
173       notification changes automatically.
174

PROPERTIES

176       'is-running' (boolean : readable / private)
177           Whether another instance is running
178
179       'name' (string : readable / writable / construct-only / private)
180           The unique name of the application
181
182       'screen' (Gtk2::Gdk::Screen : readable / writable / construct /
183       private)
184           The GdkScreen of the application
185
186       'startup-id' (string : readable / writable / construct-only / private)
187           The startup notification id for the application
188

SIGNALS

190       Gtk2::UniqueResponse = message-received (Gtk2::UniqueApp, integer,
191       Gtk2::UniqueMessageData, Glib::UInt)
192

ENUMS AND FLAGS

194   enum Gtk2::UniqueResponse
195       ·   'invalid' / 'UNIQUE_RESPONSE_INVALID'
196
197       ·   'ok' / 'UNIQUE_RESPONSE_OK'
198
199       ·   'cancel' / 'UNIQUE_RESPONSE_CANCEL'
200
201       ·   'fail' / 'UNIQUE_RESPONSE_FAIL'
202
203       ·   'passthrough' / 'UNIQUE_RESPONSE_PASSTHROUGH'
204

COPYRIGHT

209       Copyright (C) 2009-2010 by Emmanuel Rodriguez
210
211
212
213perl v5.12.3                      2011-06-22                Gtk2::UniqueApp(3)