> 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 Wimp.SprExtend).

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.