--- name: "Gtk2::UniqueApp" section: "3pm" platform: "linux" package: "libgtk2-unique-perl" version: "0.05-2+b3" release: "Debian 9 (Stretch)" platforms: ["linux"] url: "https://new.carta.tech/Gtk2::UniqueApp" --- # Gtk2::UniqueApp(3pm) Base class for singleton applications ## 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