Gtk2::UniqueApp(3) Base class for singleton applications


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->set_size_request(480, 120);
$window->signal_connect(delete_event => sub {
return TRUE;
# Watch the main window and register a handler that will be called each time
# that there's a new message.
$app->signal_connect('message-received' => sub {
my ($app, $command, $message, $time) = @_;
return 'ok';


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.




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:

A plain text message
Rad data
A file name
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.


        $app->send_message_by_name(write => data => $data);
        $app->send_message_by_name(greet => text => "Hello World!");
        $app->send_message_by_name(open  => uris =>

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.


'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


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


enum Gtk2::UniqueResponse



Copyright (C) 2009-2010 by Emmanuel Rodriguez