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