![[Burning Cog]](../../../../icons/pyromaniac.png){kind=icon}
Introduction and overview
Pointer devices (usually mice) have been extended to provide additional functionality found in more modern devices such as additional buttons and an alternate positioning device (usually provided as a single or dual 'scroll wheel'). Similarly, devices which provide absolute positioning such as tablets and touchscreens are now capable of being serviced by the pointer system. In order to provide these extra functions, a revised form of the PointerV interface has been used.
This builds upon the interface declared in PRM 5a, but moves some functions away from the driver.
The OSPointer module controls pointer movement and will handle these extended functions. Previously the Kernel provided management of the pointer. These functions are now provided entirely by the OSPointer module.
The operation is split into two major parts:
- How drivers provide information to the OSPointer module about the new features
- How programmers access this information
In addition, a separate document details the operation of the WindowScroll module which provides functionality for desktop tasks.
Technical details
PointerV
PointerV has been extended with a new reason codes - PointerV 4 - in RISC OS Select to support the use of alternative pointing device values. Specifically this allows for the scroll wheel provided by modern mice, and for tablet or touch screen devices.
Driver updates in RISC OS Select
Quadrature mouse driver
The quadrature mouse driver ('Mouse' module) has been updated to provide an additional device type for Stuart Tyrrell's PS2 mouse interface. This interface functions in 'driver' mode to provide alternate device support for single axis devices (primarily vertical scroll wheels).
Dual axis movement is presently not supported.
PS 2 mouse driver
The PS 2 mouse driver ('PS2Driver' module) has been updated to provide support for 'Intellimouse' and 'Intellimouse Pro' devices. These are more commonly known as 'scroll mice' or '5 button mice' respectively.
Dual axis movement is presently not supported.
Touch screen or tablet drivers
No touch screen or tablet driver is supplied with the current version of RISC OS. Developers wishing to implement such a driver should contact their supplier.
OSPointer handling of extended requests
The OSPointer module will issue the Extended request for versions of the OS which support these new features (RISC OS 4.32 and later). If the call returns unclaimed (R0 having not been set to -1 or 5), the module will issue PointerV 1 (Request) and defer button handling to the driver.
If the call is claimed, the OSPointer module will issue KeyV events for the buttons which have been pressed and apply the change or absolute position to the pointer.
The absolute positioning interface is available from version 0.25 of the OSPointer module.
Additional buttons
In addition to the base 3 buttons up to 8 buttons are supported by the OSPointer module. 5 button mice are common and the PS 2 driver has been updated to support such devices.
The additional buttons are reported through the extended KeyV interface for mouse buttons. These buttons are detected by the OSPointer module and returned as useful values through the standard interfaces.
Programmers interface
In order obtain position details for the alternate scrolling device, a new reason has been added, SWI OS_Pointer 2.
SWI calls
| R0 | = | X position of the pointer | ||||||||||||||||||||||||||||||
| R1 | = | Y position of the pointer | ||||||||||||||||||||||||||||||
| R2 | = | mouse buttons:
| ||||||||||||||||||||||||||||||
| R3 | = | time of button chan | ||||||||||||||||||||||||||||||
This SWI returns the pointer position from the mouse buffer if events are buffered or the current position if the buffer is empty. It has been extended from the interface described in PRM 1-699 by adding additional buttons.
| R0 | = | 2 (reason code) |
| R1 | = | Register details |
| R0 | = | signed 32bit X position of the alternate device |
| R1 | = | signed 32bit Y position of the alternate device |
This SWI returns the position of the alternate positioning device. The device position is unbounded and thus may wrap when the limits of the 32bit representation are reached. Should the device position wrap past a limit, it will be reset to zero. Thus, should the position exceed either &7FFFFFFF or -&80000000 it will be reset. Clients should be aware of this and handle such conditions appropriately.
Software vectors
| R0 | = | reason code (21) |
| R1 | = | subreason code (4) |
| R2 | = | signed 32bit change in X position |
| R3 | = | signed 32bit change in Y position |
This event is generated by the OSPointer module when a scroll event is triggered by the user. Clients which track mouse movements should monitor this event. This allows clients to monitor either changes or the absolute position should they wish to do so. If clients wish to cause the scroll event to be ignored they should claim the event.
| R0 | = | reason code (4) |
| R1 | = | pointer type |
| R0 | = | Request state:
| ||||||||||||||||||
| R1 | preserved | |||||||||||||||||||
| R2 | = | relative device: signed 32 bit change in X position absolute device: fractional 16 bit X position | ||||||||||||||||||
| R3 | = | relative device: signed 32 bit change in Y position absolute device: fractional 16 bit Y position | ||||||||||||||||||
| R4 | = | relative device: signed 32 bit change in X position of alternate device absolute device: must be 0 | ||||||||||||||||||
| R5 | = | relative device: signed 32 bit change in Y position of alternate device absolute device: must be 0 | ||||||||||||||||||
| R6 | = | Mouse buttons:
| ||||||||||||||||||
This vector reason is called by the OSPointer module to determine the position of the pointing device in a similar manner to that of PointerV 1 (Request). Drivers should check the pointer type and if it matches the device being provided details should be returned and the vector claimed. If the pointer type does not match the vector should be passed on.
Unlike PointerV 1 (Request), drivers should not issue KeyV requests for the mouse buttons that they provide. This task will be performed by the OSPointer module based on the button state returned. Drivers wishing to support both the old and new protocol may share code between PointerV 1 (Request) and PointerV 2 (Result) but they must ensure that registers are not corrupted unduly and that the different mouse button processing is performed based on the request type.
Relative devices and absolute devices respond to the same request but provide slightly different responses. The value returned in R0 is used to determine the type of response made.
Absolute devices return a 16 bit value (0-65535) which determines the position of the event. The driver may determine how the event is to be processed and indicate an equivalent button state for the event. This allows devices to provide positioning within the absolute device as distinct from button click events. For absolute devices the meaning of R4 and R5 is undefined and the registers must be returned as 0 for future compatibility. Internally, the absolute position request is scaled by the screen size and converted into a relative position which is applied to the mouse position with an equivalent of a mouse step of 1.
For scroll wheel-like alternate devices the +ve Y direction should be that for pushing the wheel 'away' from the user.