Cursors

OBJECTS

  typedef struct Cursor  Cursor;

  struct Cursor {
	App *  app;                     /* associated App */
	void * extra;                   /* platform-specific data */
  };

FUNCTIONS

  Cursor *new_cursor(App *app, Image *img, Point hotspot);
  Cursor *get_standard_cursor(App *app, int shape);
  void    del_cursor(Cursor *c);
  void    find_best_cursor_size(App *app, int *width, int *height,
                                    int *depth);
  void    set_window_cursor(Window *win, Cursor *c);
  Point   get_cursor_position(App *app);
  void    set_cursor_position(App *app, Point p);

CONSTANTS

  enum StandardCursors {
	BLANK_CURSOR,
	ARROW_CURSOR,
	WAIT_CURSOR,
	CARET_CURSOR,
	CROSS_CURSOR,
	HAND_CURSOR,
	GRAB_CURSOR,
	POINTING_CURSOR,
	PENCIL_CURSOR,
	LASSO_CURSOR,
	DROPPER_CURSOR,
	MAGNIFY_CURSOR,
	MAGPLUS_CURSOR,
	MAGMINUS_CURSOR,
	TEXT_CURSOR      = CARET_CURSOR
  };

NOTES

A Cursor represents a mouse pointer on the screen.

New cursors can be created using the new_cursor function. The hotspot point is where the 'tip' of the mouse pointer should be, and the image defines the shape of the cursor. The image can have transparent regions, and is allowed to use BLACK, WHITE and CLEAR colours, and can be at least 16 by 16 pixels in size. Other colours and larger cursors sizes may be possible, depending on the window manager.

A number of standard cursors can be obtained using the get_standard_cursor function and supplying one of the constants:

• The BLANK_CURSOR produces an invisible cursor.
• The ARROW_CURSOR is the normal mouse pointer.
• The WAIT_CURSOR indicates the user must wait for a short time, for example when loading a large file.
• The CARET_CURSOR is used when typing text, and is the same as the TEXT_CURSOR.
• The CROSS_CURSOR is used when dragging a rectangular region.
• The HAND_CURSOR and GRAB_CURSOR can be used when dragging a page around.
• The POINTING_CURSOR can be used when selecting an item from a list, or clicking on a hyperlink.
• The PENCIL_CURSOR, LASSO_CURSOR and DROPPER_CURSOR can be used during interactive drawing operations, to draw dots or freehand lines, to select a freehand region, or to select a colour from an image, respectively.
• The MAGNIFY_CURSOR can be used when increasing or decreasing the magnification of a document. The MAGPLUS_CURSOR includes a '+' within the magnifying glass shape, indicating increasing magnification, while the MAGMINUS_CURSOR includes a '-' and indicates decreasing magnification.

The memory used by a cursor can be reclaimed by calling del_cursor. Normally this is not necessary, since all used cursors are released when the App is deleted.

The find_best_cursor_size function asks the window manager what other colours and sizes can be used by a cursor. Pointers to integers are passed, and filled with appropriate values. The width and height will be the maximum size of a cursor. Often these will be 32 or 64, although a cursor might only look good at a width and height of 16, so beware of using all the available space. The depth may be 1, indicating BLACK and WHITE and CLEAR are the only colours to be used, or it may be 32, indicating the cursor may use any colours. The window manager may or may not allow alpha-blending effects to produce shadows around the cursor.

To change a window's cursor, use set_window_cursor. This sets the cursor for the entire window. It is valid to call this repeatedly within mouse event handlers.

The get_cursor_position returns the current location of the mouse cursor's hotspot in screen co-ordinates. To move the cursor to another location on the screen, use set_cursor_position and pass the new position in screen co-ordinates.