Cursors

## Cursors Cursors — Standard and pixmap cursors |

## Synopsis

    #include <gdk/gdk.h>

    struct      GdkCursor;
    enum        GdkCursorType;
    GdkCursor*  gdk_cursor_new                  (GdkCursorType cursor_type);
    GdkCursor*  gdk_cursor_new_from_pixmap      (GdkPixmap *source,
                                                 GdkPixmap *mask,
                                                 const GdkColor *fg,
                                                 const GdkColor *bg,
                                                 gint x,
                                                 gint y);
    GdkCursor*  gdk_cursor_new_from_pixbuf      (GdkDisplay *display,
                                                 GdkPixbuf *pixbuf,
                                                 gint x,
                                                 gint y);
    GdkCursor*  gdk_cursor_new_for_display      (GdkDisplay *display,
                                                 GdkCursorType cursor_type);
    GdkDisplay* gdk_cursor_get_display          (GdkCursor *cursor);
    GdkCursor*  gdk_cursor_ref                  (GdkCursor *cursor);
    void        gdk_cursor_unref                (GdkCursor *cursor);
    #define     gdk_cursor_destroy

## Description

## Details

### struct GdkCursor

    struct GdkCursor {

      GdkCursorType type;
      guint ref_count;
    };

A GdkCursor structure represents a cursor.

### enum GdkCursorType

    typedef enum
    {
      GDK_X_CURSOR 		  = 0,
      GDK_ARROW 		  = 2,
      GDK_BASED_ARROW_DOWN    = 4,
      GDK_BASED_ARROW_UP 	  = 6,
      GDK_BOAT 		  = 8,
      GDK_BOGOSITY 		  = 10,
      GDK_BOTTOM_LEFT_CORNER  = 12,
      GDK_BOTTOM_RIGHT_CORNER = 14,
      GDK_BOTTOM_SIDE 	  = 16,
      GDK_BOTTOM_TEE 	  = 18,
      GDK_BOX_SPIRAL 	  = 20,
      GDK_CENTER_PTR 	  = 22,
      GDK_CIRCLE 		  = 24,
      GDK_CLOCK	 	  = 26,
      GDK_COFFEE_MUG 	  = 28,
      GDK_CROSS 		  = 30,
      GDK_CROSS_REVERSE 	  = 32,
      GDK_CROSSHAIR 	  = 34,
      GDK_DIAMOND_CROSS 	  = 36,
      GDK_DOT 		  = 38,
      GDK_DOTBOX 		  = 40,
      GDK_DOUBLE_ARROW 	  = 42,
      GDK_DRAFT_LARGE 	  = 44,
      GDK_DRAFT_SMALL 	  = 46,
      GDK_DRAPED_BOX 	  = 48,
      GDK_EXCHANGE 		  = 50,
      GDK_FLEUR 		  = 52,
      GDK_GOBBLER 		  = 54,
      GDK_GUMBY 		  = 56,
      GDK_HAND1 		  = 58,
      GDK_HAND2 		  = 60,
      GDK_HEART 		  = 62,
      GDK_ICON 		  = 64,
      GDK_IRON_CROSS 	  = 66,
      GDK_LEFT_PTR 		  = 68,
      GDK_LEFT_SIDE 	  = 70,
      GDK_LEFT_TEE 		  = 72,
      GDK_LEFTBUTTON 	  = 74,
      GDK_LL_ANGLE 		  = 76,
      GDK_LR_ANGLE 	 	  = 78,
      GDK_MAN 		  = 80,
      GDK_MIDDLEBUTTON 	  = 82,
      GDK_MOUSE 		  = 84,
      GDK_PENCIL 		  = 86,
      GDK_PIRATE 		  = 88,
      GDK_PLUS 		  = 90,
      GDK_QUESTION_ARROW 	  = 92,
      GDK_RIGHT_PTR 	  = 94,
      GDK_RIGHT_SIDE 	  = 96,
      GDK_RIGHT_TEE 	  = 98,
      GDK_RIGHTBUTTON 	  = 100,
      GDK_RTL_LOGO 		  = 102,
      GDK_SAILBOAT 		  = 104,
      GDK_SB_DOWN_ARROW 	  = 106,
      GDK_SB_H_DOUBLE_ARROW   = 108,
      GDK_SB_LEFT_ARROW 	  = 110,
      GDK_SB_RIGHT_ARROW 	  = 112,
      GDK_SB_UP_ARROW 	  = 114,
      GDK_SB_V_DOUBLE_ARROW   = 116,
      GDK_SHUTTLE 		  = 118,
      GDK_SIZING 		  = 120,
      GDK_SPIDER		  = 122,
      GDK_SPRAYCAN 		  = 124,
      GDK_STAR 		  = 126,
      GDK_TARGET 		  = 128,
      GDK_TCROSS 		  = 130,
      GDK_TOP_LEFT_ARROW 	  = 132,
      GDK_TOP_LEFT_CORNER 	  = 134,
      GDK_TOP_RIGHT_CORNER 	  = 136,
      GDK_TOP_SIDE 		  = 138,
      GDK_TOP_TEE 		  = 140,
      GDK_TREK 		  = 142,
      GDK_UL_ANGLE 		  = 144,
      GDK_UMBRELLA 		  = 146,
      GDK_UR_ANGLE 		  = 148,
      GDK_WATCH 		  = 150,
      GDK_XTERM 		  = 152,
      GDK_LAST_CURSOR,
      GDK_CURSOR_IS_PIXMAP 	= -1
    } GdkCursorType;

