summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/grab.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/grab.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/grab.pod140
1 files changed, 140 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/grab.pod b/Master/tlpkg/tlperl/lib/Tk/grab.pod
new file mode 100644
index 00000000000..d74ee7da502
--- /dev/null
+++ b/Master/tlpkg/tlperl/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
+
+Tk::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
+