GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  GTK2::UNIQUEAPP (3)

.ds Aq ’

NAME

Gtk2::UniqueApp - Base class for singleton applications

CONTENTS

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 theres 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

<B>Gtk2::UniqueAppB> 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, CW$startup_id, ...)

o $name (string)
o $startup_id (string or undef)
o ... (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, CW$startup_id, ...)

o $name (string)
o $startup_id (string or undef)
o ... (list)
An alias for Gtk2::UniqueApp->new().

CW$app->add_command ($command_name, CW$command_id)

o $command_name (string)
o $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 = CW$app->is_running

Checks whether another instance of app is running.

uniqueresponse = CW$app->send_message ($command, ...)

o $command (scalar)
o ... (list)
Same as Gkt2::UniqueApp::send_message_by_name(), but uses a message id instead of a name.

uniqueresponse = CW$app->send_message_by_name ($command, ...)

o $command (scalar)
o ... (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/,
        );



<B>NOTEB>: 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.

CW$app->watch_window ($window)

o $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 = <B>message-receivedB> (Gtk2::UniqueApp, integer, Gtk2::UniqueMessageData, Glib::UInt)

ENUMS AND FLAGS

    enum Gtk2::UniqueResponse

o ’invalid’ / ’UNIQUE_RESPONSE_INVALID
o ok’ / ’UNIQUE_RESPONSE_OK
o ’cancel’ / ’UNIQUE_RESPONSE_CANCEL
o ’fail’ / ’UNIQUE_RESPONSE_FAIL
o ’passthrough’ / ’UNIQUE_RESPONSE_PASSTHROUGH

SEE ALSO

Gtk2::Unique, Glib::Object

COPYRIGHT

Copyright (C) 2009-2010 by Emmanuel Rodriguez
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 GTK2::UNIQUEAPP (3) 2016-04-05

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.