1
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
3
.\" Permission is hereby granted, free of charge, to any person obtaining
4
.\" a copy of this software and associated documentation files (the
5
.\" "Software"), to deal in the Software without restriction, including
6
.\" without limitation the rights to use, copy, modify, merge, publish,
7
.\" distribute, sublicense, and/or sell copies of the Software, and to
8
.\" permit persons to whom the Software is furnished to do so, subject to
9
.\" the following conditions:
11
.\" The above copyright notice and this permission notice shall be included
12
.\" in all copies or substantial portions of the Software.
14
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
17
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
18
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20
.\" OTHER DEALINGS IN THE SOFTWARE.
22
.\" Except as contained in this notice, the name of the X Consortium shall
23
.\" not be used in advertising or otherwise to promote the sale, use or
24
.\" other dealings in this Software without prior written authorization
25
.\" from the X Consortium.
27
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
28
.\" Digital Equipment Corporation
30
.\" Portions Copyright \(co 1990, 1991 by
33
.\" Permission to use, copy, modify and distribute this documentation for
34
.\" any purpose and without fee is hereby granted, provided that the above
35
.\" copyright notice appears in all copies and that both that copyright notice
36
.\" and this permission notice appear in all copies, and that the names of
37
.\" Digital and Tektronix not be used in in advertising or publicity pertaining
38
.\" to this documentation without specific, written prior permission.
39
.\" Digital and Tektronix makes no representations about the suitability
40
.\" of this documentation for any purpose.
41
.\" It is provided ``as is'' without express or implied warranty.
46
\s+1\fBChapter 5\fP\s-1
48
\s+1\fBPixmap and Cursor Functions\fP\s-1
58
Chapter 5: Pixmap and Cursor Functions
60
Once you have connected to an X server,
61
you can use the Xlib functions to:
63
Create and free pixmaps
65
Create, recolor, and free cursors
67
Creating and Freeing Pixmaps
69
\*(SN Creating and Freeing Pixmaps
72
Pixmaps can only be used on the screen on which they were created.
73
Pixmaps are off-screen resources that are used for various operations,
74
such as defining cursors as tiling patterns
75
or as the source for certain raster operations.
76
Most graphics requests can operate either on a window or on a pixmap.
77
A bitmap is a single bit-plane pixmap.
80
To create a pixmap of a given size, use
82
.IN "XCreatePixmap" "" "@DEF@"
85
Pixmap XCreatePixmap\^(\^\fIdisplay\fP, \fId\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdepth\fP\^)
87
Display *\fIdisplay\fP\^;
91
unsigned int \fIwidth\fP\^, \fIheight\fP\^;
93
unsigned int \fIdepth\fP\^;
96
Specifies the connection to the X server.
98
Specifies which screen the pixmap is created on.
99
.ds Wh , which define the dimensions of the pixmap
104
Specify the width and height\*(Wh.
106
Specifies the depth of the pixmap.
111
function creates a pixmap of the width, height, and depth you specified
112
and returns a pixmap ID that identifies it.
113
It is valid to pass an
115
window to the drawable argument.
116
The width and height arguments must be nonzero,
120
The depth argument must be one of the depths supported by the screen
121
of the specified drawable,
126
The server uses the specified drawable to determine on which screen
127
to create the pixmap.
128
The pixmap can be used only on this screen
129
and only with other drawables of the same depth (see
131
for an exception to this rule).
132
The initial contents of the pixmap are undefined.
143
To free all storage associated with a specified pixmap, use
145
.IN "XFreePixmap" "" "@DEF@"
148
XFreePixmap\^(\^\fIdisplay\fP, \fIpixmap\fP\^)
150
Display *\fIdisplay\fP\^;
152
Pixmap \fIpixmap\fP\^;
155
Specifies the connection to the X server.
157
Specifies the pixmap.
162
function first deletes the association between the pixmap ID and the pixmap.
163
Then, the X server frees the pixmap storage when there are no references to it.
164
The pixmap should never be referenced again.
171
Creating, Recoloring, and Freeing Cursors
173
\*(SN Creating, Recoloring, and Freeing Cursors
176
Each window can have a different cursor defined for it.
177
Whenever the pointer is in a visible window,
178
it is set to the cursor defined for that window.
179
If no cursor was defined for that window,
180
the cursor is the one defined for the parent window.
182
From X's perspective,
183
a cursor consists of a cursor source, mask, colors, and a hotspot.
184
The mask pixmap determines the shape of the cursor and must be a depth
186
The source pixmap must have a depth of one,
187
and the colors determine the colors of the source.
188
The hotspot defines the point on the cursor that is reported
189
when a pointer event occurs.
190
There may be limitations imposed by the hardware on
191
cursors as to size and whether a mask is implemented.
192
.IN "XQueryBestCursor"
194
can be used to find out what sizes are possible.
195
There is a standard font for creating cursors, but
196
Xlib provides functions that you can use to create cursors
197
from an arbitrary font or from bitmaps.
200
To create a cursor from the standard cursor font, use
201
.PN XCreateFontCursor .
202
.IN "XCreateFontCursor" "" "@DEF@"
205
#include <X11/cursorfont.h>
207
Cursor XCreateFontCursor\^(\^\fIdisplay\fP, \fIshape\fP\^)
209
Display *\fIdisplay\fP\^;
211
unsigned int \fIshape\fP\^;
214
Specifies the connection to the X server.
216
Specifies the shape of the cursor.
219
X provides a set of standard cursor shapes in a special font named
221
Applications are encouraged to use this interface for their cursors
222
because the font can be customized for the individual display type.
223
The shape argument specifies which glyph of the standard fonts
226
The hotspot comes from the information stored in the cursor font.
227
The initial colors of a cursor are a black foreground and a white
229
.PN XRecolorCursor ).
230
For further information about cursor shapes,
233
.PN XCreateFontCursor
241
To create a cursor from font glyphs, use
242
.PN XCreateGlyphCursor .
243
.IN "XCreateGlyphCursor" "" "@DEF@"
246
Cursor XCreateGlyphCursor\^(\^\fIdisplay\fP, \fIsource_font\fP\^, \fImask_font\fP\^, \fIsource_char\fP\^, \fImask_char\fP\^,
248
\fIforeground_color\fP\^, \fIbackground_color\fP\^)
250
Display *\fIdisplay\fP\^;
252
Font \fIsource_font\fP\^, \fImask_font\fP\^;
254
unsigned int \fIsource_char\fP\^, \fImask_char\fP\^;
256
XColor *\fIforeground_color\fP\^;
258
XColor *\fIbackground_color\fP\^;
261
Specifies the connection to the X server.
262
.IP \fIsource_font\fP 1i
263
Specifies the font for the source glyph.
264
.IP \fImask_font\fP 1i
265
Specifies the font for the mask glyph or
267
.IP \fIsource_char\fP 1i
268
Specifies the character glyph for the source.
269
.IP \fImask_char\fP 1i
270
Specifies the glyph character for the mask.
271
.IP \fIforeground_color\fP 1i
272
Specifies the RGB values for the foreground of the source.
273
.IP \fIbackground_color\fP 1i
274
Specifies the RGB values for the background of the source.
278
.PN XCreateGlyphCursor
279
function is similar to
280
.PN XCreatePixmapCursor
281
except that the source and mask bitmaps are obtained from the specified
283
The source_char must be a defined glyph in source_font,
287
If mask_font is given,
288
mask_char must be a defined glyph in mask_font,
292
The mask_font and character are optional.
293
The origins of the source_char and mask_char (if defined) glyphs are
294
positioned coincidently and define the hotspot.
295
The source_char and mask_char need not have the same bounding box metrics,
296
and there is no restriction on the placement of the hotspot relative to the bounding
298
If no mask_char is given, all pixels of the source are displayed.
299
You can free the fonts immediately by calling
301
if no further explicit references to them are to be made.
303
For 2-byte matrix fonts,
304
the 16-bit value should be formed with the byte1
305
member in the most significant byte and the byte2 member in the
306
least significant byte.
308
.PN XCreateGlyphCursor
317
To create a cursor from two bitmaps,
319
.PN XCreatePixmapCursor .
320
.IN "XCreatePixmapCursor" "" "@DEF@"
323
Cursor XCreatePixmapCursor\^(\^\fIdisplay\fP, \fIsource\fP\^, \fImask\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^, \fIx\fP\^, \fIy\fP\^)
325
Display *\fIdisplay\fP\^;
327
Pixmap \fIsource\fP\^;
331
XColor *\fIforeground_color\fP\^;
333
XColor *\fIbackground_color\fP\^;
335
unsigned int \fIx\fP\^, \fIy\fP\^;
338
Specifies the connection to the X server.
340
Specifies the shape of the source cursor.
341
.\" *** JIM: NEED TO CHECK THIS. ***
343
Specifies the cursor's source bits to be displayed or
345
.IP \fIforeground_color\fP 1i
346
Specifies the RGB values for the foreground of the source.
347
.IP \fIbackground_color\fP 1i
348
Specifies the RGB values for the background of the source.
349
.ds Xy , which indicate the hotspot relative to the source's origin
354
Specify the x and y coordinates\*(Xy.
358
.PN XCreatePixmapCursor
359
function creates a cursor and returns the cursor ID associated with it.
360
The foreground and background RGB values must be specified using
361
foreground_color and background_color,
362
even if the X server only has a
367
The foreground color is used for the pixels set to 1 in the
368
source, and the background color is used for the pixels set to 0.
369
Both source and mask, if specified, must have depth one (or a
371
error results) but can have any root.
372
The mask argument defines the shape of the cursor.
373
The pixels set to 1 in the mask define which source pixels are displayed,
374
and the pixels set to 0 define which pixels are ignored.
376
all pixels of the source are displayed.
377
The mask, if present, must be the same size as the pixmap defined by the
378
source argument, or a
381
The hotspot must be a point within the source,
386
The components of the cursor can be transformed arbitrarily to meet
388
The pixmaps can be freed immediately if no further explicit references
389
to them are to be made.
390
Subsequent drawing in the source or mask pixmap has an undefined effect on the
392
The X server might or might not make a copy of the pixmap.
394
.PN XCreatePixmapCursor
402
To determine useful cursor sizes, use
403
.PN XQueryBestCursor .
404
.IN "XQueryBestCursor" "" "@DEF@"
407
Status XQueryBestCursor\^(\^\fIdisplay\fP, \fId\fP, \fIwidth\fP\^, \fIheight\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^)
409
Display *\fIdisplay\fP\^;
413
unsigned int \fIwidth\fP\^, \fIheight\fP\^;
415
unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
418
Specifies the connection to the X server.
419
.ds Dr , which indicates the screen
421
Specifies the drawable\*(Dr.
422
.ds Wh \ of the cursor that you want the size information for
427
Specify the width and height\*(Wh.
428
.IP \fIwidth_return\fP 1i
431
.IP \fIheight_return\fP 1i
432
Return the best width and height that is closest to the specified width
436
Some displays allow larger cursors than other displays.
439
function provides a way to find out what size cursors are actually
440
possible on the display.
441
.IN "Cursor" "limitations"
442
It returns the largest size that can be displayed.
443
Applications should be prepared to use smaller cursors on displays that
444
cannot support large ones.
452
To change the color of a given cursor, use
454
.IN "XRecolorCursor" "" "@DEF@"
457
XRecolorCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^)
459
Display *\fIdisplay\fP\^;
461
Cursor \fIcursor\fP\^;
463
XColor *\fIforeground_color\fP\^, *\fIbackground_color\fP\^;
466
Specifies the connection to the X server.
468
Specifies the cursor.
469
.IP \fIforeground_color\fP 1i
470
Specifies the RGB values for the foreground of the source.
471
.IP \fIbackground_color\fP 1i
472
Specifies the RGB values for the background of the source.
477
function changes the color of the specified cursor, and
478
if the cursor is being displayed on a screen,
479
the change is visible immediately.
480
The pixel members of the
482
structures are ignored; only the RGB values are used.
490
To free (destroy) a given cursor, use
492
.IN "XFreeCursor" "" "@DEF@"
495
XFreeCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^)
497
Display *\fIdisplay\fP\^;
499
Cursor \fIcursor\fP\^;
502
Specifies the connection to the X server.
504
Specifies the cursor.
509
function deletes the association between the cursor resource ID
510
and the specified cursor.
511
The cursor storage is freed when no other resource references it.
512
The specified cursor ID should not be referred to again.
added
removed
specs/libX11/CH05
