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 :
In addition, a separate document details the operation of the WindowScroll module which provides functionality for desktop tasks.
R0 = 4 (Extended request) R1 = pointer type
R0 = -1 to indicate that the request was claimed by a relative positioning device (eg mouse, trackerball) 5 (Absolute response) to indicate that the request was claimed by an absolute positioning device (eg touchscreen, tablet) 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 : bit 0 = Right button bit 1 = Middle button bit 2 = Left button bits 3-7 = May be provided at the discretion of driver bitd 8-31 = Must be 0
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 corrupt 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.
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 above 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 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.
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.
In order obtain position details for the alternate scrolling device, a new reason has been added to OS_Pointer.
OS_Pointer 2 (SWI &64)
R0 = 2 (read alternate position)
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.
OS_Mouse (SWI &1C)
R0 = X position of pointer R1 = Y position of pointer R2 = mouse buttons : bit 0 = right button bit 1 = middle button bit 2 = left button bit 3 = fourth button bit 4 = fifth button bit 5 = sixth button bit 6 = seventh button bit 7 = eigth button Others reserved R3 = time of button change
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.
EventV 21, 4
R0 = 21 (Expansion event) R1 = 4 (Pointer scroll event) 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.
Thanks to Stuart Tyrrell and Theo Markettos for their feedback and support.
This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.
HTML document version 1.03 3rd November 2015