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 outermost 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 object like the synopsis above is
       typical.  It's also possible to hold a grab object for an extended time, perhaps for some
       state driven interaction with the server.

       Care must be taken not to grab for too long since other client programs are locked out.
       Also 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 (which means 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 alive once nothing else is
       interested.  When a connection is destroyed the server ungrabs automatically and 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 explicitly.  An ungrab is done automatically when $g is
           destroyed, but "$g->ungrab()" can do it sooner.

           If $g is already ungrabbed then do nothing.

       "$g->grab ()"
           Re-grab with the $g object.  This can be used after a "$g->ungrab()" to grab again
           with 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()".

           This function is only the state of $g.  There might be other "GrabServer" objects
           which grabbing the server.

SEE ALSO

       X11::Protocol, X11::Protocol::Other

HOME PAGE

       <http://user42.tuxfamily.org/x11-protocol-other/index.html>

LICENSE

       Copyright 2010, 2011, 2012, 2013, 2014, 2017 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/>.