Difference between revisions of "Unit Touch"
From Ultibo.org
| Line 683: | Line 683: | ||
<br /> | <br /> | ||
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
| − | <pre style="border: 0; padding-bottom:0px;">function TouchDeviceControl(Touch:PTouchDevice; Request:Integer; Argument1: | + | <pre style="border: 0; padding-bottom:0px;">function TouchDeviceControl(Touch:PTouchDevice; Request:Integer; Argument1:PtrUInt; var Argument2:PtrUInt):LongWord;</pre> |
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Perform a control request on the specified touch device</div> | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Perform a control request on the specified touch device</div> | ||
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
| Line 1,008: | Line 1,008: | ||
! Note | ! Note | ||
| Also accepts passing the touch rotation constant values directly | | Also accepts passing the touch rotation constant values directly | ||
| + | |- | ||
| + | |} | ||
| + | </div></div> | ||
| + | <br /> | ||
| + | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
| + | <pre style="border: 0; padding-bottom:0px;">function TouchDeviceSetCallback(Touch:PTouchDevice; Event:TTouchEvent; Parameter:Pointer):LongWord;</pre> | ||
| + | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the event callback function for the specified touch device</div> | ||
| + | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
| + | {| class="wikitable" style="font-size: 14px; background: white;" | ||
| + | |- | ||
| + | ! Touch | ||
| + | | The touch device to set the event callback for | ||
| + | |- | ||
| + | ! Event | ||
| + | | The event callback function to be called when touch data is received | ||
| + | |- | ||
| + | ! Parameter | ||
| + | | A pointer to private data to be passed to the callback with each event | ||
| + | |- | ||
| + | ! Return | ||
| + | | ERROR_SUCCESS if completed or another error code on failure | ||
| + | |- | ||
| + | ! Note | ||
| + | | This function also clears the TOUCH_FLAG_MOUSE_DATA flag because the event callback is not compatible with receiving touch events as mouse data | ||
|- | |- | ||
|} | |} | ||
Revision as of 06:09, 16 November 2022
Return to Unit Reference
Description
Ultibo Touch Interface unit
Constants
Touch specific constants
TOUCH_* TOUCH_NAME_PREFIX = 'Touch';
|
Name prefix for Touch Devices |
Touch device type
TOUCH_TYPE_* TOUCH_TYPE_NONE = 0;
|
|
TOUCH_TYPE_RESISTIVE = 1;
|
|
TOUCH_TYPE_CAPACITIVE = 2;
|
|
TOUCH_TYPE_MAX = 2;
|
|
Touch device state
TOUCH_STATE_* TOUCH_STATE_DISABLED = 0;
|
|
TOUCH_STATE_ENABLED = 1;
|
|
TOUCH_STATE_MAX = 1;
|
|
Touch device flag
TOUCH_FLAG_* TOUCH_FLAG_NONE = $00000000;
|
|
TOUCH_FLAG_NON_BLOCK = $00000001;
|
If set device reads are non blocking (Also supported in Flags parameter of TouchDeviceRead) |
TOUCH_FLAG_PEEK_BUFFER = $00000002;
|
Peek at the buffer to see if any data is available, don't remove it (Used only in Flags parameter of TouchDeviceRead) |
TOUCH_FLAG_MOUSE_DATA = $00000004;
|
If set the device will write a mouse data event for each touch event |
TOUCH_FLAG_MULTI_POINT = $00000008;
|
If set the device supports multi point touch |
TOUCH_FLAG_PRESSURE = $00000010;
|
If set the device supports pressure value on touch points |
TOUCH_FLAG_SWAP_XY = $00000020;
|
If set swap the X and Y coordinates |
TOUCH_FLAG_INVERT_X = $00000040;
|
If set invert the X coordinate |
TOUCH_FLAG_INVERT_Y = $00000080;
|
If set invert the Y coordinate |
TOUCH_FLAG_SWAP_MAX_XY = $00000100;
|
If set swap the maximum X and Y values |
| Flags supported by TOUCH_CONTROL_GET/SET/CLEAR_FLAG | |
TOUCH_FLAG_MASK = TOUCH_FLAG_NON_BLOCK or TOUCH_FLAG_MOUSE_DATA or TOUCH_FLAG_MULTI_POINT or TOUCH_FLAG_PRESSURE or TOUCH_FLAG_SWAP_XY or TOUCH_FLAG_INVERT_X or TOUCH_FLAG_INVERT_Y or TOUCH_FLAG_SWAP_MAX_XY;
| |
Touch device control code
TOUCH_CONTROL_* TOUCH_CONTROL_GET_FLAG = 1;
|
Get Flag |
TOUCH_CONTROL_SET_FLAG = 2;
|
Set Flag |
TOUCH_CONTROL_CLEAR_FLAG = 3;
|
Clear Flag |
TOUCH_CONTROL_FLUSH_BUFFER = 4;
|
Flush Buffer |
TOUCH_CONTROL_GET_WIDTH = 5;
|
Get Screen Width |
TOUCH_CONTROL_GET_HEIGHT = 6;
|
Get Screen Height |
TOUCH_CONTROL_GET_MAX_X = 7;
|
Get Maximum X value (Only applies to Absolute X values) |
TOUCH_CONTROL_GET_MAX_Y = 8;
|
Get Maximum Y value (Only applies to Absolute Y values) |
TOUCH_CONTROL_GET_MAX_Z = 9;
|
Get Maximum Z value (Only applies to Absolute Z values) |
TOUCH_CONTROL_GET_MAX_POINTS = 10;
|
Get Maximum number of Touch Points |
TOUCH_CONTROL_GET_ROTATION = 11;
|
Get Rotation value (0, 90, 180, 270)(Only where supported by the driver) |
TOUCH_CONTROL_SET_ROTATION = 12;
|
Set Rotation value (0, 90, 180, 270)(Only where supported by the driver) |
Touch buffer size
TOUCH_BUFFER_* TOUCH_BUFFER_SIZE = 1024;
|
Touch data definitions
TOUCH_FINGER*, TOUCH_ID_* | Values for TTouchData.Info | |
TOUCH_FINGER = $00000001;
|
A finger is pressed at this touch point |
| Values for TTouchData.PointID | |
TOUCH_ID_UNKNOWN = Word(-1);
|
|
| Values for TTouchData.PositionX | |
TOUCH_X_UNKNOWN = -1;
|
|
| Values for TTouchData.PositionY | |
TOUCH_Y_UNKNOWN = -1;
|
|
| Values for TTouchData.PositionZ | |
TOUCH_Z_UNKNOWN = -1;
|
|
Touch rotation
TOUCH_ROTATION_* TOUCH_ROTATION_0 = FRAMEBUFFER_ROTATION_0;
|
No rotation |
TOUCH_ROTATION_90 = FRAMEBUFFER_ROTATION_90;
|
90 degree rotation |
TOUCH_ROTATION_180 = FRAMEBUFFER_ROTATION_180;
|
180 degree rotation |
TOUCH_ROTATION_270 = FRAMEBUFFER_ROTATION_270;
|
270 degree rotation |
Touch logging
TOUCH_LOG_* TOUCH_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;
|
Touch debugging messages |
TOUCH_LOG_LEVEL_INFO = LOG_LEVEL_INFO;
|
Touch informational messages, such as a device being attached or detached |
TOUCH_LOG_LEVEL_WARN = LOG_LEVEL_WARN;
|
Touch warning messages |
TOUCH_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;
|
Touch error messages |
TOUCH_LOG_LEVEL_NONE = LOG_LEVEL_NONE;
|
No Touch messages |
Type definitions
Touch data
PTouchData = ^TTouchData;
TTouchData = record
Info:LongWord;
|
|
PointID:Word;
|
|
PositionX:SmallInt;
|
|
PositionY:SmallInt;
|
|
PositionZ:SmallInt;
|
Touch buffer
PTouchBuffer = ^TTouchBuffer;
TTouchBuffer = record
Wait:TSemaphoreHandle;
|
Buffer ready semaphore |
Start:LongWord;
|
Index of first buffer ready |
Count:LongWord;
|
Number of entries ready in buffer |
Buffer:array[0..(TOUCH_BUFFER_SIZE - 1)] of TTouchData;
|
Touch properties
PTouchProperties = ^TTouchProperties;
TTouchProperties = record
Flags:LongWord;
|
Device flags (eg TOUCH_FLAG_MULTI_POINT) |
Width:LongWord;
|
Screen Width |
Height:LongWord;
|
Screen Height |
Rotation:LongWord;
|
Screen Rotation (eg TOUCH_ROTATION_180) |
MaxX:LongWord;
|
Maximum (absolute) X value for the touch device |
MaxY:LongWord;
|
Maximum (absolute) Y value for the touch device |
MaxZ:LongWord;
|
Maximum (absolute) Z value for the touch device |
MaxPoints:LongWord;
|
Maximum number of touch points |
Touch enumeration callback
TTouchEnumerate = function(Touch:PTouchDevice; Data:Pointer):LongWord;
|
Touch notification callback
TTouchNotification = function(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;
|
Touch device start
TTouchDeviceStart = function(Touch:PTouchDevice):LongWord;
|
Touch device stop
TTouchDeviceStop = function(Touch:PTouchDevice):LongWord;
|
Touch device peek
TTouchDevicePeek = function(Touch:PTouchDevice):LongWord;
|
Touch device read
TTouchDeviceRead = function(Touch:PTouchDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
|
Touch device write
TTouchDeviceWrite = function(Touch:PTouchDevice; Buffer:Pointer; Size,Count:LongWord):LongWord;
|
Touch device flush
TTouchDeviceFlush = function(Touch:PTouchDevice):LongWord;
|
Touch device update
TTouchDeviceUpdate = function(Touch:PTouchDevice):LongWord;
|
Touch device control
TTouchDeviceControl = function(Touch:PTouchDevice; Request:Integer; Argument1:LongWord; var Argument2:LongWord):LongWord;
|
Touch device get properties
TTouchDeviceGetProperties = function(Touch:PTouchDevice; Properties:PTouchProperties):LongWord;
|
Touch device
PTouchDevice = ^TTouchDevice;
TTouchDevice = record
| Device Properties | |
Device:TDevice;
|
The Device entry for this Touch device |
| Touch Properties | |
TouchId:LongWord;
|
Unique Id of this Touch device in the Touch device table |
TouchState:LongWord;
|
Touch device state (eg TOUCH_STATE_ENABLED) |
DeviceStart:TTouchDeviceStart;
|
A Device specific DeviceStart method implementing the standard Touch device interface (Mandatory) |
DeviceStop:TTouchDeviceStop;
|
A Device specific DeviceStop method implementing the standard Touch device interface (Mandatory) |
DevicePeek:TTouchDevicePeek;
|
A Device specific DevicePeek method implementing a standard Touch device interface (Or nil if the default method is suitable) |
DeviceRead:TTouchDeviceRead;
|
A Device specific DeviceRead method implementing a standard Touch device interface (Or nil if the default method is suitable) |
DeviceWrite:TTouchDeviceWrite;
|
A Device specific DeviceWrite method implementing a standard Touch device interface (Or nil if the default method is suitable) |
DeviceFlush:TTouchDeviceFlush;
|
A Device specific DeviceFlush method implementing a standard Touch device interface (Or nil if the default method is suitable) |
DeviceUpdate:TTouchDeviceUpdate;
|
A Device specific DeviceUpdate method implementing a standard Touch device interface (Or nil if the default method is suitable) |
DeviceControl:TTouchDeviceControl;
|
A Device specific DeviceControl method implementing a standard Touch device interface (Or nil if the default method is suitable) |
DeviceGetProperties:TTouchDeviceGetProperties;
|
A Device specific DeviceGetProperties method implementing a standard Touch device interface (Or nil if the default method is suitable) |
| Driver Properties | |
Lock:TMutexHandle;
|
Device lock |
Buffer:TTouchBuffer;
|
Touch input buffer |
Properties:TTouchProperties;
|
Device properties |
| Statistics Properties | |
ReceiveCount:LongWord;
|
|
ReceiveErrors:LongWord;
|
|
BufferOverruns:LongWord;
|
|
| Internal Properties | |
Prev:PTouchDevice;
|
Previous entry in Touch device table |
Next:PTouchDevice;
|
Next entry in Touch device table |
Public variables
Touch logging
TOUCH_DEFAULT_LOG_LEVEL:LongWord = TOUCH_LOG_LEVEL_DEBUG;
|
Minimum level for Touch messages. Only messages with level greater than or equal to this will be printed. |
TOUCH_LOG_ENABLED:Boolean;
|
Function declarations
Initialization functions
procedure TouchInit;
Description: Initialize the Touch unit and Touch device table
| Note | Called only during system startup |
|---|
Touch functions
function TouchDeviceStart(Touch:PTouchDevice):LongWord;
Description: Start the specified Touch device ready for receiving events
| Touch | The Touch device to start |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function TouchDeviceStop(Touch:PTouchDevice):LongWord;
Description: Stop the specified Touch device and terminate receiving events
| Touch | The Touch device to stop |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function TouchDevicePeek(Touch:PTouchDevice):LongWord;
Description: Peek at the buffer of the specified touch device to see if any data packets are ready
| Touch | The Touch device to peek at |
|---|---|
| Return | ERROR_SUCCESS if packets are ready, ERROR_NO_MORE_ITEMS if not or another error code on failure. |
function TouchDeviceRead(Touch:PTouchDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: Read touch data packets from the buffer of the specified touch device
| Touch | The Touch device to read from |
|---|---|
| Buffer | Pointer to a buffer to copy the touch data packets to |
| Size | The size of the buffer in bytes (Must be at least TTouchData or greater) |
| Flags | The flags for the behaviour of the read (eg TOUCH_FLAG_NON_BLOCK) |
| Count | The number of touch data packets copied to the buffer |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function TouchDeviceWrite(Touch:PTouchDevice; Buffer:Pointer; Size,Count:LongWord):LongWord;
Description: Write touch data packets to the buffer of the specified touch device
| Touch | The Touch device to write to |
|---|---|
| Buffer | Pointer to a buffer to copy the touch data packets from |
| Size | The size of the buffer in bytes (Must be at least TTouchData or greater) |
| Count | The number of touch data packets to copy from the buffer |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function TouchDeviceFlush(Touch:PTouchDevice):LongWord;
Description: Flush the contents of the buffer of the specified touch device
| Touch | The Touch device to flush |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function TouchDeviceUpdate(Touch:PTouchDevice):LongWord;
Description: Request the specified touch device to update the current configuration
| Touch | The Touch device to update |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Items updated can include rotation, maximum X and Y and flags (If supported) |
function TouchDeviceControl(Touch:PTouchDevice; Request:Integer; Argument1:PtrUInt; var Argument2:PtrUInt):LongWord;
Description: Perform a control request on the specified touch device
| Touch | The Touch device to control |
|---|---|
| Request | The request code for the operation (eg TOUCH_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 TouchDeviceProperties(Touch:PTouchDevice; Properties:PTouchProperties):LongWord; inline;
Description: Get the properties for the specified Touch device
| Touch | The Touch device to get properties from |
|---|---|
| Properties | Pointer to a TTouchProperties structure to fill in |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Replaced by TouchDeviceGetProperties for consistency |
function TouchDeviceGetProperties(Touch:PTouchDevice;Properties:PTouchProperties):LongWord;
Description: Get the properties for the specified Touch device
| Touch | The Touch device to get properties from |
|---|---|
| Properties | Pointer to a TTouchProperties structure to fill in |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function TouchDeviceCreate:PTouchDevice;
Description: Create a new Touch device entry
| Return | Pointer to new Touch device entry or nil if Touch device could not be created |
|---|
function TouchDeviceCreateEx(Size:LongWord):PTouchDevice;
Description: Create a new Touch device entry
| Size | Size in bytes to allocate for new Touch device (Including the Touch device entry) |
|---|---|
| Return | Pointer to new Touch device entry or nil if Touch device could not be created |
function TouchDeviceDestroy(Touch:PTouchDevice):LongWord;
Description: Destroy an existing Touch device entry
| Touch | The Touch device to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function TouchDeviceRegister(Touch:PTouchDevice):LongWord;
Description: Register a new Touch device in the Touch device table
| Touch | The Touch device to register |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function TouchDeviceDeregister(Touch:PTouchDevice):LongWord;
Description: Deregister an Touch device from the Touch device table
| Touch | The Touch device to dregister |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function TouchDeviceFind(TouchId:LongWord):PTouchDevice;
Description: Find a Touch device by ID in the Touch device table
| TouchId | The ID number of the Touch device to find |
|---|---|
| Return | Pointer to Touch device entry or nil if not found |
function TouchDeviceFindByName(const Name:String):PTouchDevice; inline;
Description: Find a Touch device by name in the device table
| Name | The name of the Touch device to find (eg Touch0) |
|---|---|
| Return | Pointer to Touch device entry or nil if not found |
function TouchDeviceFindByDescription(const Description:String):PTouchDevice; inline;
Description: Find a Touch device by description in the device table
| Description | The description of the Touch to find (eg USB Touchscreen) |
|---|---|
| Return | Pointer to Touch device entry or nil if not found |
function TouchDeviceEnumerate(Callback:TTouchEnumerate; Data:Pointer):LongWord;
Description: Enumerate all Touch devices in the Touch device table
| Callback | The callback function to call for each Touch device in the table |
|---|---|
| Data | A private data pointer to pass to callback for each Touch device in the table |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function TouchDeviceNotification(Touch:PTouchDevice; Callback:TTouchNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: Register a notification for Touch device changes
| Touch | The Touch device to notify changes for (Optional, pass nil for all Touch devices) |
|---|---|
| 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) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
Touch helper functions
function TouchGetCount:LongWord; inline;
Description: Get the current Touch device count
| Return | The number of Touch devices |
|---|
function TouchDeviceGetDefault:PTouchDevice; inline;
Description: Get the current default Touch device
| Return | Pointer to default Touch device entry |
|---|
function TouchDeviceSetDefault(Touch:PTouchDevice):LongWord;
Description: Set the current default Touch device
| Touch | The Touch device to set as default |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function TouchDeviceCheck(Touch:PTouchDevice):PTouchDevice;
Description: Check if the supplied Touch device is in the Touch device table
| Touch | The Touch device to check |
|---|---|
| Return | Pointer to Touch device entry or nil if not found |
function TouchDeviceTypeToString(TouchType:LongWord):String;
Description: Return a string describing the Touch device type (eg TOUCH_TYPE_CAPACITIVE)
| Note | None documented |
|---|
function TouchDeviceStateToString(TouchState:LongWord):String;
Description: Return a string describing the Touch device state (eg TOUCH_STATE_ENABLED)
| Note | None documented |
|---|
function TouchDeviceRotationToString(Rotation:LongWord):String;
Description: Return a string describing the supplied touch rotation value
| Note | None documented |
|---|
function TouchDeviceResolveRotation(ARotation:LongWord):LongWord;
Description: Resolve a value of 0, 90, 180 or 270 to a touch rotation constant (eg TOUCH_ROTATION_180)
| Note | Also accepts passing the touch rotation constant values directly |
|---|
function TouchDeviceSetCallback(Touch:PTouchDevice; Event:TTouchEvent; Parameter:Pointer):LongWord;
Description: Set the event callback function for the specified touch device
| Touch | The touch device to set the event callback for |
|---|---|
| Event | The event callback function to be called when touch data is received |
| Parameter | A pointer to private data to be passed to the callback with each event |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | This function also clears the TOUCH_FLAG_MOUSE_DATA flag because the event callback is not compatible with receiving touch events as mouse data |
function TouchInsertData(Touch:PTouchDevice; Data:PTouchData; Signal:Boolean):LongWord;
Description: Insert a TTouchData entry into the touch device buffer
| Touch | The touch device to insert data for |
|---|---|
| Data | The TTouchData entry to insert |
| Signal | If True then signal that new data is available in the buffer |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Caller must hold the touch device lock |
procedure TouchLog(Level:LongWord; Touch:PTouchDevice; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure TouchLogInfo(Touch:PTouchDevice; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
procedure TouchLogWarn(Touch:PTouchDevice; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
procedure TouchLogError(Touch:PTouchDevice; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
procedure TouchLogDebug(Touch:PTouchDevice; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
Return to Unit Reference
