SYNOPSIS

    use Gtk2 '-init';
    use Gtk2::Unique;

    my $COMMAND_FOO = 1;
    my $COMMAND_BAR = 2;

	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.

An alias for Gtk2::UniqueApp->new().

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.

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.

Makes app "watch" a window. Every watched window will receive startup notification changes automatically.

Checks whether another instance of app is running.

Same as Gkt2::UniqueApp::send_message_by_name(), but uses a message id instead of a name.

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.