The standard cursors available.

`GDK_X_CURSOR` |
`GDK_ARROW` |
`GDK_BASED_ARROW_DOWN` |
`GDK_BASED_ARROW_UP` |
`GDK_BOAT` |
`GDK_BOGOSITY` |
`GDK_BOTTOM_LEFT_CORNER` |
`GDK_BOTTOM_RIGHT_CORNER` |
`GDK_BOTTOM_SIDE` |
`GDK_BOTTOM_TEE` |
`GDK_BOX_SPIRAL` |
`GDK_CENTER_PTR` |
`GDK_CIRCLE` |
`GDK_CLOCK` |
`GDK_COFFEE_MUG` |
`GDK_CROSS` |
`GDK_CROSS_REVERSE` |
`GDK_CROSSHAIR` |
`GDK_DIAMOND_CROSS` |
`GDK_DOT` |
`GDK_DOTBOX` |
`GDK_DOUBLE_ARROW` |
`GDK_DRAFT_LARGE` |
`GDK_DRAFT_SMALL` |
`GDK_DRAPED_BOX` |
`GDK_EXCHANGE` |
`GDK_FLEUR` |
`GDK_GOBBLER` |
`GDK_GUMBY` |
`GDK_HAND1` |
`GDK_HAND2` |
`GDK_HEART` |
`GDK_ICON` |
`GDK_IRON_CROSS` |
`GDK_LEFT_PTR` |
`GDK_LEFT_SIDE` |
`GDK_LEFT_TEE` |
`GDK_LEFTBUTTON` |
`GDK_LL_ANGLE` |
`GDK_LR_ANGLE` |
`GDK_MAN` |
`GDK_MIDDLEBUTTON` |
`GDK_MOUSE` |
`GDK_PENCIL` |
`GDK_PIRATE` |
`GDK_PLUS` |
`GDK_QUESTION_ARROW` |
`GDK_RIGHT_PTR` |
`GDK_RIGHT_SIDE` |
`GDK_RIGHT_TEE` |
`GDK_RIGHTBUTTON` |
`GDK_RTL_LOGO` |
`GDK_SAILBOAT` |
`GDK_SB_DOWN_ARROW` |
`GDK_SB_H_DOUBLE_ARROW` |
`GDK_SB_LEFT_ARROW` |
`GDK_SB_RIGHT_ARROW` |
`GDK_SB_UP_ARROW` |
`GDK_SB_V_DOUBLE_ARROW` |
`GDK_SHUTTLE` |
`GDK_SIZING` |
`GDK_SPIDER` |
`GDK_SPRAYCAN` |
`GDK_STAR` |
`GDK_TARGET` |
`GDK_TCROSS` |
`GDK_TOP_LEFT_ARROW` |
`GDK_TOP_LEFT_CORNER` |
`GDK_TOP_RIGHT_CORNER` |
`GDK_TOP_SIDE` |
`GDK_TOP_TEE` |
`GDK_TREK` |
`GDK_UL_ANGLE` |
`GDK_UMBRELLA` |
`GDK_UR_ANGLE` |
`GDK_WATCH` |
`GDK_XTERM` |
`GDK_LAST_CURSOR` |
`GDK_CURSOR_IS_PIXMAP` | type of cursors constructed with `gdk_cursor_new_from_pixmap()`.

