home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _b950029d32b9dea61e03c6e737af8aca < prev    next >
Text File  |  2004-06-01  |  5KB  |  141 lines
  1. #  Copyright (c) 1992 The Regents of the University of California.
  2. #  Copyright (c) 1994-1996 Sun Microsystems, Inc.
  3. #  See the file "license.terms" for information on usage and redistribution
  4. #  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  5. #
  6. #
  7.  
  8. =head1 NAME
  9.  
  10. grab - Confine pointer and keyboard events to a window sub-tree
  11.  
  12. =for category User Interaction
  13.  
  14. =head1 SYNOPSIS
  15.  
  16. I<$widget>-E<gt>B<grab>
  17.  
  18. I<$widget>-E<gt>B<grab>I<Option>
  19.  
  20. =head1 DESCRIPTION
  21.  
  22. This set of methods implement simple pointer and keyboard grabs for Tk.
  23. Tk's grabs are different than the grabs
  24. described in the Xlib documentation.
  25. When a grab is set for a particular window, Tk restricts all pointer
  26. events to the grab window and its descendants in Tk's window hierarchy.
  27. Whenever the pointer is within the grab window's subtree, the pointer
  28. will behave exactly the same as if there had been no grab at all
  29. and all events will be reported in the normal fashion.
  30. When the pointer is outside I<$widget>'s tree, button presses and
  31. releases and
  32. mouse motion events are reported to I<$widget>, and window entry
  33. and window exit events are ignored.
  34. The grab subtree ``owns'' the pointer:
  35. windows outside the grab subtree will be visible on the screen
  36. but they will be insensitive until the grab is released.
  37. The tree of windows underneath the grab window can include top-level
  38. windows, in which case all of those top-level windows
  39. and their descendants will continue to receive mouse events
  40. during the grab.
  41.  
  42. Two forms of grabs are possible:  local and global.
  43. A local grab affects only the grabbing application:  events will
  44. be reported to other applications as if the grab had never occurred.
  45. Grabs are local by default.
  46. A global grab locks out all applications on the screen,
  47. so that only the given subtree of the grabbing application will be
  48. sensitive to pointer events (mouse button presses, mouse button releases,
  49. pointer motions, window entries, and window exits).
  50. During global grabs the window manager will not receive pointer
  51. events either.
  52.  
  53. During local grabs, keyboard events (key presses and key releases)
  54. are delivered as usual:  the window
  55. manager controls which application receives keyboard events, and
  56. if they are sent to any window in the grabbing application then they are
  57. redirected to the focus window.
  58. During a global grab Tk grabs the keyboard so that all keyboard events
  59. are always sent to the grabbing application.
  60. The B<focus> method is still used to determine which window in the
  61. application receives the keyboard events.
  62. The keyboard grab is released when the grab is released.
  63.  
  64. Grabs apply to particular displays.  If an application has windows
  65. on multiple displays then it can establish a separate grab on each
  66. display.
  67. The grab on a particular display affects only the windows on
  68. that display.
  69. It is possible for different applications on a single display to have
  70. simultaneous local grabs, but only one application can have a global
  71. grab on a given display at once.
  72.  
  73. The B<grab> methods take any of the following forms:
  74.  
  75. =over 4
  76.  
  77. =item I<$widget>-E<gt>B<grabCurrent>
  78.  
  79. Returns the current grab
  80. window in this application for I<$widget>'s display, or an empty
  81. string if there is no such window.
  82.  
  83. =item I<$widget>-E<gt>B<grabs>
  84.  
  85. Returns a list whose elements
  86. are all of the windows grabbed by this application for all displays,
  87. or an empty string if the application has no grabs.
  88.  
  89. I<Not implemented yet!>
  90.  
  91. =item I<$widget>-E<gt>B<grabRelease>
  92.  
  93. Releases the grab on I<$widget> if there is one, otherwise does
  94. nothing.  Returns an empty string.
  95.  
  96. =item I<$widget>-E<gt>B<grab>
  97.  
  98. Sets a local grab on I<$widget>.
  99. If a grab was already in effect for this application on
  100. I<$widget>'s display then it is automatically released.
  101. If there is already a local grab on I<$widget>, then the command
  102. does nothing.  Returns an empty string.
  103.  
  104. =item I<$widget>-E<gt>B<grabGlobal>
  105.  
  106. Sets a global grab on I<$widget>.
  107. If a grab was already in effect for this application on
  108. I<$widget>'s display then it is automatically released.
  109. If there is already a global grab on I<$widget>,
  110. then the command does nothing.  Returns an empty string.
  111.  
  112. =item I<$widget>-E<gt>B<grabStatus>
  113.  
  114. Returns B<none> if no grab is currently set on I<$widget>,
  115. B<local> if a local grab is set on I<$widget>, and
  116. B<global> if a global grab is set.
  117.  
  118. =back
  119.  
  120. =head1 BUGS
  121.  
  122. It took an incredibly complex and gross implementation to produce
  123. the simple grab effect described above.
  124. Given the current implementation, it isn't safe for applications
  125. to use the Xlib grab facilities at all except through the Tk grab
  126. procedures.
  127. If applications try to manipulate X's grab mechanisms directly,
  128. things will probably break.
  129.  
  130. If a single process is managing several different Tk applications,
  131. only one of those applications can have a local grab for a given
  132. display at any given time.  If the applications are in different
  133. processes, this restriction doesn't exist.
  134.  
  135. =head1 KEYWORDS
  136.  
  137. grab, keyboard events, pointer events, window
  138.  
  139. =cut
  140.  
  141.