Description |
Informs the API that a function is to be used as a callback function for receipt of the specified type(s) of data. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Parameters |
The device handle, a context identifier, the required data type(s) constants which may be OR’d together and a pointer to the callback routine. Possible constants are:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Returns |
0 = fail, 1 = OK. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Notes |
1. The callback function is executed in the context of a dedicated thread therefore only thread safe (reentrant) functions should be called from the callback function - many windowing api functions are non-reentrant - if you need to call non-reentrant functions you need to provide synchronisation management - a common way to achieve this is to post a message to the primary process thread and perform all non-reentrant operations from the primary thread. 2. The context value is passed unchanged to the callback function for identification purposes. All functions registered must be unregistered before the program terminates, see calls below. 3. To trap all events, pass a value of 0x1FFFFF (or &H1FFFFF for VB) in the aTypes parameter. 4. To get data for all devices pass device handle 0. 5. Note that underscore prefixes are omitted in Visual Basic declarations, i.e. _ReadDataTypeXY becomes ReadDataTypeXY. 6. You should always ensure that a callback for _ReadDataTypeUnload is registered; the driver will invoke this callback:-
…at which time you should unregister any other callbacks and terminate. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
This structure (struct _PointerData) can be found in the header file TBapi.h. It is used to hold pointer (and other) data returned from the driver to a registered callback routine The data returned is directly related to the callback trigger as specified at the time of callback registration, such as:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
UPDD manages a number of states or conditions related to touch, such as “is the screen being touched” or “is a tip button pressed”. Changes in these states are known collectively as events throughout the API and the API provides a number of features to work with these events.
State categories
UPDD recognises 3 types of state and reports events for changes of each of these. States are mostly boolean (true / false) values, apart from EVNN which is presents as an unsigned integer value; but can of course be split into up to 32 single bit boolean values as required.
1) Physical state. This relates to whether the touch device has been physically activated. In the normal case this means that the user is touching the screen, but it can also mean that a button (eg on a pen) or other physical action has taken place. Specifically a physical state event TRUE is sent when any packet is received from the touch device with touch data (X / Y / L=true / R=true / LIFT=false bits in the data packet) . a physical state event TRUE is sent when any packet is received from the touch device when one of the following occurs a) The L or R bit that set the state is matched by a false value for the same bit. b) A lift = true bit is received c) A timed liftoff occurs
There is one physical state per
supported stylus. 2) Logical state. The logical state indicates the actual state of touch as might be delivered to the operating system. NB whether the state is passed to the operating system depends on other settings. In a normal touch scenario, touching a touch screen will always result in the logical state being set and an event being delivered to any API program registered for it, but if the mouse port is disabled using TBApiMousePortInterfaceEnable, then no information is deliverd to the operating system. There are 2
logical states per supported stylus, one for left button actions, the other
for right button actions. 3) Flags state. UPDD recognises 3 flags that can be defined in a data packet. L R and EVNN. L and R represent single bits in the data packet. EVNN represents an integer value that can be described by up to 32 bits in the packet.
Event types
For each of the state types listed above there is a corresponding event type that can be received by an API based program.
Physical event A program registers to receive physical events by passing _ReadDataTypePhysicalEvent as an argument to TBApiRegisterDataCallback
A physical event callback is received whenever the value of a physical state is changed.
The following struct is used to define a physical event
struct _physicalEvent { bool state; // the value that the state changed to bool timed; // whether the change is triggered by a timeout(e.g. liftoff time) bool wasToolbarTouch; // was the touch in a toolbar area when the state change to true }physicalEvent;
Logical event
A program registers to receive logical events by passing _ReadDataTypeLogicalEvent as an argument to TBApiRegisterDataCallback
A logical event callback is received whenever the value of a logical state is changed.
The following struct is used to define a logical event
struct _logicalEvent { bool left; // does this represent a left mouse button action bool state; // the value that the state changed to bool timed; // whether the change is triggered by a timeout (eg liftoff time) bool wasToolbarTouch; // was the touch in a toolbar area when the state change to true }logicalEvent;
Flags event
A program registers to receive logical events by passing _ _ReadDataTypeFlagsEvent as an argument to TBApiRegisterDataCallback
A flags event callback is received whenever the driver processes a data packet having flag related data (L / R / EVNN).
The following struct is used to define a flags event
struct _flagsEvent { bool hasEVNN; // true if the evnn field has valid data uint32_t evnn; // value of the EVNN bits in the data packet bool hasLBit; // true if the lBit field has valid data bool lBit; // value of the L bit in the data packet bool hasRBit; // true if the rBit field has valid data bool rBit; // value of the R bit in the data packet }flagsEvent;
5.1 conversion notes.
As this area of the API has changed in
UPDD version 5.1, existing client programs that utilise events will have to
be compiled to work with this driver version. The following notes should be of use for such a conversion.
_ReadDataTypeEvent is obsolete. The closest replacement is _ReadDataTypeLogicalEvent.
_ReadDataTypeRawEvent is obsolete. The closest replacement is __ReadDataTypePhysicalEvent for touch data and _ReadDataTypeFlagsEvent for flag related data.
struct _rawEvent is obsolete. The closest replacement is struct _physicalEvent. Note that event handles are no longer used; instead the event is identified directly by the callback data. Because flag event callbacks are now monolithic, there is no need to look for handle == -1 as was previously the case when reading an change to EVNN.
struct _event is obsolete. The closest replacement is struct _logicalEvent for touch data and _ struct _flagsEvent for flag related data.
Note that prior to version 5.1 there was an event type of DFLT. This Is no longer supported but physical events provide more or less the same functionality.
NB these features became available in version 5.1.1259. Builds of 5.1 prior to this were work in progress in this area. If you have a need to utilise event API processing it is recommended that you upgrade if using an earlier 5.1.X version, particularly if implementing a program that works with multiple UPDD version.
A timing example
This simple example shows the sequence of events that occurs when a user touches the screen, with interactive touch mode active and an API program is in use:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Register data callback routine |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
See also |
Unregister data callback routine |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Unregister data callback routine context |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Visual C++ Declaration/example
BOOL TBAPI TBApiRegisterDataCallback(HTBDEVICE aDeviceHandle, unsigned long aContext, unsigned long aTypes, TB_DATA_CALL aFunc);
// In the following example CBFunc is called whenever pointer co-ordinates are processed by relative device 1 until TBApiUnregisterDataCallback is called
HTBDEVICE hd = TBApiGetRelativeDevice(0);
TBApiRegisterDataCallback(hd,0,_ReadDataTypeXY,CBFunc);
...
…
…
void TBAPI CBFunc(unsigned long context, _PointerData* data)
{
char buf[100];
sprintf(buf, "device %d Generated x=0x%x y=0x%x\n",
(int)data->pd.device,
(int)data->pd.xy->rawx,
(int)data->pd.xy->rawy);
AfxMessageBox(buf);
}
Public Declare Function TBApiRegisterDataCallback Lib "TBapi" Alias “_DLL_TBApiRegisterDataCallback@16" (ByVal aDeviceHandle As Byte, ByVal aContext As Long, ByVal aTypes As Long, ByVal aFunc As Long) As Long
Dim dev as byte
dev = TBApiGetRelativeDevice(0)
TBApiRegisterDataCallback dev, 0, ReadDataTypeXY, CBFunc
…
…
...
Public Sub CBFunc(ByVal iContext As Long, ByRef pMyData As CoordinateData)
With pMyData
MsgBox "device “ & .device & _
“ generated x=" & .RawX & _
" y=" & .RawY
End With
End Sub