### gdk_cursor_new ()

    GdkCursor*  gdk_cursor_new                  (GdkCursorType cursor_type);

Creates a new cursor from the set of builtin cursors for the default display. See `gdk_cursor_new_for_display()`.

To make the cursor invisible, use `gdk_cursor_new_from_pixmap()` to create a cursor with no pixels in it.

`cursor_type` : | cursor to create
Returns : | a new GdkCursor

### gdk_cursor_new_from_pixmap ()

    GdkCursor*  gdk_cursor_new_from_pixmap      (GdkPixmap *source,
                                                 GdkPixmap *mask,
                                                 const GdkColor *fg,
                                                 const GdkColor *bg,
                                                 gint x,
                                                 gint y);

Creates a new cursor from a given pixmap and mask. Both the pixmap and mask must have a depth of 1 (i.e. each pixel has only 2 values - on or off). The standard cursor size is 16 by 16 pixels. You can create a bitmap from inline data as in the below example.

Example 6. Creating a custom cursor

    /* This data is in X bitmap format, and can be created with the 'bitmap'
       utility. */
    #define cursor1_width 16
    #define cursor1_height 16
    static unsigned char cursor1_bits[] = {
      0x80, 0x01, 0x40, 0x02, 0x20, 0x04, 0x10, 0x08, 0x08, 0x10, 0x04, 0x20,
      0x82, 0x41, 0x41, 0x82, 0x41, 0x82, 0x82, 0x41, 0x04, 0x20, 0x08, 0x10,
      0x10, 0x08, 0x20, 0x04, 0x40, 0x02, 0x80, 0x01};

    static unsigned char cursor1mask_bits[] = {
      0x80, 0x01, 0xc0, 0x03, 0x60, 0x06, 0x30, 0x0c, 0x18, 0x18, 0x8c, 0x31,
      0xc6, 0x63, 0x63, 0xc6, 0x63, 0xc6, 0xc6, 0x63, 0x8c, 0x31, 0x18, 0x18,
      0x30, 0x0c, 0x60, 0x06, 0xc0, 0x03, 0x80, 0x01};

     GdkCursor *cursor;
     GdkPixmap *source, *mask;
     GdkColor fg = { 0, 65535, 0, 0 }; /* Red. */
     GdkColor bg = { 0, 0, 0, 65535 }; /* Blue. */

     source = gdk_bitmap_create_from_data (NULL, cursor1_bits,
                                           cursor1_width, cursor1_height);
     mask = gdk_bitmap_create_from_data (NULL, cursor1mask_bits,
                                         cursor1_width, cursor1_height);
     cursor = gdk_cursor_new_from_pixmap (source, mask, &fg, &bg, 8, 8);
     gdk_pixmap_unref (source);
     gdk_pixmap_unref (mask);

     gdk_window_set_cursor (widget->window, cursor);

