Input: 2.4 Mouse Input: Setting the Pointer Image

The GEOS User Interface uses several default settings for the mouse pointer, all defined by the Specific UI.

Some applications will want to modify the mouse pointer's image in order to provide certain feedback to the user. For example, a chess game may set the pointer to an image of the piece being moved and then reset it to an arrow after the move is completed; a graphics application could set the pointer to an image of whatever tool is currently in use. Another time an application may change the mouse pointer is when a quick-transfer is in progress.

Defining the Pointer Image

The pointer is defined as a bitmap 16 pixels on each side. It has a "hot spot" of five pixels that acts as the active point of the image. When the user clicks, the area affected is the hot spot, not the entire image.

The pointer is stored in a PointerDef16 structure. This structure defines the image bitmap, the horizontal and vertical offsets to the hot spot, and the definition of how the image should mix with the background. This definition is known as the pointer's mask.

The definition of PointerDef16 is given below. When setting the pointer image, you will typically pass an optr (a combination handle and chunk handle) to a PointerDef16 structure; the structure can be set up in a sharable chunk beforehand, or it can be set in a local or global variable. Typically, you will set the entire pointer image in a resource chunk and compile it into your geode; this is much easier and faster to use than building it at run-time.

typedef struct {
	byte	   PD_width;
	byte	   PD_height;
	sbyte	   PD_hotX;
	sbyte	   PD_hotY;
	byte	   PD_mask[STANDARD_CURSOR_IMAGE_SIZE];
	byte	   PD_image[STANDARD_CURSOR_IMAGE_SIZE];
} PointerDef16;

The PD_hotX field defines the horizontal offset from the upper-left corner of the image to the center of the hot spot. Similarly, PD_hotY defines the vertical offset from the upper-left corner to the hot spot. Both are in pixels and must be less than 16 (since the image is only 16 pixels in each dimension).

The PD_mask field contains the 16 by 16 bitmap of the mask, while PD_image holds the bitmap of the image. Both are stored as 32-byte arrays, two bytes per row. For example, if the first line of the image was all black and the second all white, the first four bytes of PD_image would be 0xFF, 0xFF, 0x00, and 0x00.

Note that the block the pointer chunk is stored in must be declared sharable.

Setting the Pointer Image

You can set the pointer's image in three ways. First, you can send a message to the GenView to set the pointer image whenever the pointer is over the view's window (see the GenView chapter). Second, you can set the pointer to a default image type during a quick-transfer operation (see the Clipboard chapter). Third, you can set the pointer image after handling a mouse event. Only the third option is discussed here.

An object may wish to set the pointer image while it is selected, while the pointer is over its bounds, or in any number of other situations. For example, a chess piece currently being moved may set the pointer's image to the shape of the piece so the user knows exactly what type of piece is being moved.

Every mouse event you handle must return a MouseReturnParams structure, defined in Return Values for Mouse Events . Make sure to return the following to set the pointer image:

MRF_SET_POINTER_IMAGE in flags When the UI sees this flag in the returned structure, it looks for the address of a pointer definition in the ptrImage field. If you do not return this flag, the UI will not try to set the pointer.
The optr of the pointer image in ptrImage This field gives the handle and chunk handle of the PointerDef structure that defines the pointer image to be set. The structure must be in a sharable block; most likely you will have it set in a geode resource.

GEOS SDK TechDocs |

2.3 Large Mouse Events | Next:

3 Keyboard Input