NAME

App::MathImage::X11::Protocol::GrabServer -- object-oriented server grabbing

SYNOPSIS

use App::MathImage::X11::Protocol::GrabServer;
{
  my $grab = App::MathImage::X11::Protocol::GrabServer->new ($X); 
  do_some_things();
  # UngrabServer when $grab destroyed
}

DESCRIPTION

This is an object-oriented approach to GrabServer / UngrabServer. A grab object represents a desired server grab on an X11::Protocol connection. The first grab object created does a GrabServer and the last to be destroyed does an UngrabServer.

The idea is that is can be easier to manage the lifespan of an object in a block or a state object than to be sure of catching all exits. Grab objects can nest or overlap, which is good in a library or sub-function where the ungrab should wait until the end of the outermost desired grab.

A server grab is usually done to make a few operations atomic, usually something global like root window properties etc. The block-based temporary object shown in the synopsis above is typical. It's also possible to hold a grab object for an extended time, perhaps for some state driven interaction, but care should be taken not to grab for too long since other client programs are locked out.

Weak $X

If weak references are available, which means Perl 5.6 and up and Scalar::Util XS code, then only a weak reference is held to the target X11::Protocol object. This means the grab doesn't keep it alive and connected once nothing else is interested. When the connection is destroyed the server ungrabs automatically, so there's no need for an explicit $X->UngrabServer in that case.

The effect of the weakening is that $X can be destroyed anywhere within a grab block once nothing else refers to it, the same as if there was no grab. Without the weakening it would wait until the end of the block. In practice this is unlikely to make much difference.

FUNCTIONS

$grab = App::MathImage::X11::Protocol::GrabServer->new ($X)

$X should be an X11::Protocol object. Create and return a $grab object representing a grab of the $X server.

If this new grab object is the only one currently on $X then do an $X->GrabServer.

$grab->grab

$grab->ungrab

Explicitly grab or ungrab the $grab object. If it's already grabbing or not grabbing then do nothing.

An ungrab is done automatically when $grab is destroyed, but $grab->ungrab() can do it sooner. A $grab->grab() can re-grab with that object if desired.

SEE ALSO

X11::Protocol, App::MathImage::X11::Protocol::MoreUtils

HOME PAGE

http://user42.tuxfamily.org/math-image/index.html

LICENSE

Copyright 2010, 2011 Kevin Ryde

Math-Image 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.

Math-Image 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 Math-Image. If not, see <http://www.gnu.org/licenses/>.