~ubuntu-branches/ubuntu/vivid/gcl/vivid

Next: <a href="tk_002dlistbox_002dsingle_002dselect.html#tk_002dlistbox_002dsingle_002dselect" accesskey="n" rel="next">tk-listbox-single-select</a>, Previous: <a href="focus.html#focus" accesskey="p" rel="prev">focus</a>, Up: <a href="Control.html#Control" accesskey="u" rel="up">Control</a>   [<a href="wm.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]

</div>

<hr>

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

<h4 class="unnumberedsubsec">Synopsis</h4>

grab ?:global? window

grab option ?arg arg ...?

<h4 class="unnumberedsubsec">Description</h4>

This command implements 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 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 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.

100

During local grabs, keyboard events (key presses and key releases)

101

are delivered as usual: the window

102

manager controls which application receives keyboard events, and

103

if they are sent to any window in the grabbing application then they are

104

redirected to the focus window.

105

During a global grab Tk grabs the keyboard so that all keyboard events

106

are always sent to the grabbing application.

107

The focus command is still used to determine which window in the

108

application receives the keyboard events.

109

The keyboard grab is released when the grab is released.

110

111

Grabs apply to particular displays. If an application has windows

112

on multiple displays then it can establish a separate grab on each

113

display.

114

The grab on a particular display affects only the windows on

115

that display.

116

It is possible for different applications on a single display to have

117

simultaneous local grabs, but only one application can have a global

118

grab on a given display at once.

119

120

The grab command can take any of the following forms:

121

122

123

<dt>grab ?:global? window</dt>

124

<dd>Same as grab :set, described below.

125

</dd>

126

<dt>grab :current ?window?</dt>

127

<dd>If window is specified, returns the name of the current grab

128

window in this application for window’s display, or an empty

129

string if there is no such window.

130

If window is omitted, the command returns a list whose elements

131

are all of the windows grabbed by this application for all displays,

132

or an empty string if the application has no grabs.

133

</dd>

134

<dt>grab :release window</dt>

135

<dd>Releases the grab on window if there is one, otherwise does

136

nothing. Returns an empty string.

137

</dd>

138

<dt>grab :set ?:global? window</dt>

139

<dd>Sets a grab on window. If :global is specified then the

140

grab is global, otherwise it is local.

141

If a grab was already in effect for this application on

142

window’s display then it is automatically released.

143

If there is already a grab on window and it has the same

144

global/local form as the requested grab, then the command

145

does nothing. Returns an empty string.

146

</dd>

147

<dt>grab :status window</dt>

148

<dd>Returns none if no grab is currently set on window,

149

local if a local grab is set on window, and

150

global if a global grab is set.

151

152

</dd>

153

</dl>

154

155

156

157

It took an incredibly complex and gross implementation to produce

158

the simple grab effect described above.

159

Given the current implementation, it isn’t safe for applications

160

to use the Xlib grab facilities at all except through the Tk grab

161

procedures.

162

If applications try to manipulate X’s grab mechanisms directly,

163

things will probably break.

164

165

If a single process is managing several different Tk applications,

166

only one of those applications can have a local grab for a given

167

display at any given time. If the applications are in different

168

processes, this restriction doesn’t exist.

169

170

171

<h4 class="unnumberedsubsec">Keywords</h4>

172

grab, keyboard events, pointer events, window

173

<hr>

174

175

176

177

</div>

178

179

180

181

</body>

182

</html>

Older »