1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>
The Mouse Pointer
</title>
<meta name="GENERATOR" content=
"Modular DocBook HTML Stylesheet Version 1.45">
<link rel="HOME" title="GTK+ / Gnome Application Development"
href="ggad.html">
<link rel="UP" title="GDK Basics" href="cha-gdk.html">
<link rel="PREVIOUS" title="Events" href="sec-gdkevent.html">
<link rel="NEXT" title="Fonts" href="sec-gdkfont.html">
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink=
"#840084" alink="#0000FF">
<div class="NAVHEADER">
<table width="100%" border="0" bgcolor="#ffffff" cellpadding=
"1" cellspacing="0">
<tr>
<th colspan="4" align="center">
<font color="#000000" size="2">GTK+ / Gnome Application
Development</font>
</th>
</tr>
<tr>
<td width="25%" bgcolor="#ffffff" align="left">
<a href="sec-gdkevent.html"><font color="#0000ff" size=
"2"><b><<< Previous</b></font></a>
</td>
<td width="25%" colspan="2" bgcolor="#ffffff" align=
"center">
<font color="#0000ff" size="2"><b><a href="ggad.html">
<font color="#0000ff" size="2"><b>
Home</b></font></a></b></font>
</td>
<td width="25%" bgcolor="#ffffff" align="right">
<a href="sec-gdkfont.html"><font color="#0000ff" size=
"2"><b>Next >>></b></font></a>
</td>
</tr>
</table>
</div>
<div class="SECT1">
<h1 class="SECT1">
<a name="SEC-GDKCURSOR">The Mouse Pointer</a>
</h1>
<p>
The mouse pointer is represented on the screen by a small
bitmap called the <i class="FIRSTTERM">cursor</i>. The
cursor is normally an arrow shape, but it can be changed on
a window-by-window basis. As the pointer moves, it
generates motion events and moves the cursor on the screen
to give the user feedback.
</p>
<div class="SECT2">
<h2 class="SECT2">
<a name="Z129">Pointer Location</a>
</h2>
<p>
You can query the pointer's location with <tt class=
"FUNCTION">gdk_window_get_pointer()</tt> (<a href=
"sec-gdkcursor.html#FL-GETPOINTER">Figure 7</a>). This
function requests the X and Y coordinates of the pointer
relative to the window passed as its first argument. It
also requests the currently active modifiers (including
modifier keys and buttons; this field is identical to the
<span class="STRUCTNAME">state</span> field in several
events, such as button events). If <span class=
"STRUCTNAME">NULL</span> is passed for the <span class=
"STRUCTNAME">x</span>, <span class="STRUCTNAME">y</span>,
or <span class="STRUCTNAME">state</span> arguments, that
argument will be ignored.
</p>
<div class="FIGURE">
<a name="FL-GETPOINTER"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-GETPOINTER.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <gdk/gdk.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">GdkWindow* <tt class=
"FUNCTION">
gdk_window_get_pointer</tt></code>(GdkWindow* <tt
class="PARAMETER"><i>window</i></tt>, gint* <tt
class="PARAMETER"><i>x</i></tt>, gint* <tt class=
"PARAMETER"><i>y</i></tt>, GdkModifierMask* <tt
class="PARAMETER"><i>state</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 7. Querying Pointer Location</b>
</p>
</div>
</div>
<div class="SECT2">
<h2 class="SECT2">
<a name="SEC-POINTERGRAB">Grabbing the Pointer</a>
</h2>
<p>
It is possible to <i class="FIRSTTERM">grab</i> the
pointer, which means that all pointer events will go to
the <i class="FIRSTTERM">grab window</i> for the duration
of the grab. Normally pointer events go to the window the
pointer is inside. You should grab the pointer, for
example, if the user is using click-and-drag selection to
select a rectangular area. If they click and then
inadvertently drag the pointer outside the window, you
should continue to track the pointer's location and
change the selection accordingly. The grab also ensures
that pointer events won't be sent to other applications.
</p>
<p>
To grab the pointer, call <tt class="FUNCTION">
gdk_pointer_grab()</tt>, shown in <a href=
"sec-gdkcursor.html#FL-GRABBING">Figure 8</a>. The first
argument to this function is the grab window; this window
will receive events during the grab. The next argument
should be <span class="STRUCTNAME">TRUE</span> or <span
class="STRUCTNAME">FALSE</span>; it specifies whether
events will go only to the grab window, or to its child
windows as well. The <span class="STRUCTNAME">
confine_to</span> argument specifies a window to confine
the pointer to. The user will not be able to move the
pointer outside this window. You can specify a different
<span class="STRUCTNAME">cursor</span> for the duration
of the grab; see the next section for details on creating
a cursor. If you don't want to change the cursor, give
<span class="STRUCTNAME">NULL</span> as the <span class=
"STRUCTNAME">cursor</span> argument. (Side note: it is
safe to destroy the cursor immediately after calling <tt
class="FUNCTION">gdk_pointer_grab()</tt> because it is a
server-side resource and X will not deallocate it until
the grab is over.)
</p>
<p>
The final argument, <span class="STRUCTNAME">time</span>,
specifies when the grab should take effect, in server
time. This is intended to resolve conflicts if two
clients try to grab the pointer simultaneously; the time
must be after the last grab time, and it must not be in
the future. Usually, you will want to use the <span
class="STRUCTNAME">time</span> field from the event
you're processing, or the <tt class="FUNCTION">
GDK_CURRENT_TIME</tt> macro. <tt class="FUNCTION">
GDK_CURRENT_TIME</tt> is a magic constant that tells the
X server to substitute the current time.
</p>
<p>
<tt class="FUNCTION">gdk_pointer_grab()</tt> returns
<span class="STRUCTNAME">TRUE</span> if it succeeds. It
is possible for it to fail if the grab window or <span
class="STRUCTNAME">confine_to</span> window is hidden,
another client has the grab already, or any of the
arguments are invalid. Regrettably few applications check
this return value, which is a bug (granted, a
difficult-to-trigger one).
</p>
<p>
To ungrab the pointer, call <tt class="FUNCTION">
gdk_pointer_ungrab()</tt>; the <span class="STRUCTNAME">
time</span> argument is identical to the one in <tt
class="FUNCTION">gdk_pointer_grab()</tt>. You can find
out if the pointer is grabbed using <tt class="FUNCTION">
gdk_pointer_is_grabbed()</tt>. You <i class="EMPHASIS">
must</i> ungrab the pointer when you're finished with it,
because the user will be unable to use other applications
while the pointer is grabbed.
</p>
<p>
Note that the GDK-level concept of grabbing the pointer
is distinct from the GTK+-level grab concept. A GTK+ grab
redirects certain events to a grabbing <i class=
"EMPHASIS">widget</i>, creating a "modal" widget such as
a dialog (see <a href="z57.html#SEC-GRABS">the section
called <i>Grabs</i> in the chapter called <i>GTK+
Basics</i></a>). GTK+'s grab only affects the current
application; only events that occur on one of the current
application's widgets are redirected. The scope of a GDK
grab is wider, encompassing the entire X server, not just
your application.
</p>
<div class="FIGURE">
<a name="FL-GRABBING"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-GRABBING.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <gdk/gdk.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">gint <tt class=
"FUNCTION">gdk_pointer_grab</tt></code>(GdkWindow*
<tt class="PARAMETER"><i>window</i></tt>, gint <tt
class="PARAMETER"><i>owner_events</i></tt>,
GdkWindow* <tt class="PARAMETER"><i>
confine_to</i></tt>, GdkCursor* <tt class=
"PARAMETER"><i>cursor</i></tt>, guint32 <tt class=
"PARAMETER"><i>time</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">gdk_pointer_ungrab</tt></code>(guint32 <tt
class="PARAMETER"><i>time</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">gint <tt class=
"FUNCTION">
gdk_pointer_is_grabbed</tt></code>(void);</code>
</p>
</div>
<p>
<b>Figure 8. Grabbing the Pointer</b>
</p>
</div>
</div>
<div class="SECT2">
<h2 class="SECT2">
<a name="Z130">Changing the Cursor</a>
</h2>
<p>
You can change the cursor shape at any time; cursor
shapes are set on a window-by-window basis with <tt
class="FUNCTION">gdk_window_set_cursor()</tt> (<a href=
"sec-gdkcursor.html#FL-CURSOR">Figure 9</a>). By default,
windows use their parent's cursor; you can restore the
default cursor by setting a window's cursor to <span
class="STRUCTNAME">NULL</span>.
</p>
<p>
Two ways are provided to create a cursor. The simplest
way is to choose a cursor from the cursor font that comes
with X. The cursor font contains cursors instead of
characters; you can view it with the command <tt class=
"APPLICATION">xfd -fn cursor</tt>. You can also browse
the available cursors using the <tt class="APPLICATION">
testgtk</tt> program that comes with GTK+. Each cursor
shape has a constant defined in <tt class="FILENAME">
gdk/gdkcursors.h</tt>. <tt class="FUNCTION">
gdk_cursor_new()</tt> accepts one of these constants as
its only argument:
</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="PROGRAMLISTING">
GdkCursor* cursor;
cursor = gdk_cursor_new(GDK_CLOCK);
gdk_window_set_cursor(window, cursor);
gdk_cursor_destroy(cursor);
</pre>
</td>
</tr>
</table>
<p>
Notice that you can destroy the cursor as soon as you
attach it to a window; <span class="STRUCTNAME">
GdkCursor</span> is a client-side handle for a
server-side resource, and X will keep the server-side
resource around as long as it's in use.
</p>
<p>
If none of the cursors in the cursor font are
appropriate, you can create a custom cursor from a
bitmap. Two bitmaps, actually: the <span class=
"STRUCTNAME">source</span> pixmap, and the <span class=
"STRUCTNAME">mask</span>. Since these are bitmaps, every
pixel is either on or off (0 or 1). If a pixel is 0 in
the mask, that pixel will be transparent. If a pixel is 1
in both pixmaps, it will be displayed in the <span class=
"STRUCTNAME">fg</span> (foreground) color passed to <tt
class="FUNCTION">gdk_cursor_new_from_pixmap()</tt>. If a
pixel is 1 in the mask but 0 in the <span class=
"STRUCTNAME">source</span> pixmap, it will be displayed
in the <span class="STRUCTNAME">bg</span> (background)
color. The <span class="STRUCTNAME">source</span> and
<span class="STRUCTNAME">mask</span> pixmaps must be the
same size, and they must have a depth of one.
</p>
<p>
The foreground and background colors should be
contrasting, so the cursor will be visible against any
background. Most cursors are drawn in the foreground
color and outlined in the background color. (To see this,
move an X cursor over a dark background; you will notice
a white outline around its edges.) To achieve this, <span
class="STRUCTNAME">mask</span> should be slightly larger
than <span class="STRUCTNAME">source</span>, but the same
shape.
</p>
<p>
The final two arguments to <tt class="FUNCTION">
gdk_cursor_new_from_pixmap()</tt> are the coordinates of
the cursor's <i class="FIRSTTERM">hot spot</i>. This is
the point drawn at the mouse pointer's location---the tip
of an arrow cursor, or the center of a crosshair cursor.
<tt class="FUNCTION">gdk_cursor_new_from_pixmap()</tt>
will fail if the hot spot is not within the bitmap.
</p>
<div class="FIGURE">
<a name="FL-CURSOR"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-CURSOR.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <gdk/gdk.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">GdkCursor* <tt class=
"FUNCTION">gdk_cursor_new</tt></code>(GdkCursorType
<tt class="PARAMETER"><i>
cursor_type</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">GdkCursor* <tt class=
"FUNCTION">
gdk_cursor_new_from_pixmap</tt></code>(GdkPixmap* <tt
class="PARAMETER"><i>source</i></tt>, GdkPixmap* <tt
class="PARAMETER"><i>mask</i></tt>, GdkColor* <tt
class="PARAMETER"><i>fg</i></tt>, GdkColor* <tt
class="PARAMETER"><i>bg</i></tt>, gint <tt class=
"PARAMETER"><i>x</i></tt>, gint <tt class=
"PARAMETER"><i>y</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">gdk_cursor_destroy</tt></code>(GdkCursor*
<tt class="PARAMETER"><i>cursor</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">
gdk_window_set_cursor</tt></code>(GdkWindow* <tt
class="PARAMETER"><i>window</i></tt>, GdkCursor* <tt
class="PARAMETER"><i>cursor</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 9. <span class="STRUCTNAME">
GdkCursor</span></b>
</p>
</div>
</div>
</div>
<div class="NAVFOOTER">
<br>
<br>
<table width="100%" border="0" bgcolor="#ffffff" cellpadding=
"1" cellspacing="0">
<tr>
<td width="25%" bgcolor="#ffffff" align="left">
<a href="sec-gdkevent.html"><font color="#0000ff" size=
"2"><b><<< Previous</b></font></a>
</td>
<td width="25%" colspan="2" bgcolor="#ffffff" align=
"center">
<font color="#0000ff" size="2"><b><a href="ggad.html">
<font color="#0000ff" size="2"><b>
Home</b></font></a></b></font>
</td>
<td width="25%" bgcolor="#ffffff" align="right">
<a href="sec-gdkfont.html"><font color="#0000ff" size=
"2"><b>Next >>></b></font></a>
</td>
</tr>
<tr>
<td colspan="2" align="left">
<font color="#000000" size="2"><b>Events</b></font>
</td>
<td colspan="2" align="right">
<font color="#000000" size="2"><b>Fonts</b></font>
</td>
</tr>
</table>
</div>
</body>
</html>
|
