Unit Mouse
From Ultibo.org
Return to Unit Reference
Description
Ultibo Mouse interface unit
This unit provides both the Mouse device interface and the generic USB HID mouse driver.
Constants
Mouse specific constants
MOUSE_* MOUSE_NAME_PREFIX = 'Mouse';
|
Name prefix for Mouse Devices |
Mouse device type constants
MOUSE_TYPE_* MOUSE_TYPE_NONE = 0;
|
|
MOUSE_TYPE_USB = 1;
|
|
MOUSE_TYPE_PS2 = 2;
|
|
MOUSE_TYPE_SERIAL = 3;
|
|
MOUSE_TYPE_MAX = 3;
|
|
Mouse device state constants
MOUSE_STATE_* MOUSE_STATE_DETACHED = 0;
|
|
MOUSE_STATE_DETACHING = 1;
|
|
MOUSE_STATE_ATTACHING = 2;
|
|
MOUSE_STATE_ATTACHED = 3;
|
|
MOUSE_STATE_MAX = 3;
|
|
Mouse device flag constants
MOUSE_FLAG_* MOUSE_FLAG_NONE = $00000000;
|
|
MOUSE_FLAG_NON_BLOCK = $00000001;
|
If set device reads are non blocking (Also supported in Flags parameter of MouseReadEx) |
MOUSE_FLAG_DIRECT_READ = $00000002;
|
If set device writes mouse data to its local buffer and which must be read using MouseDeviceRead |
MOUSE_FLAG_SWAP_BUTTONS = $00000004;
|
If set left and right mouse buttons will be swapped in mouse data |
MOUSE_FLAG_PEEK_BUFFER = $00000008;
|
Peek at the buffer to see if any data is available, don't remove it. (Used only in Flags parameter of MouseReadEx) |
| Flags supported by MOUSE_CONTROL_GET/SET/CLEAR_FLAG | |
MOUSE_FLAG_MASK = MOUSE_FLAG_NON_BLOCK or MOUSE_FLAG_DIRECT_READ or MOUSE_FLAG_SWAP_BUTTONS;
|
|
Mouse device control code constants
MOUSE_CONTROL_* MOUSE_CONTROL_GET_FLAG = 1;
|
Get Flag |
MOUSE_CONTROL_SET_FLAG = 2;
|
Set Flag |
MOUSE_CONTROL_CLEAR_FLAG = 3;
|
Clear Flag |
MOUSE_CONTROL_FLUSH_BUFFER = 4;
|
Flush Buffer |
Mouse buffer size constants
MOUSE_BUFFER_* MOUSE_BUFFER_SIZE = 512;
|
Mouse data definition constants
MOUSE_LEFT_*, MOUSE_RIGHT_* | Values for TMouseData.Buttons | |
MOUSE_LEFT_BUTTON = $0001;
|
The Left mouse button is pressed |
MOUSE_RIGHT_BUTTON = $0002;
|
The Right mouse button is pressed |
MOUSE_MIDDLE_BUTTON = $0004;
|
The Middle mouse button is pressed |
MOUSE_SIDE_BUTTON = $0008;
|
The Side mouse button is pressed |
MOUSE_EXTRA_BUTTON = $0010;
|
The Extra mouse button is pressed |
MOUSE_TOUCH_BUTTON = $0020;
|
The Touch screen is being touched |
MOUSE_ABSOLUTE_X = $0040;
|
The OffsetX value is absolute not relative |
MOUSE_ABSOLUTE_Y = $0080;
|
The OffsetY value is absolute not relative |
MOUSE_ABSOLUTE_WHEEL = $0100;
|
The OffsetWheel value is absolute not relative |
Mouse logging constants
MOUSE_LOG_* MOUSE_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;
|
Mouse debugging messages |
MOUSE_LOG_LEVEL_INFO = LOG_LEVEL_INFO;
|
Mouse informational messages, such as a device being attached or detached |
MOUSE_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;
|
Mouse error messages |
MOUSE_LOG_LEVEL_NONE = LOG_LEVEL_NONE;
|
No Mouse messages |
USB mouse specific constants
USBMOUSE_* USBMOUSE_DRIVER_NAME = 'USB Mouse Driver (HID boot protocol)';
|
Name of USB mouse driver |
USBMOUSE_MOUSE_DESCRIPTION = 'USB HID Mouse';
|
Description of USB mouse device |
| HID Interface Subclass types (See USB HID v1.11 specification) | |
USB_HID_SUBCLASS_BOOT = 1;
|
Section 4.2 |
| HID Interface Protocol types (See USB HID v1.11 specification) | |
USB_HID_BOOT_PROTOCOL_KEYBOARD = 1;
|
Section 4.3 |
USB_HID_BOOT_PROTOCOL_MOUSE = 2;
|
Section 4.3 |
| HID Request types | |
USB_HID_REQUEST_GET_REPORT = $01;
|
|
USB_HID_REQUEST_GET_IDLE = $02;
|
|
USB_HID_REQUEST_GET_PROTOCOL = $03;
|
Section 7.2 |
USB_HID_REQUEST_SET_REPORT = $09;
|
|
USB_HID_REQUEST_SET_IDLE = $0A;
|
|
USB_HID_REQUEST_SET_PROTOCOL = $0B;
|
Section 7.2 |
| HID Protocol types | |
USB_HID_PROTOCOL_BOOT = 0;
|
Section 7.2.5 |
USB_HID_PROTOCOL_REPORT = 1;
|
Section 7.2.5 |
| HID Report types | |
USB_HID_REPORT_INPUT = 1;
|
Section 7.2.1 |
USB_HID_REPORT_OUTPUT = 2;
|
Section 7.2.1 |
USB_HID_REPORT_FEATURE = 3;
|
Section 7.2.1 |
| HID Report IDs | |
USB_HID_REPORTID_NONE = 0;
|
Section 7.2.1 |
| HID Boot Protocol Button bits | |
USB_HID_BOOT_LEFT_BUTTON = (1 shl 0);
|
|
USB_HID_BOOT_RIGHT_BUTTON = (1 shl 1);
|
|
USB_HID_BOOT_MIDDLE_BUTTON = (1 shl 2);
|
|
USB_HID_BOOT_SIDE_BUTTON = (1 shl 3);
|
|
USB_HID_BOOT_EXTRA_BUTTON = (1 shl 4);
|
|
| HID Boot Protocol Report data | |
USB_HID_BOOT_REPORT_SIZE = 3;
|
Appendix B of HID Device Class Definition 1.11 |
USB_HID_BOOT_DATA_SIZE = 8;
|
Allocate more than the minimum to allow for extra data |
Type definitions
To be documented
Public variables
Mouse logging
MOUSE_DEFAULT_LOG_LEVEL:LongWord = MOUSE_LOG_LEVEL_DEBUG;
|
Minimum level for Mouse messages. Only messages with level greater than or equal to this will be printed. |
MOUSE_LOG_ENABLED:Boolean;
|
Function declarations
Initialization functions
procedure MouseInit;
Description: Initialize the mouse unit, device table and USB mouse driver
| Note | Called only during system startup |
|---|
Mouse functions
function MousePeek:LongWord;
Description: Peek at the global mouse buffer to see if any data packets are ready
| Return | ERROR_SUCCESS if packets are ready, ERROR_NO_MORE_ITEMS if not or another error code on failure |
|---|
function MouseRead(Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Read mouse data packets from the global mouse buffer
| Buffer | Pointer to a buffer to copy the mouse data packets to |
|---|---|
| Size | The size of the buffer in bytes (Must be at least TMouseData or greater) |
| Count | The number of mouse data packets copied to the buffer |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MouseReadEx(Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: Read mouse data packets from the global mouse buffer
| Buffer | Pointer to a buffer to copy the mouse data packets to |
|---|---|
| Size | The size of the buffer in bytes (Must be at least TMouseData or greater) |
| Flags | The flags for the behaviour of the read (eg MOUSE_FLAG_NON_BLOCK) |
| Count | The number of mouse data packets copied to the buffer |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MouseWrite(Buffer:Pointer; Size,Count:LongWord):LongWord;
Description: Write mouse data packets to the global mouse buffer
| Buffer | Pointer to a buffer to copy the mouse data packets from |
|---|---|
| Size | The size of the buffer in bytes (Must be at least TMouseData or greater) |
| Count | The number of mouse data packets to copy from the buffer |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MouseFlush:LongWord;
Description: Flush the contents of the global mouse buffer
| Return | ERROR_SUCCESS if completed or another error code on failure |
|---|
function MouseDeviceRead(Mouse:PMouseDevice; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Read mouse data packets from the buffer of the specified mouse
| Mouse | The mouse device to read from |
|---|---|
| Buffer | Pointer to a buffer to copy the mouse data packets to |
| Size | The size of the buffer in bytes (Must be at least TMouseData or greater) |
| Count | The number of mouse data packets copied to the buffer |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MouseDeviceControl(Mouse:PMouseDevice; Request:Integer; Argument1:LongWord; var Argument2:LongWord):LongWord;
Description: Perform a control request on the specified mouse device
| Mouse | The mouse device to control |
|---|---|
| Request | The request code for the operation (eg MOUSE_CONTROL_GET_FLAG) |
| Argument1 | The first argument for the operation (Dependent on request code) |
| Argument2 | The second argument for the operation (Dependent on request code) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MouseDeviceSetState(Mouse:PMouseDevice; State:LongWord):LongWord;
Description: Set the state of the specified mouse and send a notification
| Mouse | The mouse to set the state for |
|---|---|
| State | The new state to set and notify |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MouseDeviceCreate:PMouseDevice;
Description: Create a new Mouse device entry
| Return | Pointer to new Mouse device entry or nil if mouse could not be created |
|---|
function MouseDeviceCreateEx(Size:LongWord):PMouseDevice;
Description: Create a new Mouse device entry
| Size | Size in bytes to allocate for new mouse (Including the mouse device entry) |
|---|---|
| Return | Pointer to new Mouse device entry or nil if mouse could not be created |
function MouseDeviceDestroy(Mouse:PMouseDevice):LongWord;
Description: Destroy an existing Mouse device entry
| Mouse | The mouse device to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MouseDeviceRegister(Mouse:PMouseDevice):LongWord;
Description: Register a new Mouse device in the Mouse table
| Mouse | The mouse device to register |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MouseDeviceDeregister(Mouse:PMouseDevice):LongWord;
Description: Deregister a Mouse device from the Mouse table
| Mouse | The mouse device to deregister |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MouseDeviceFind(MouseId:LongWord):PMouseDevice;
Description: Find a mouse device by ID in the mouse table
| MouseId | The ID number of the mouse to find |
|---|---|
| Return | Pointer to mouse device entry or nil if not found |
function MouseDeviceFindByName(const Name:String):PMouseDevice; inline;
Description: Find a mouse device by name in the mouse table
| Name | The name of the mouse to find (eg Mouse0) |
|---|---|
| Return | Pointer to mouse device entry or nil if not found |
function MouseDeviceFindByDescription(const Description:String):PMouseDevice; inline;
Description: Find a mouse device by description in the mouse table
| Description | The description of the mouse to find (eg USB HID Mouse) |
|---|---|
| Return | Pointer to mouse device entry or nil if not found |
function MouseDeviceEnumerate(Callback:TMouseEnumerate; Data:Pointer):LongWord;
Description: Enumerate all mouse devices in the mouse table
| Callback | The callback function to call for each mouse in the table |
|---|---|
| Data | A private data pointer to pass to callback for each mouse in the table |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MouseDeviceNotification(Mouse:PMouseDevice; Callback:TMouseNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: Register a notification for mouse device changes
| Mouse | The mouse device to notify changes for (Optional, pass nil for all mice) |
|---|---|
| Callback | The function to call when a notification event occurs |
| Data | A private data pointer to pass to callback when a notification event occurs |
| Notification | The events to register for notification of (eg DEVICE_NOTIFICATION_REGISTER) |
| Flags | The flags to control the notification (eg NOTIFIER_FLAG_WORKER) |
RTL console functions
function SysConsoleHideMouse(AUserData:Pointer):Boolean;
Description: Handler for Platform ConsoleHideMouse function
| Note | None documented |
|---|
function SysConsoleShowMouse(X,Y:LongWord; AUserData:Pointer):Boolean;
Description: Handler for Platform ConsoleShowMouse function
| Note | None documented |
|---|
function SysConsoleReadMouse(var X,Y,Buttons:LongWord; AUserData:Pointer):Boolean;
Description: Handler for Platform ConsoleReadMouse function
| Note | None documented |
|---|
USB mouse functions
function USBMouseDeviceRead(Mouse:PMouseDevice; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Implementation of MouseDeviceRead API for USB Mouse
| Note | None documented |
|---|
function USBMouseDeviceControl(Mouse:PMouseDevice; Request:Integer; Argument1:LongWord; var Argument2:LongWord):LongWord;
Description: Implementation of MouseDeviceControl API for USB Mouse
| Note | None documented |
|---|
function USBMouseDriverBind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Bind the Mouse driver to a USB device if it is suitable
| Device | The USB device to attempt to bind to |
|---|---|
| Interface | The USB interface to attempt to bind to (or nil for whole device) |
| Return | USB_STATUS_SUCCESS if completed, USB_STATUS_DEVICE_UNSUPPORTED if unsupported or another error code on failure |
function USBMouseDriverUnbind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Unbind the Mouse driver from a USB device
| Device | The USB device to unbind from |
|---|---|
| Interface | The USB interface to unbind from (or nil for whole device) |
| Return | USB_STATUS_SUCCESS if completed or another error code on failure |
procedure USBMouseReportWorker(Request:PUSBRequest);
Description: Called (by a Worker thread) to process a completed USB request from a USB mouse IN interrupt endpoint
| Request | The USB request which has completed |
|---|
procedure USBMouseReportComplete(Request:PUSBRequest);
Description: Called when a USB request from a USB mouse IN interrupt endpoint completes
| Request | The USB request which has completed |
|---|---|
| Note | Request is passed to worker thread for processing to prevent blocking the USB completion |
Mouse helper functions
function MouseGetCount:LongWord; inline;
Description: Get the current mouse count
| Note | None documented |
|---|
function MouseDeviceCheck(Mouse:PMouseDevice):PMouseDevice;
Description: Check if the supplied Mouse is in the mouse table
| Note | None documented |
|---|
function MouseDeviceTypeToString(MouseType:LongWord):String;
Description: To be documented
| Note | None documented |
|---|
function MouseDeviceStateToString(MouseState:LongWord):String;
Description: To be documented
| Note | None documented |
|---|
function MouseDeviceStateToNotification(State:LongWord):LongWord;
Description: Convert a Mouse state value into the notification code for device notifications
| Note | None documented |
|---|
procedure MouseLog(Level:LongWord; Mouse:PMouseDevice; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure MouseLogInfo(Mouse:PMouseDevice; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure MouseLogError(Mouse:PMouseDevice; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure MouseLogDebug(Mouse:PMouseDevice; const AText:String);
Description: To be documented
| Note | None documented |
|---|
USB mouse helper functions
function USBMouseDeviceSetProtocol(Mouse:PUSBMouseDevice; Protocol:Byte):LongWord;
Description: Set the report protocol for a USB mouse device
| Mouse | The USB mouse device to set the report protocol for |
|---|---|
| Protocol | The report protocol to set (eg USB_HID_PROTOCOL_BOOT) |
| Return | USB_STATUS_SUCCESS if completed or another USB error code on failure |
Return to Unit Reference
