NAME¶
Gtk2::UniqueApp - Base class for singleton applications
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();
}
DESCRIPTION¶
Gtk2::UniqueApp is the base class for single instance applications. You
can either create an instance of UniqueApp via
"Gtk2::UniqueApp->new()" and
"Gtk2::UniqueApp->_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
"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
"Gtk2::UniqueApp:name" property is required, and should be in the
form of a domain name, like
org.gnome.YourApplication.
After the creation, you should check whether an instance of your application is
already running, using "Gtk2::UniqueApp::is_running()"; if this
method returns "FALSE" the usual application construction sequence
can continue; if it returns "TRUE" you can either exit or send a
message using Gtk2::UniqueMessageData and
"Gtk2::UniqueMessageData::send_message()".
You can define custom commands using "Gtk2::UniqueApp::add_command()":
you need to provide an arbitrary integer and a string for the command.
HIERARCHY¶
Glib::Object
+----Gtk2::UniqueApp
METHODS¶
uniqueapp = Gtk2::UniqueApp-> new ($name, $startup_id, ...)¶
- •
- $name (string)
- •
- $startup_id (string or undef)
- •
- ... (list)
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
org.gnome.YourApplication.
If startup_id is "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 "Gtk2::UniqueApp::is_running()". If
another instance is running you can send a command to it, using the
"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.
uniqueapp = Gtk2::UniqueApp-> new_with_commands ($name, $startup_id, ...)¶
- •
- $name (string)
- •
- $startup_id (string or undef)
- •
- ... (list)
An alias for "Gtk2::UniqueApp->new()".
$app->add_command ($command_name, $command_id)¶
- •
- $command_name (string)
- •
- $command_id (integer)
Adds command_name as a custom command that can be used by app. You must call
"Gtk2::UniqueApp::add_command()" before
"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
"Gtk2::UniqueApp::send_message()" and inside the
message-received signal.
boolean = $app-> is_running¶
Checks whether another instance of app is running.
uniqueresponse = $app-> send_message ($command, ...)¶
- •
- $command (scalar)
- •
- ... (list)
Same as "Gkt2::UniqueApp::send_message_by_name()", but uses a message
id instead of a name.
uniqueresponse = $app-> send_message_by_name ($command, ...)¶
- •
- $command (scalar)
- •
- ... (list)
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:
- text
- A plain text message
- data
- Rad data
- filename
- A file name
- uris
- URI, multiple values can be passed
The running application will receive a
message-received signal and will
call the various signal handlers attach to it. If any handler returns a
"Gtk2::UniqueResponse" different than "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/',
);
NOTE: If you prefer to use an ID instead of a message name then use the
function "Gkt2::UniqueApp::send_message()". The usage is the same as
this one.
$app->watch_window ($window)¶
- •
- $window (Gtk2::Window)
Makes app "watch" a window. Every watched window will receive startup
notification changes automatically.
PROPERTIES¶
- 'is-running' (boolean : default false : readable / private)
- Whether another instance is running
- 'name' (string : default undef : readable / writable / construct-only /
private)
- The unique name of the application
- 'screen' (Gtk2::Gdk::Screen : default undef : readable / writable /
construct / private)
- The GdkScreen of the application
- 'startup-id' (string : default undef : readable / writable /
construct-only / private)
- The startup notification id for the application
SIGNALS¶
- Gtk2::UniqueResponse = message-received (Gtk2::UniqueApp, integer,
Gtk2::UniqueMessageData, Glib::UInt)
ENUMS AND FLAGS¶
enum Gtk2::UniqueResponse¶
- •
- 'invalid' / 'UNIQUE_RESPONSE_INVALID'
- •
- 'ok' / 'UNIQUE_RESPONSE_OK'
- •
- 'cancel' / 'UNIQUE_RESPONSE_CANCEL'
- •
- 'fail' / 'UNIQUE_RESPONSE_FAIL'
- •
- 'passthrough' / 'UNIQUE_RESPONSE_PASSTHROUGH'
SEE ALSO¶
Gtk2::Unique, Glib::Object
COPYRIGHT¶
Copyright (C) 2009-2010 by Emmanuel Rodriguez