10.2 Creating Cursors

The following paragraphs describe the CLX functions used to create and free cursor objects.

create-cursor

&key :source :mask :x :y :foreground :background

Function

:source: The source pixmap. This argument is required.
:mask: The mask pixmap.
:x, :y: The hot spot position in the :source. This argument is required.
:foreground: A color object specifying the foreground color. This argument is required.
:background: A color object specifying the background color. This argument is required.

Creates and returns a cursor. :x and :y define the position of the hot spot relative to the origin of the :source. :foreground and :background colors must be specified, even if the server only has a :static-gray or :gray-scale screen. The :source, :x, and :y arguments must also be specified.

The cursor image is drawn by drawing a pixel from the :source bitmap at every position where the corresponding bit in the :mask bitmap is 1. If the corresponding :source bit is 1, a pixel is drawn in the :foreground color; otherwise, a pixel is drawn in the :back-ground color. If the :mask is omitted, all :source pixels are drawn. If given, the :mask must be the same size as the :source.

An X server may not be able to support every cursor size. A server is free to modify any component of the cursor to satisfy hardware or software limitations.

The :source and :mask can be freed immediately after the cursor is created. Subsequent drawing in the :source or :mask pixmap has an undefined effect on the cursor.

cursor: Type cursor.

create-glyph-cursor

&key :source-font :source-char :mask-font (:mask-char 0) :foreground :background

Function

:source-font: The source font. This is a required argument.
:source-char: An index specifying a glyph in the source font. This is a required argument.
:mask-font: The mask font.
:mask-char: An index specifying a glyph in the mask font.
:foreground: A color object specifying the foreground color. This is a required argument.
:background: A color object specifying the background color. This is a required argument.

Creates and returns a cursor defined by font glyphs. The source bitmap is defined by the :source-font and :source-char . The mask bitmap is defined by the :mask-font and :mask-char. It is an error if the :source-char and :mask-char are not valid indexes for the :source-font and :mask-font, respectively. The hot spot position is defined by the "character origin" of the source glyph, that is, the position [- char-left-bearing, char-ascent] relative to the upper left corner of the source glyph bitmap.

Source and mask bits are compared after aligning the character origins of the source and mask glyphs. The source and mask glyphs need not have the same size or character origin position. If the :mask-font is omitted, all source pixels are drawn.

An X server may not be able to support every cursor size. A server is free to modify any component of the cursor to satisfy hardware or software limitations.

Either of the :source-font or :mask-font can be closed after the cursor is created.

cursor: Type cursor.