home *** CD-ROM | disk | FTP | other *** search
- # 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
-
-