.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "X11::Protocol::GrabServer 3pm" .TH X11::Protocol::GrabServer 3pm "2016-12-25" "perl v5.24.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" X11::Protocol::GrabServer \-\- object\-oriented server grabbing .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 6 \& use X11::Protocol::GrabServer; \& { \& my $grab = X11::Protocol::GrabServer\->new ($X); \& do_some_things(); \& # UngrabServer when $grab destroyed \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is an object-oriented approach to GrabServer / UngrabServer on an \&\f(CW\*(C`X11::Protocol\*(C'\fR connection. A grab object represents a desired server grab and destroying it ungrabs. .PP The first grab object on a connection does a \f(CW\*(C`GrabServer()\*(C'\fR and the last destroyed does an \f(CW\*(C`UngrabServer()\*(C'\fR. 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. .PP Multiple grab objects can overlap or nest. A single \f(CW\*(C`GrabServer()\*(C'\fR is done and it remains until the last object is destroyed. This is good in a library or sub-function where an \f(CW\*(C`UngrabServer()\*(C'\fR should wait until the end of any outer desired grab. .PP 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. .PP 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 \s-1TCP\s0 etc server connection is broken. .ie n .SS "Weak $X" .el .SS "Weak \f(CW$X\fP" .IX Subsection "Weak $X" If Perl weak references are available (Perl 5.6 and up and \f(CW\*(C`Scalar::Util\*(C'\fR with its usual \s-1XS\s0 code), then a grab object holds only a weak reference to the target \f(CW$X\fR 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 \f(CW\*(C`UngrabServer()\*(C'\fR in that case. .PP The main effect of the weakening is that \f(CW$X\fR 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. .PP In the future if an \f(CW\*(C`X11::Protocol\*(C'\fR connection gets a notion of an explicit close then the intention would be to skip any \f(CW\*(C`UngrabServer()\*(C'\fR in that case too, ie. treat a closed connection the same as a weakened away connection. .PP Currently no attention is paid to whether the server has disconnected the link. A \f(CW\*(C`UngrabServer()\*(C'\fR is done on destroy in the usual way. If the server has disconnected then a \f(CW\*(C`SIGPIPE\*(C'\fR or \f(CW\*(C`EPIPE\*(C'\fR occurs the same as for any other request sent to the \f(CW$X\fR. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .ie n .IP """$g = X11::Protocol::GrabServer\->new ($X)""" 4 .el .IP "\f(CW$g = X11::Protocol::GrabServer\->new ($X)\fR" 4 .IX Item "$g = X11::Protocol::GrabServer->new ($X)" \&\f(CW$X\fR is an \f(CW\*(C`X11::Protocol\*(C'\fR object. Create and return a \f(CW$g\fR object representing a grab of the \f(CW$X\fR server. .Sp If this new \f(CW$g\fR is the first new grab on \f(CW$X\fR then an \&\f(CW\*(C`$X\->GrabServer\*(C'\fR is done. .ie n .IP """$g\->ungrab ()""" 4 .el .IP "\f(CW$g\->ungrab ()\fR" 4 .IX Item "$g->ungrab ()" Ungrab the \f(CW$g\fR object. An ungrab is done automatically when \f(CW$g\fR is destroyed, but \f(CW\*(C`$g\->ungrab()\*(C'\fR can do it sooner. .Sp If \f(CW$g\fR is already ungrabbed this way then do nothing. .ie n .IP """$g\->grab ()""" 4 .el .IP "\f(CW$g\->grab ()\fR" 4 .IX Item "$g->grab ()" Re-grab with the \f(CW$g\fR object. This can be used after a \f(CW\*(C`$g\->ungrab()\*(C'\fR to grab again using the same object, the same as if newly created. .Sp If \f(CW$g\fR is already grabbing, then do nothing. .ie n .IP """$bool = $g\->is_grabbed ()""" 4 .el .IP "\f(CW$bool = $g\->is_grabbed ()\fR" 4 .IX Item "$bool = $g->is_grabbed ()" Return true if \f(CW$g\fR is grabbing. This is true when first created, or false after a \f(CW\*(C`$g\->ungrab()\*(C'\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" X11::Protocol, X11::Protocol::Other .SH "HOME PAGE" .IX Header "HOME PAGE" .SH "LICENSE" .IX Header "LICENSE" Copyright 2010, 2011, 2012, 2013 Kevin Ryde .PP X11\-Protocol\-Other is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. .PP X11\-Protocol\-Other is distributed in the hope that it will be useful, but \&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE. \s0 See the \s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with X11\-Protocol\-Other. If not, see .