NAME¶
X11::Protocol::GrabServer -- object-oriented server grabbing
SYNOPSIS¶
use X11::Protocol::GrabServer;
{
my $grab = X11::Protocol::GrabServer->new ($X);
do_some_things();
# UngrabServer when $grab destroyed
}
DESCRIPTION¶
This is an object-oriented approach to GrabServer / UngrabServer on an
"X11::Protocol" connection. A grab object represents a desired
server grab and destroying it ungrabs.
The first grab object on a connection does a "GrabServer()" and the
last destroyed does an "UngrabServer()". The idea is that it's
easier to manage the lifespan of a grabbing object in a block etc than to be
sure of catching all exits.
Multiple grab objects can overlap or nest. A single "GrabServer()" is
done and it remains until the last object is destroyed. This is good in a
library or sub-function where an "UngrabServer()" should wait until
the end of any outer desired grab.
A server grab is usually to make a few operations atomic, for instance something
global like root window properties. A block-based temporary per the synopsis
above is typical. It's also possible to hold a grab object for an extended
time, perhaps for some state driven interaction.
Care must be taken not to grab for too long since other client programs are
locked out. If a grabbing program hangs then the server will be unusable until
the program is killed, or its TCP etc server connection is broken.
Weak $X¶
If Perl weak references are available (Perl 5.6 and up and
"Scalar::Util" with its usual XS code), then a grab object holds
only a weak reference to the target $X connection. This means the grab doesn't
keep the connection up once nothing else is interested. When a connection is
destroyed the server ungrabs automatically so there's no need for an explicit
"UngrabServer()" in that case.
The main effect of the weakening is that $X can be garbage collected anywhere
within a grabbing block, the same as if there was no grab. Without the
weakening it would wait until the end of the block. In practice this only
rarely makes a difference.
In the future if an "X11::Protocol" connection gets a notion of an
explicit close then the intention would be to skip any
"UngrabServer()" in that case too, ie. treat a closed connection the
same as a weakened away connection.
Currently no attention is paid to whether the server has disconnected the link.
A "UngrabServer()" is done on destroy in the usual way. If the
server has disconnected then a "SIGPIPE" or "EPIPE" occurs
the same as for any other request sent to the $X.
FUNCTIONS¶
- "$g = X11::Protocol::GrabServer->new ($X)"
- $X is an "X11::Protocol" object. Create and return a $g object
representing a grab of the $X server.
If this new $g is the first new grab on $X then an
"$X->GrabServer" is done.
- "$g->ungrab ()"
- Ungrab the $g object. An ungrab is done automatically when $g is
destroyed, but "$g->ungrab()" can do it sooner.
If $g is already ungrabbed this way then do nothing.
- "$g->grab ()"
- Re-grab with the $g object. This can be used after a
"$g->ungrab()" to grab again using the same object, the same
as if newly created.
If $g is already grabbing, then do nothing.
- "$bool = $g->is_grabbed ()"
- Return true if $g is grabbing. This is true when first created, or false
after a "$g->ungrab()".
SEE ALSO¶
X11::Protocol, X11::Protocol::Other
HOME PAGE¶
<
http://user42.tuxfamily.org/x11-protocol-other/index.html>
LICENSE¶
Copyright 2010, 2011, 2012, 2013 Kevin Ryde
X11-Protocol-Other is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 3, or (at your option) any later version.
X11-Protocol-Other is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
details.
You should have received a copy of the GNU General Public License along with
X11-Protocol-Other. If not, see <
http://www.gnu.org/licenses/>.