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