grab — User Commands

NAME

grab − Confine pointer and keyboard events to a particular window sub-tree

SYNOPSIS

grab
grab window
grab −global window

DESCRIPTION

This command implements simple pointer and keyboard grabs for Tk. If the window argument is specified, then the pointer and keyboard are grabbed to that window as described below. If a grab is already in effect for another window in this application then the existing grab is automatically released. If a grab is already in effect for another application then an error is returned. If the window argument is specified as an empty string or as none then any existing grab in the application is released. In all of the above cases an empty string is returned. If grab is invoked with no arguments then the path name of the current grab window is returned, or none if no grab is active in this application.

Tk’s grabs are somewhat different than the grabs described in the Xlib documentation. A Tk grab simply restricts all pointer events to the window tree rooted at window. Whenever the pointer is within 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 window’s tree, button presses and releases and mouse motion events are reported to window, 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 totally insensitive until the grab is released. The tree of windows underneath window can include top-level windows. If this is the case, then 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 is requested with the −global switch. In this case the grab will lock out all applications on the screen, so that only the given subtree of the grabbing application will be sensitive to pointer events. During global grabs the window manager will not receive pointer events either.

During local grabs, keyboard events are handled 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 focus command 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.

Pointer events include mouse button presses, mouse button releases, pointer motions, window entries, and window exits. Keyboard events include key presses and key releases.

BUGS

If grab is invoked several times in a row with different window arguments and insufficient time to process all pending events between the invocations, then the grab-related events may end up in the wrong order in the event queue. This problem is mostly likely to occur with local grabs. The solution is to insert after commands between the grab invocations, so that there’s enough time to clear the event queue before the next grab invocation.

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.

KEYWORDS

grab, variable, wait, window