Wimp.Pointer

New Calls

        *Pointer
        Wimp_SetPointerShape
        Wimp_SpriteOp (36 = SetPointerShape)
        how to behave properly

*Pointer

        Syntax:  *Pointer [0 | 1]

*Pointer or *Pointer 1 turns the pointer on, while *Pointer 0 turns it off.

The *Pointer command has been changed so that it sets up the default pointer shape in mouse pointer 1 from a sprite called "ptr_default" in the Wimp's common sprite pool (see Wimp.Sprites).

The default pointer sprite does not contain a palette - instead, *Pointer sets the pointer palette from the current setting of the Wimp palette (see Wimp.Colours).

Applications wishing to alter the pointer shape while the pointer is inside their window should use pointer shape 2, and should reset the pointer using the *Pointer command when the pointer leaves the window.

Pointer shapes 3 and 4 are reserved for use by such programs as the Hourglass module, which modifies the pointer shape under interrupt.

Wimp_SetPointerShape

Entry: R0 = pointer shape number (0 to turn it off)
R1 -> shape data (2 bits per pixel, rows from top to bottom)
R2 = width (pixels)
R3 = height (pixels)

        R4,R5 = offset of active point from top-left

The use of this call is now discouraged, as there is a better one:

Wimp_SpriteOp, R0 = 36 (SetPointerShape)

Entry: R0 = 36
R2 -> sprite name (of the form "ptr_xxx")
R3 bits 0..3 = pointer shape number
R3 bit 4 set => don't set up the shape data
R3 bit 5 set => don't set up the palette
R3 bit 6 set => don't set up the pointer shape number
R4,R5 = coordinates of active point from top-left
R6 -> scale factors (as for PutSpriteScaled)

        R7 -> translation table  (as for PutSpriteScaled)

        (see also documentation for SpriteExtension module).

If R3 bit 5 is unset, but the sprite has no palette entries, the Wimp will set up the default pointer palette (ie. the one that the Palette utility can alter).

The convention for pointer shapes is that there should be a well-known 'family' of them in the Wimp's common sprite area, and applications should use these if possible. In this way many applications can share data, and it also makes it easier for the user to change the pointer shapes if he so desires. Another advantage is that the various pointer shapes are more likely to coordinate with each other.

The default pointer shapes all have names starting with "ptr_": the list so far is as follows:

        ptr_default             default pointer shape

Note that if for some reason it is not desirable to use a pointer shape from the Wimp's common sprite pool, it is possible to call OS_SpriteOp directly to use any arbitrary sprite as a pointer shape.

How to behave properly

The recommended way for applications to change the pointer shape is for them to trap Pointer_Entering_Window and Pointer_Leaving_Window events from Wimp_Poll, setting up pointer shape 2 when the pointer enters their window, and restoring to pointer shape 1 when the pointer leaves the window (NB: the recommended way to do this is by *Pointer, since that resets the mouse palette as well).

There are some pitfalls, however:

The application must keep a flag saying whether the pointer is currently inside its window, so that if it wants to change the pointer shape due to some internal state change, it should only do so if it currently 'owns' the pointer. The classic case of this is when the user right-clicks in a menu on the window, causing the application to change what it wants the pointer shape to be. Unfortunately if the menus are re-opened immediately, the pointer should remain in its default state, since it never enters the application window.
When the user alters the screen mode (ie. Wimp_SetMode is called), the pointer shape is set back to the default. However, no Pointer_Entering or Pointer_Leaving events are generated, so the application must explicitly reset the correct pointer shape when it gets the Message_ModeChange message, if it thinks that it currently owns the pointer (see above).

The latter case is currently difficult to elicit, since the only way for the user to change mode is via the palette utility's menu. However, if someone were to invent a 'hot key' that called Wimp_SetMode, the pointer could be anywhere at the time, so applications should be written to cope with it.