trusty (3) X11::Protocol::GrabServer.3pm.gz

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/>.