XCreateMultiColorCursor Extension Function

x11 R6 Technical Reference

XCreateMultiColorCursor Extension Function

Purpose

Creates a multicolored cursor and returns the resource ID associated with the cursor.

Library

Enhanced X-Windows Library (libXext.a)

C Syntax

Cursor XCreateMultiColorCursor (DisplayPtr, Source, Number, Colors, X, Y)
Display *DisplayPtr;
Pixmap Source;
INT32 Number;
XColor *Colors;
INT32 X, Y;

Description

The XCreateMultiColorCursor extension function creates a multicolored cursor and returns the X server cursor resource ID associated with the cursor. This cursor ID can then be used with the XRecolorMultiColorCursor extension function, and the XFreeCursor and XDefineCursor functions. The XDefineCursor function associates the cursor resource with a window ID.

The cursor is colored according to the colors specified in an array of XColor structures. The pixel value in each array element corresponds to the pixel value in the source pixmap. This pixel value in the source pixmap is colored with color specified by the red, green, and blue (RGB) values in the same array element. Typically, the 0 (zero) value in a cursor pixmap is considered transparent.

To create a multicolored cursor there must be hardware available that contains multiple cursor planes. If hardware support is not available, a software cursor resource is created by using the color specified by array element 1 for any pixel in the pixmap that contains a pixel value. A pixel value of 0 continues to be transparent.

Any source pixmap pixel value without a corresponding RGB value specified in the array of XColor structures is considered undefined. Any pixel value outside the range of the hardware capability is ignored.

Parameters

Colors	Specifies an array of XColor structures that describes the values for each pixel value in the source pixmap.
DisplayPtr	Specifies the connection to the X server.
Number	Specifies the number of colors in the Colors parameter.
Source	Specifies the X server resource ID of the pixmap to be used for the cursor.
X	Indicates the x coordinate for the cursor hotspot relative to the origin of the source pixmap. This coordinate must be a point within the source pixmap.
Y	Indicates the y coordinate for the cursor hotspot relative to the origin of the source pixmap. This coordinate must be a point within the source pixmap.

Error Codes

BadAlloc

BadDrawable

BadMatch

BadPixmap

Return Values

CursorID	Indicates that the XCreateMultiColorCursor extension function succeeded.
0	Indicates that the XCreateMultiColorCursor extension function failed.

Related Information

Using Extensions in AIXwindows in AIX Version 4.3 AIXwindows Programming Guide.

The XColor data structure.

The XRecolorMultiColorCursor extension function.

The XDefineCursor function, XFreeCursor function.

AIXwindows Overview for Programmers in AIX Version 4.3 AIXwindows Programming Guide.