`source` : | the pixmap specifying the cursor.
`mask` : | the pixmap specifying the mask, which must be the same size as `source`.
`fg` : | the foreground color, used for the bits in the source which are 1. The color does not have to be allocated first.
`bg` : | the background color, used for the bits in the source which are 0. The color does not have to be allocated first.
`x` : | the horizontal offset of the 'hotspot' of the cursor.
`y` : | the vertical offset of the 'hotspot' of the cursor.
Returns : | a new GdkCursor.

### gdk_cursor_new_from_pixbuf ()

    GdkCursor*  gdk_cursor_new_from_pixbuf      (GdkDisplay *display,
                                                 GdkPixbuf *pixbuf,
                                                 gint x,
                                                 gint y);

Creates a new cursor from a pixbuf.

Not all GDK backends support RGBA cursors. If they are not supported, a monochrome approximation will be displayed. The functions `gdk_display_supports_cursor_alpha()` and `gdk_display_supports_cursor_color()` can be used to determine whether RGBA cursors are supported; `gdk_display_get_default_cursor_size()` and `gdk_display_get_maximal_cursor_size()` give information about cursor sizes.

On the X backend, support for RGBA cursors requires a sufficently new version of the X Render extension.

`display` : | the GdkDisplay for which the cursor will be created
`pixbuf` : | the GdkPixbuf containing the cursor image
`x` : | the horizontal offset of the 'hotspot' of the cursor.
`y` : | the vertical offset of the 'hotspot' of the cursor.
Returns : | a new GdkCursor.

Since 2.4

### gdk_cursor_new_for_display ()

    GdkCursor*  gdk_cursor_new_for_display      (GdkDisplay *display,
                                                 GdkCursorType cursor_type);

Creates a new cursor from the set of builtin cursors. Some useful ones are:

- GDK_RIGHT_PTR (right-facing arrow)

- GDK_CROSSHAIR (crosshair)

- GDK_XTERM (I-beam)

- GDK_WATCH (busy)

- GDK_FLEUR (for moving objects)

- GDK_HAND1 (a right-pointing hand)

- GDK_HAND2 (a left-pointing hand)

- GDK_LEFT_SIDE (resize left side)

- GDK_RIGHT_SIDE (resize right side)

- GDK_TOP_LEFT_CORNER (resize northwest corner)

- GDK_TOP_RIGHT_CORNER (resize northeast corner)

- GDK_BOTTOM_LEFT_CORNER (resize southwest corner)

- GDK_BOTTOM_RIGHT_CORNER (resize southeast corner)

- GDK_TOP_SIDE (resize top side)

- GDK_BOTTOM_SIDE (resize bottom side)

- GDK_SB_H_DOUBLE_ARROW (move vertical splitter)

- GDK_SB_V_DOUBLE_ARROW (move horizontal splitter)

To make the cursor invisible, use `gdk_cursor_new_from_pixmap()` to create a cursor with no pixels in it.

`display` : | the GdkDisplay for which the cursor will be created
`cursor_type` : | cursor to create
Returns : | a new GdkCursor

Since 2.2

### gdk_cursor_get_display ()

    GdkDisplay* gdk_cursor_get_display          (GdkCursor *cursor);

Returns the display on which the GdkCursor is defined.

`cursor` : | a GdkCursor.
Returns : | the GdkDisplay associated to `cursor`

Since 2.2

### gdk_cursor_ref ()

    GdkCursor*  gdk_cursor_ref                  (GdkCursor *cursor);

Adds a reference to `cursor`.

`cursor` : | a GdkCursor
Returns : | Same `cursor` that was passed in

### gdk_cursor_unref ()

    void        gdk_cursor_unref                (GdkCursor *cursor);

Removes a reference from `cursor`, deallocating the cursor if no references remain.

`cursor` : | a GdkCursor

### gdk_cursor_destroy

    #define gdk_cursor_destroy             gdk_cursor_unref

### Warning

`gdk_cursor_destroy` is deprecated and should not be used in newly-written code.

Destroys a cursor, freeing any resources allocated for it.