diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/grab.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/grab.pod | 140 |
1 files changed, 0 insertions, 140 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/grab.pod b/Master/tlpkg/tlperl/lib/Tk/grab.pod deleted file mode 100644 index 98a488d09f7..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/grab.pod +++ /dev/null @@ -1,140 +0,0 @@ -# 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 - |