---
name: "GetCursor"
section: "2"
platform: "linux"
package: "perl-tk"
version: "b11.02-5"
release: "Debian 1.3 (Bo)"
platforms: ["linux"]
url: "https://new.carta.tech/GetCursor"
---

# GetCursor(2)

maintain database of cursors

## NAME

Tk\_GetCursor, Tk\_GetCursorFromData, Tk\_NameOfCursor, Tk\_FreeCursor - maintain database of cursors

## SYNOPSIS

```
#include <tk.h>

Cursor
Tk_GetCursor(interp, tkwin, nameId)

Cursor
Tk_GetCursorFromData(interp, tkwin, source, mask, width, height, xHot, yHot, fg, bg)

char *
Tk_NameOfCursor(display, cursor)

Tk_FreeCursor(display, cursor)
```

## ARGUMENTS

Interpreter to use for error reporting. Token for window in which the cursor will be used. Description of cursor;  see below for possible values. Data for cursor bitmap, in standard bitmap format. Data for mask bitmap, in standard bitmap format. Width of *source* and *mask*. Height of *source* and *mask*. X-location of cursor hot-spot. Y-location of cursor hot-spot. Textual description of foreground color for cursor. Textual description of background color for cursor. Display for which *cursor* was allocated. X identifier for cursor.  If passed to**Tk\_FreeCursor**, must have been returned by some previous call to **Tk\_GetCursor** or **Tk\_GetCursorFromData**.

## DESCRIPTION

These procedures manage a collection of cursors being used by an application.  The procedures allow cursors to be re-used efficiently, thereby avoiding server overhead, and also allow cursors to be named with character strings (actually Tk\_Uids).

**Tk\_GetCursor** takes as argument a Tk\_Uid describing a cursor, and returns the X identifier for a cursor corresponding to the description.  It re-uses an existing cursor if possible and creates a new one otherwise.  *NameId* must be a standard Tcl list with one of the following forms:

- *name* \[*fgColor* \[*bgColor*\]\]

  *Name* is the name of a cursor in the standard X cursor font, i.e., any of the names defined in **cursorfont.h**, without the **XC\_**.  Some example values are **X\_cursor**, **hand2**, or **left\_ptr**.  Appendix B of \`\`The X Window System'' by Scheifler & Gettys has illustrations showing what each of these cursors looks like.  If *fgColor* and *bgColor* are both specified, they give the foreground and background colors to use for the cursor (any of the forms acceptable to **Tk\_GetColor** may be used).  If only *fgColor* is specified, then there will be no background color:  the background will be transparent. If no colors are specified, then the cursor will use black for its foreground color and white for its background color.

- **@***sourceName maskName fgColor bgColor*

  In this form, *sourceName* and *maskName* are the names of files describing bitmaps for the cursor's source bits and mask. Each file must be in standard X11 or X10 bitmap format. *FgColor* and *bgColor*  indicate the colors to use for the cursor, in any of the forms acceptable to **Tk\_GetColor**.

- **@***sourceName fgColor*

  This form is similar to the one above, except that the source is used as mask also.  This means that the cursor's background is transparent.

**Tk\_GetCursorFromData** allows cursors to be created from in-memory descriptions of their source and mask bitmaps.  *Source* points to standard bitmap data for the cursor's source bits, and *mask* points to standard bitmap data describing which pixels of *source* are to be drawn and which are to be considered transparent.  *Width* and *height* give the dimensions of the cursor, *xHot* and *yHot* indicate the location of the cursor's hot-spot (the point that is reported when an event occurs), and *fg* and *bg* describe the cursor's foreground and background colors textually (any of the forms suitable for **Tk\_GetColor** may be used).  Typically, the arguments to **Tk\_GetCursorFromData** are created by including a cursor file directly into the source code for a program, as in the following example:

```
Cursor cursor;
#include "source.cursor"
#include "mask.cursor"
cursor = Tk_GetCursorFromData(interp, tkwin, source_bits,
	mask_bits, source_width, source_height, source_x_hot,
	source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue"));
```

Under normal conditions, **Tk\_GetCursor** and **Tk\_GetCursorFromData** will return an identifier for the requested cursor.  If an error occurs in creating the cursor, such as when *nameId* refers to a non-existent file, then **None** is returned and an error message will be stored in *interp-\>result*.

**Tk\_GetCursor** and **Tk\_GetCursorFromData** maintain a database of all the cursors they have created.  Whenever possible, a call to **Tk\_GetCursor** or **Tk\_GetCursorFromData** will return an existing cursor rather than creating a new one.  This approach can substantially reduce server overhead, so the Tk procedures should generally be used in preference to Xlib procedures like **XCreateFontCursor** or **XCreatePixmapCursor**, which create a new cursor on each call.

The procedure **Tk\_NameOfCursor** is roughly the inverse of **Tk\_GetCursor**.  If its *cursor* argument was created by **Tk\_GetCursor**, then the return value is the *nameId* argument that was passed to **Tk\_GetCursor** to create the cursor.  If *cursor* was created by a call to **Tk\_GetCursorFromData**, or by any other mechanism, then the return value is a hexadecimal string giving the X identifier for the cursor. Note:  the string returned by **Tk\_NameOfCursor** is only guaranteed to persist until the next call to **Tk\_NameOfCursor**.

When a cursor returned by **Tk\_GetCursor** or **Tk\_GetCursorFromData** is no longer needed, **Tk\_FreeCursor** should be called to release it. There should be exactly one call to **Tk\_FreeCursor** for each call to **Tk\_GetCursor** or **Tk\_GetCursorFromData**. When a cursor is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) **Tk\_FreeCursor** will release it to the X server and remove it from the database.

## BUGS

In determining whether an existing cursor can be used to satisfy a new request, **Tk\_GetCursor** and **Tk\_GetCursorFromData** consider only the immediate values of their arguments.  For example, when a file name is passed to **Tk\_GetCursor**, **Tk\_GetCursor** will assume it is safe to re-use an existing cursor created from the same file name:  it will not check to see whether the file itself has changed, or whether the current directory has changed, thereby causing the name to refer to a different file.  Similarly, **Tk\_GetCursorFromData** assumes that if the same *source* pointer is used in two different calls, then the pointers refer to the same data;  it does not check to see if the actual data values have changed.

## KEYWORDS

cursor