1
<?xml version="1.0" encoding="UTF-8" ?>
2
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
4
<chapter id="pixmap_and_cursor_functions">
5
<title>Pixmap and Cursor Functions</title>
6
<sect1 id="Creating_and_Freeing_Pixmaps">
7
<title>Creating and Freeing Pixmaps</title>
9
<!-- (SN Creating and Freeing Pixmaps -->
13
Pixmaps can only be used on the screen on which they were created.
14
Pixmaps are off-screen resources that are used for various operations,
15
such as defining cursors as tiling patterns
16
or as the source for certain raster operations.
17
Most graphics requests can operate either on a window or on a pixmap.
18
A bitmap is a single bit-plane pixmap.
23
To create a pixmap of a given size, use
24
<function>XCreatePixmap</function>.
25
<indexterm significance="preferred"><primary>XCreatePixmap</primary></indexterm>
29
<funcdef>Pixmap <function>XCreatePixmap</function></funcdef>
30
<paramdef>Display<parameter> *display</parameter></paramdef>
31
<paramdef>Drawable<parameter> d</parameter></paramdef>
32
<paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
33
<paramdef>unsignedint<parameter> depth</parameter></paramdef>
40
<emphasis remap='I'>display</emphasis>
44
Specifies the connection to the X server.
50
<emphasis remap='I'>d</emphasis>
54
Specifies which screen the pixmap is created on.
55
<!-- .ds Wh , which define the dimensions of the pixmap -->
61
<emphasis remap='I'>width</emphasis>
72
<emphasis remap='I'>height</emphasis>
76
Specify the width and height(Wh.
82
<emphasis remap='I'>depth</emphasis>
86
Specifies the depth of the pixmap.
96
<function>XCreatePixmap</function>
97
function creates a pixmap of the width, height, and depth you specified
98
and returns a pixmap ID that identifies it.
99
It is valid to pass an
100
<symbol>InputOnly</symbol>
101
window to the drawable argument.
102
The width and height arguments must be nonzero,
104
<errorname>BadValue</errorname>
106
The depth argument must be one of the depths supported by the screen
107
of the specified drawable,
109
<errorname>BadValue</errorname>
114
The server uses the specified drawable to determine on which screen
115
to create the pixmap.
116
The pixmap can be used only on this screen
117
and only with other drawables of the same depth (see
118
<function>XCopyPlane</function>
119
for an exception to this rule).
120
The initial contents of the pixmap are undefined.
124
<function>XCreatePixmap</function>
126
<errorname>BadAlloc</errorname>,
127
<errorname>BadDrawable</errorname>,
129
<errorname>BadValue</errorname>
135
To free all storage associated with a specified pixmap, use
136
<function>XFreePixmap</function>.
137
<indexterm significance="preferred"><primary>XFreePixmap</primary></indexterm>
141
<funcdef><function>XFreePixmap</function></funcdef>
142
<paramdef>Display<parameter> *display</parameter></paramdef>
143
<paramdef>Pixmap<parameter> pixmap</parameter></paramdef>
150
<emphasis remap='I'>display</emphasis>
154
Specifies the connection to the X server.
160
<emphasis remap='I'>pixmap</emphasis>
164
Specifies the pixmap.
174
<function>XFreePixmap</function>
175
function first deletes the association between the pixmap ID and the pixmap.
176
Then, the X server frees the pixmap storage when there are no references to it.
177
The pixmap should never be referenced again.
181
<function>XFreePixmap</function>
183
<errorname>BadPixmap</errorname>
187
<sect1 id="Creating_Recoloring_and_Freeing_Cursors">
188
<title>Creating, Recoloring, and Freeing Cursors</title>
190
<!-- (SN Creating, Recoloring, and Freeing Cursors -->
194
Each window can have a different cursor defined for it.
195
Whenever the pointer is in a visible window,
196
it is set to the cursor defined for that window.
197
If no cursor was defined for that window,
198
the cursor is the one defined for the parent window.
202
From X's perspective,
203
a cursor consists of a cursor source, mask, colors, and a hotspot.
204
The mask pixmap determines the shape of the cursor and must be a depth
206
The source pixmap must have a depth of one,
207
and the colors determine the colors of the source.
208
The hotspot defines the point on the cursor that is reported
209
when a pointer event occurs.
210
There may be limitations imposed by the hardware on
211
cursors as to size and whether a mask is implemented.
212
<indexterm><primary>XQueryBestCursor</primary></indexterm>
213
<function>XQueryBestCursor</function>
214
can be used to find out what sizes are possible.
215
There is a standard font for creating cursors, but
216
Xlib provides functions that you can use to create cursors
217
from an arbitrary font or from bitmaps.
222
To create a cursor from the standard cursor font, use
223
<function>XCreateFontCursor</function>.
226
#include <X11/cursorfont.h>
229
<indexterm significance="preferred"><primary>XCreateFontCursor</primary></indexterm>
233
<funcdef>Cursor <function>XCreateFontCursor</function></funcdef>
234
<paramdef>Display<parameter> *display</parameter></paramdef>
235
<paramdef>unsignedint<parameter> shape</parameter></paramdef>
243
<emphasis remap='I'>display</emphasis>
247
Specifies the connection to the X server.
253
<emphasis remap='I'>shape</emphasis>
257
Specifies the shape of the cursor.
266
X provides a set of standard cursor shapes in a special font named
268
Applications are encouraged to use this interface for their cursors
269
because the font can be customized for the individual display type.
270
The shape argument specifies which glyph of the standard fonts
275
The hotspot comes from the information stored in the cursor font.
276
The initial colors of a cursor are a black foreground and a white
278
<function>XRecolorCursor</function>).
279
For further information about cursor shapes,
284
<function>XCreateFontCursor</function>
286
<errorname>BadAlloc</errorname>
288
<errorname>BadValue</errorname>
294
To create a cursor from font glyphs, use
295
<function>XCreateGlyphCursor</function>.
296
<indexterm significance="preferred"><primary>XCreateGlyphCursor</primary></indexterm>
300
<funcdef>Cursor <function>XCreateGlyphCursor</function></funcdef>
301
<paramdef>Display<parameter> *display</parameter></paramdef>
302
<paramdef>Fontsource_font,<parameter> mask_font</parameter></paramdef>
303
<paramdef>unsignedintsource_char,<parameter> mask_char</parameter></paramdef>
304
<paramdef>XColor<parameter> *foreground_color</parameter></paramdef>
305
<paramdef>XColor<parameter> *background_color</parameter></paramdef>
312
<emphasis remap='I'>display</emphasis>
316
Specifies the connection to the X server.
322
<emphasis remap='I'>source_font</emphasis>
326
Specifies the font for the source glyph.
332
<emphasis remap='I'>mask_font</emphasis>
336
Specifies the font for the mask glyph or
337
<symbol>None</symbol>.
343
<emphasis remap='I'>source_char</emphasis>
347
Specifies the character glyph for the source.
353
<emphasis remap='I'>mask_char</emphasis>
357
Specifies the glyph character for the mask.
363
<emphasis remap='I'>foreground_color</emphasis>
367
Specifies the <acronym>RGB</acronym> values for the foreground of the source.
373
<emphasis remap='I'>background_color</emphasis>
377
Specifies the <acronym>RGB</acronym> values for the background of the source.
387
<function>XCreateGlyphCursor</function>
388
function is similar to
389
<function>XCreatePixmapCursor</function>
390
except that the source and mask bitmaps are obtained from the specified
392
The source_char must be a defined glyph in source_font,
394
<errorname>BadValue</errorname>
396
If mask_font is given,
397
mask_char must be a defined glyph in mask_font,
399
<errorname>BadValue</errorname>
401
The mask_font and character are optional.
402
The origins of the source_char and mask_char (if defined) glyphs are
403
positioned coincidently and define the hotspot.
404
The source_char and mask_char need not have the same bounding box metrics,
405
and there is no restriction on the placement of the hotspot relative to the bounding
407
If no mask_char is given, all pixels of the source are displayed.
408
You can free the fonts immediately by calling
409
<function>XFreeFont</function>
410
if no further explicit references to them are to be made.
414
For 2-byte matrix fonts,
415
the 16-bit value should be formed with the byte1
416
member in the most significant byte and the byte2 member in the
417
least significant byte.
421
<function>XCreateGlyphCursor</function>
423
<errorname>BadAlloc</errorname>,
424
<errorname>BadFont</errorname>,
426
<errorname>BadValue</errorname>
432
To create a cursor from two bitmaps,
434
<function>XCreatePixmapCursor</function>.
435
<indexterm significance="preferred"><primary>XCreatePixmapCursor</primary></indexterm>
439
<funcdef>Cursor <function>XCreatePixmapCursor</function></funcdef>
440
<paramdef>Display<parameter> *display</parameter></paramdef>
441
<paramdef>Pixmap<parameter> source</parameter></paramdef>
442
<paramdef>Pixmap<parameter> mask</parameter></paramdef>
443
<paramdef>XColor<parameter> *foreground_color</parameter></paramdef>
444
<paramdef>XColor<parameter> *background_color</parameter></paramdef>
445
<paramdef>unsignedintx,<parameter> y</parameter></paramdef>
452
<emphasis remap='I'>display</emphasis>
456
Specifies the connection to the X server.
462
<emphasis remap='I'>source</emphasis>
466
Specifies the shape of the source cursor.
467
<!-- .\" *** JIM: NEED TO CHECK THIS. *** -->
473
<emphasis remap='I'>mask</emphasis>
477
Specifies the cursor's source bits to be displayed or
478
<symbol>None</symbol>.
484
<emphasis remap='I'>foreground_color</emphasis>
488
Specifies the <acronym>RGB</acronym> values for the foreground of the source.
494
<emphasis remap='I'>background_color</emphasis>
498
Specifies the <acronym>RGB</acronym> values for the background of the source.
499
<!-- .ds Xy , which indicate the hotspot relative to the source's origin -->
505
<emphasis remap='I'>x</emphasis>
516
<emphasis remap='I'>y</emphasis>
520
Specify the x and y coordinates(Xy.
530
<function>XCreatePixmapCursor</function>
531
function creates a cursor and returns the cursor ID associated with it.
532
The foreground and background <acronym>RGB</acronym> values must be specified using
533
foreground_color and background_color,
534
even if the X server only has a
535
<symbol>StaticGray</symbol>
537
<symbol>GrayScale</symbol>
539
The foreground color is used for the pixels set to 1 in the
540
source, and the background color is used for the pixels set to 0.
541
Both source and mask, if specified, must have depth one (or a
542
<errorname>BadMatch</errorname>
543
error results) but can have any root.
544
The mask argument defines the shape of the cursor.
545
The pixels set to 1 in the mask define which source pixels are displayed,
546
and the pixels set to 0 define which pixels are ignored.
548
all pixels of the source are displayed.
549
The mask, if present, must be the same size as the pixmap defined by the
550
source argument, or a
551
<errorname>BadMatch</errorname>
553
The hotspot must be a point within the source,
555
<errorname>BadMatch</errorname>
560
The components of the cursor can be transformed arbitrarily to meet
562
The pixmaps can be freed immediately if no further explicit references
563
to them are to be made.
564
Subsequent drawing in the source or mask pixmap has an undefined effect on the
566
The X server might or might not make a copy of the pixmap.
570
<function>XCreatePixmapCursor</function>
572
<errorname>BadAlloc</errorname>
574
<errorname>BadPixmap</errorname>
580
To determine useful cursor sizes, use
581
<function>XQueryBestCursor</function>.
582
<indexterm significance="preferred"><primary>XQueryBestCursor</primary></indexterm>
586
<funcdef>Status <function>XQueryBestCursor</function></funcdef>
587
<paramdef>Display<parameter> *display</parameter></paramdef>
588
<paramdef>Drawable<parameter> d</parameter></paramdef>
589
<paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
590
<paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
597
<emphasis remap='I'>display</emphasis>
601
Specifies the connection to the X server.
602
<!-- .ds Dr , which indicates the screen -->
608
<emphasis remap='I'>d</emphasis>
612
Specifies the drawable(Dr.
613
<!-- .ds Wh \ of the cursor that you want the size information for -->
619
<emphasis remap='I'>width</emphasis>
630
<emphasis remap='I'>height</emphasis>
634
Specify the width and height(Wh.
640
<emphasis remap='I'>width_return</emphasis>
651
<emphasis remap='I'>height_return</emphasis>
655
Return the best width and height that is closest to the specified width
665
Some displays allow larger cursors than other displays.
667
<function>XQueryBestCursor</function>
668
function provides a way to find out what size cursors are actually
669
possible on the display.
670
<indexterm ><primary>Cursor</primary><secondary>limitations</secondary></indexterm>
671
It returns the largest size that can be displayed.
672
Applications should be prepared to use smaller cursors on displays that
673
cannot support large ones.
677
<function>XQueryBestCursor</function>
679
<errorname>BadDrawable</errorname>
685
To change the color of a given cursor, use
686
<function>XRecolorCursor</function>.
687
<indexterm significance="preferred"><primary>XRecolorCursor</primary></indexterm>
691
<funcdef><function>XRecolorCursor</function></funcdef>
692
<paramdef>Display<parameter> *display</parameter></paramdef>
693
<paramdef>Cursor<parameter> cursor</parameter></paramdef>
694
<paramdef>XColor*foreground_color,<parameter> *background_color</parameter></paramdef>
701
<emphasis remap='I'>display</emphasis>
705
Specifies the connection to the X server.
711
<emphasis remap='I'>cursor</emphasis>
715
Specifies the cursor.
721
<emphasis remap='I'>foreground_color</emphasis>
725
Specifies the <acronym>RGB</acronym> values for the foreground of the source.
731
<emphasis remap='I'>background_color</emphasis>
735
Specifies the <acronym>RGB</acronym> values for the background of the source.
745
<function>XRecolorCursor</function>
746
function changes the color of the specified cursor, and
747
if the cursor is being displayed on a screen,
748
the change is visible immediately.
749
The pixel members of the
750
<structname>XColor</structname>
751
structures are ignored; only the <acronym>RGB</acronym> values are used.
755
<function>XRecolorCursor</function>
757
<errorname>BadCursor</errorname>
763
To free (destroy) a given cursor, use
764
<function>XFreeCursor</function>.
765
<indexterm significance="preferred"><primary>XFreeCursor</primary></indexterm>
769
<funcdef><function>XFreeCursor</function></funcdef>
770
<paramdef>Display<parameter> *display</parameter></paramdef>
771
<paramdef>Cursor<parameter> cursor</parameter></paramdef>
778
<emphasis remap='I'>display</emphasis>
782
Specifies the connection to the X server.
788
<emphasis remap='I'>cursor</emphasis>
792
Specifies the cursor.
802
<function>XFreeCursor</function>
803
function deletes the association between the cursor resource ID
804
and the specified cursor.
805
The cursor storage is freed when no other resource references it.
806
The specified cursor ID should not be referred to again.
810
<function>XFreeCursor</function>
812
<errorname>BadCursor</errorname>
added
removed
specs/libX11/CH05.xml
