Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
grab(3)		      User Contributed Perl Documentation	       grab(3)

       Tk::grab	- Confine pointer and keyboard events to a window sub-tree



       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 $widget's tree, button presses
       and releases and	mouse motion events are	reported to $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 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 grab	methods	take any of the	following forms:

	   Returns the current grab window in this application for $widget's
	   display, or an empty	string if there	is no such window.

	   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.

	   Not implemented yet!

	   Releases the	grab on	$widget	if there is one, otherwise does
	   nothing.  Returns an	empty string.

	   Sets	a local	grab on	$widget.  If a grab was	already	in effect for
	   this	application on $widget's display then it is automatically
	   released.  If there is already a local grab on $widget, then	the
	   command does	nothing.  Returns an empty string.

	   Sets	a global grab on $widget.  If a	grab was already in effect for
	   this	application on $widget's display then it is automatically
	   released.  If there is already a global grab	on $widget, then the
	   command does	nothing.  Returns an empty string.

	   Returns none	if no grab is currently	set on $widget,	local if a
	   local grab is set on	$widget, and global if a global	grab is	set.

       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.

       grab, keyboard events, pointer events, window

perl v5.32.0			  2013-11-15			       grab(3)


Want to link to this manual page? Use this URL:

home | help