Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Gtk2::UniqueApp(3)    User Contributed Perl Documentation   Gtk2::UniqueApp(3)

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

       o   $startup_id (string or undef)

       o   ... (list)

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

   $app->add_command ($command_name, $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 = $app->is_running
       Checks whether another instance of app is running.

   uniqueresponse = $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 = $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/',
	       );

       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)
       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 / static-
       nick / static-blurb)
	   Whether another instance is running

       'name' (string :	default	undef :	readable / writable / construct-only /
       private / static-nick / static-blurb)
	   The unique name of the application

       'screen'	(Gtk2::Gdk::Screen : default undef : readable /	writable /
       construct / private / static-nick / static-blurb)
	   The GdkScreen of the	application

       'startup-id' (string : default undef : readable / writable / construct-
       only / private /	static-nick / static-blurb)
	   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
       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

perl v5.32.1			  2021-02-28		    Gtk2::UniqueApp(3)

NAME | SYNOPSIS | DESCRIPTION | HIERARCHY | METHODS | PROPERTIES | SIGNALS | ENUMS AND FLAGS | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Gtk2::UniqueApp&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help