.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Gtk2::UniqueApp 3pm"
.TH Gtk2::UniqueApp 3pm "2014-04-24" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Gtk2::UniqueApp \- Base class for singleton applications
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&        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(\*(Aqfoo\*(Aq, 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\*(Aqs a new message.
\&                $app\->watch_window($window);
\&                $app\->signal_connect(\*(Aqmessage\-received\*(Aq => sub {
\&                        my ($app, $command, $message, $time) = @_;
\&                        $label\->set_text($message\->get_text);
\&                        return \*(Aqok\*(Aq;
\&                });
\&
\&                Gtk2\->main();
\&        }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBGtk2::UniqueApp\fR is the base class for single instance applications. You can
either create an instance of UniqueApp via \f(CW\*(C`Gtk2::UniqueApp\->new()\*(C'\fR and
\&\f(CW\*(C`Gtk2::UniqueApp\->_with_commands()\*(C'\fR; or you can subclass Gtk2::UniqueApp
with your own application class.
.PP
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 \f(CW\*(C`Gtk2::UniqueApp::is_running()\*(C'\fR.
.PP
The usual method for using the Gtk2::UniqueApp \s-1API\s0 is to create a new instance,
passing an application-dependent name as construction-only property; the
\&\f(CW\*(C`Gtk2::UniqueApp:name\*(C'\fR property is required, and should be in the form of a
domain name, like \fIorg.gnome.YourApplication\fR.
.PP
After the creation, you should check whether an instance of your application is
already running, using \f(CW\*(C`Gtk2::UniqueApp::is_running()\*(C'\fR; if this method returns
\&\f(CW\*(C`FALSE\*(C'\fR the usual application construction sequence can continue; if it returns
\&\f(CW\*(C`TRUE\*(C'\fR you can either exit or send a message using Gtk2::UniqueMessageData
and \f(CW\*(C`Gtk2::UniqueMessageData::send_message()\*(C'\fR.
.PP
You can define custom commands using \f(CW\*(C`Gtk2::UniqueApp::add_command()\*(C'\fR: you need
to provide an arbitrary integer and a string for the command.
.SH "HIERARCHY"
.IX Header "HIERARCHY"
.Vb 2
\&  Glib::Object
\&  +\-\-\-\-Gtk2::UniqueApp
.Ve
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "uniqueapp = Gtk2::UniqueApp\->\fBnew\fP ($name, $startup_id, ...)"
.el .SS "uniqueapp = Gtk2::UniqueApp\->\fBnew\fP ($name, \f(CW$startup_id\fP, ...)"
.IX Subsection "uniqueapp = Gtk2::UniqueApp->new ($name, $startup_id, ...)"
.IP "\(bu" 4
\&\f(CW$name\fR (string)
.IP "\(bu" 4
\&\f(CW$startup_id\fR (string or undef)
.IP "\(bu" 4
\&... (list)
.PP
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 \fIorg.gnome.YourApplication\fR.
.PP
If startup_id is \f(CW\*(C`undef\*(C'\fR the \s-1DESKTOP_STARTUP_ID\s0 environment variable will be
check, and if that fails a \*(L"fake\*(R" startup notification id will be created.
.PP
Once you have created a Gtk2::UniqueApp instance, you should check if any other
instance is running, using \f(CW\*(C`Gtk2::UniqueApp::is_running()\*(C'\fR. If another
instance is running you can send a command to it, using the
\&\f(CW\*(C`Gtk2::UniqueApp::send_message()\*(C'\fR function; after that, the second instance
should quit. If no other instance is running, the usual logic for creating the
application can follow.
.ie n .SS "uniqueapp = Gtk2::UniqueApp\->\fBnew_with_commands\fP ($name, $startup_id, ...)"
.el .SS "uniqueapp = Gtk2::UniqueApp\->\fBnew_with_commands\fP ($name, \f(CW$startup_id\fP, ...)"
.IX Subsection "uniqueapp = Gtk2::UniqueApp->new_with_commands ($name, $startup_id, ...)"
.IP "\(bu" 4
\&\f(CW$name\fR (string)
.IP "\(bu" 4
\&\f(CW$startup_id\fR (string or undef)
.IP "\(bu" 4
\&... (list)
.PP
An alias for \f(CW\*(C`Gtk2::UniqueApp\->new()\*(C'\fR.
.ie n .SS "$app\->\fBadd_command\fP ($command_name, $command_id)"
.el .SS "\f(CW$app\fP\->\fBadd_command\fP ($command_name, \f(CW$command_id\fP)"
.IX Subsection "$app->add_command ($command_name, $command_id)"
.IP "\(bu" 4
\&\f(CW$command_name\fR (string)
.IP "\(bu" 4
\&\f(CW$command_id\fR (integer)
.PP
Adds command_name as a custom command that can be used by app. You must call
\&\f(CW\*(C`Gtk2::UniqueApp::add_command()\*(C'\fR before \f(CW\*(C`Gtk2::UniqueApp::send_message()\*(C'\fR in
order to use the newly added command.
.PP
The command name is used internally: you need to use the command's logical id in
\&\f(CW\*(C`Gtk2::UniqueApp::send_message()\*(C'\fR and inside the \fImessage-received\fR signal.
.ie n .SS "boolean = $app\->\fBis_running\fP"
.el .SS "boolean = \f(CW$app\fP\->\fBis_running\fP"
.IX Subsection "boolean = $app->is_running"
Checks whether another instance of app is running.
.ie n .SS "uniqueresponse = $app\->\fBsend_message\fP ($command, ...)"
.el .SS "uniqueresponse = \f(CW$app\fP\->\fBsend_message\fP ($command, ...)"
.IX Subsection "uniqueresponse = $app->send_message ($command, ...)"
.IP "\(bu" 4
\&\f(CW$command\fR (scalar)
.IP "\(bu" 4
\&... (list)
.PP
Same as \f(CW\*(C`Gkt2::UniqueApp::send_message_by_name()\*(C'\fR, but uses a message id
instead of a name.
.ie n .SS "uniqueresponse = $app\->\fBsend_message_by_name\fP ($command, ...)"
.el .SS "uniqueresponse = \f(CW$app\fP\->\fBsend_message_by_name\fP ($command, ...)"
.IX Subsection "uniqueresponse = $app->send_message_by_name ($command, ...)"
.IP "\(bu" 4
\&\f(CW$command\fR (scalar)
.IP "\(bu" 4
\&... (list)
.PP
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:
.IP "text" 4
.IX Item "text"
A plain text message
.IP "data" 4
.IX Item "data"
Rad data
.IP "filename" 4
.IX Item "filename"
A file name
.IP "uris" 4
.IX Item "uris"
\&\s-1URI,\s0 multiple values can be passed
.PP
The running application will receive a \fImessage-received\fR signal and will call
the various signal handlers attach to it. If any handler returns a
\&\f(CW\*(C`Gtk2::UniqueResponse\*(C'\fR different than \f(CW\*(C`ok\*(C'\fR, the emission will stop.
.PP
Usages:
.PP
.Vb 6
\&        $app\->send_message_by_name(write => data => $data);
\&        $app\->send_message_by_name(greet => text => "Hello World!");
\&        $app\->send_message_by_name(open  => uris =>
\&                \*(Aqhttp://search.cpan.org/\*(Aq,
\&                \*(Aqhttp://www.gnome.org/\*(Aq,
\&        );
.Ve
.PP
\&\fB\s-1NOTE\s0\fR: If you prefer to use an \s-1ID\s0 instead of a message name then use the
function \f(CW\*(C`Gkt2::UniqueApp::send_message()\*(C'\fR. The usage is the same as this one.
.ie n .SS "$app\->\fBwatch_window\fP ($window)"
.el .SS "\f(CW$app\fP\->\fBwatch_window\fP ($window)"
.IX Subsection "$app->watch_window ($window)"
.IP "\(bu" 4
\&\f(CW$window\fR (Gtk2::Window)
.PP
Makes app \*(L"watch\*(R" a window. Every watched window will receive startup notification changes automatically.
.SH "PROPERTIES"
.IX Header "PROPERTIES"
.IP "'is\-running' (boolean : default false : readable / private)" 4
.IX Item "'is-running' (boolean : default false : readable / private)"
Whether another instance is running
.IP "'name' (string : default undef : readable / writable / construct-only / private)" 4
.IX Item "'name' (string : default undef : readable / writable / construct-only / private)"
The unique name of the application
.IP "'screen' (Gtk2::Gdk::Screen : default undef : readable / writable / construct / private)" 4
.IX Item "'screen' (Gtk2::Gdk::Screen : default undef : readable / writable / construct / private)"
The GdkScreen of the application
.IP "'startup\-id' (string : default undef : readable / writable / construct-only / private)" 4
.IX Item "'startup-id' (string : default undef : readable / writable / construct-only / private)"
The startup notification id for the application
.SH "SIGNALS"
.IX Header "SIGNALS"
.IP "Gtk2::UniqueResponse = \fBmessage-received\fR (Gtk2::UniqueApp, integer, Gtk2::UniqueMessageData, Glib::UInt)" 4
.IX Item "Gtk2::UniqueResponse = message-received (Gtk2::UniqueApp, integer, Gtk2::UniqueMessageData, Glib::UInt)"
.SH "ENUMS AND FLAGS"
.IX Header "ENUMS AND FLAGS"
.SS "enum Gtk2::UniqueResponse"
.IX Subsection "enum Gtk2::UniqueResponse"
.PD 0
.IP "\(bu" 4
.PD
\&'invalid' / '\s-1UNIQUE_RESPONSE_INVALID\s0'
.IP "\(bu" 4
\&'ok' / '\s-1UNIQUE_RESPONSE_OK\s0'
.IP "\(bu" 4
\&'cancel' / '\s-1UNIQUE_RESPONSE_CANCEL\s0'
.IP "\(bu" 4
\&'fail' / '\s-1UNIQUE_RESPONSE_FAIL\s0'
.IP "\(bu" 4
\&'passthrough' / '\s-1UNIQUE_RESPONSE_PASSTHROUGH\s0'
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Gtk2::Unique, Glib::Object
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2009\-2010 by Emmanuel Rodriguez