diff options
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/Tk/grab.pod')
| -rwxr-xr-x | Master/tlpkg/tlperl0/lib/Tk/grab.pod | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/Tk/grab.pod b/Master/tlpkg/tlperl0/lib/Tk/grab.pod new file mode 100755 index 00000000000..98a488d09f7 --- /dev/null +++ b/Master/tlpkg/tlperl0/lib/Tk/grab.pod @@ -0,0 +1,140 @@ +# Copyright (c) 1992 The Regents of the University of California. +# Copyright (c) 1994-1996 Sun Microsystems, Inc. +# See the file "license.terms" for information on usage and redistribution +# of this file, and for a DISCLAIMER OF ALL WARRANTIES. +# +# + +=head1 NAME + +grab - Confine pointer and keyboard events to a window sub-tree + +=for category User Interaction + +=head1 SYNOPSIS + +I<$widget>-E<gt>B<grab> + +I<$widget>-E<gt>B<grab>I<Option> + +=head1 DESCRIPTION + +This set of methods implement simple pointer and keyboard grabs for Tk. +Tk's grabs are different than the grabs +described in the Xlib documentation. +When a grab is set for a particular window, Tk restricts all pointer +events to the grab window and its descendants in Tk's window hierarchy. +Whenever the pointer is within the grab window's subtree, the pointer +will behave exactly the same as if there had been no grab at all +and all events will be reported in the normal fashion. +When the pointer is outside I<$widget>'s tree, button presses and +releases and +mouse motion events are reported to I<$widget>, and window entry +and window exit events are ignored. +The grab subtree ``owns'' the pointer: +windows outside the grab subtree will be visible on the screen +but they will be insensitive until the grab is released. +The tree of windows underneath the grab window can include top-level +windows, in which case all of those top-level windows +and their descendants will continue to receive mouse events +during the grab. + +Two forms of grabs are possible: local and global. +A local grab affects only the grabbing application: events will +be reported to other applications as if the grab had never occurred. +Grabs are local by default. +A global grab locks out all applications on the screen, +so that only the given subtree of the grabbing application will be +sensitive to pointer events (mouse button presses, mouse button releases, +pointer motions, window entries, and window exits). +During global grabs the window manager will not receive pointer +events either. + +During local grabs, keyboard events (key presses and key releases) +are delivered as usual: the window +manager controls which application receives keyboard events, and +if they are sent to any window in the grabbing application then they are +redirected to the focus window. +During a global grab Tk grabs the keyboard so that all keyboard events +are always sent to the grabbing application. +The B<focus> method is still used to determine which window in the +application receives the keyboard events. +The keyboard grab is released when the grab is released. + +Grabs apply to particular displays. If an application has windows +on multiple displays then it can establish a separate grab on each +display. +The grab on a particular display affects only the windows on +that display. +It is possible for different applications on a single display to have +simultaneous local grabs, but only one application can have a global +grab on a given display at once. + +The B<grab> methods take any of the following forms: + +=over 4 + +=item I<$widget>-E<gt>B<grabCurrent> + +Returns the current grab +window in this application for I<$widget>'s display, or an empty +string if there is no such window. + +=item I<$widget>-E<gt>B<grabs> + +Returns a list whose elements +are all of the windows grabbed by this application for all displays, +or an empty string if the application has no grabs. + +I<Not implemented yet!> + +=item I<$widget>-E<gt>B<grabRelease> + +Releases the grab on I<$widget> if there is one, otherwise does +nothing. Returns an empty string. + +=item I<$widget>-E<gt>B<grab> + +Sets a local grab on I<$widget>. +If a grab was already in effect for this application on +I<$widget>'s display then it is automatically released. +If there is already a local grab on I<$widget>, then the command +does nothing. Returns an empty string. + +=item I<$widget>-E<gt>B<grabGlobal> + +Sets a global grab on I<$widget>. +If a grab was already in effect for this application on +I<$widget>'s display then it is automatically released. +If there is already a global grab on I<$widget>, +then the command does nothing. Returns an empty string. + +=item I<$widget>-E<gt>B<grabStatus> + +Returns B<none> if no grab is currently set on I<$widget>, +B<local> if a local grab is set on I<$widget>, and +B<global> if a global grab is set. + +=back + +=head1 BUGS + +It took an incredibly complex and gross implementation to produce +the simple grab effect described above. +Given the current implementation, it isn't safe for applications +to use the Xlib grab facilities at all except through the Tk grab +procedures. +If applications try to manipulate X's grab mechanisms directly, +things will probably break. + +If a single process is managing several different Tk applications, +only one of those applications can have a local grab for a given +display at any given time. If the applications are in different +processes, this restriction doesn't exist. + +=head1 KEYWORDS + +grab, keyboard events, pointer events, window + +=cut + |