TBApiGetRawEventState API Call

Description

Gets the current state of a controller’s event handler.

Parameters

Device handle, event handle and pointer to return state variable.

Event handles are derived by calling TBApiGetSettingSZ. Registry entries are held (per device handle) as in the following example:

Event Bind 0 = “EV01”

Event Bind 1 = “DFLT”

Event Bind 2 = “EV00”

Event Bind 3 = “Z”

By knowing the event of interest, enumerate the registry until the desired handle is found. In this example if “EV00” is required, the handle to be used in subsequent calls to TBApiGetRawEventState is ‘2’.

Returns

0 = fail, 1 = OK.

Notes

When a pointer device is in use a stream of data, known as the data packet, is sent to the hardware port and the data is interpreted by UPDD. This data packet contains various types of information, mainly X and Y co-ordinates as the stylus moves around. The data is normally sent in a fixed number of bytes, each byte consisting of 8 bits (a bit being a single entity that can be either a 0 or 1). A bit or bits within a data packet can be used to indicate that an action has occurred on the device.

If a controller is using event bits UPDD needs to be informed what bits are event bits. This is achieved at the time the controller is defined to UPDD using mnemonics to describe the function of each bit within a byte. Mnemonics used to define event bits are internally labelled DFLT, Evnn (nn = 00 to 08), R, L, Z, HWnnn (nn= 01, 02, 04, 08, 16, 32, 64, 128), which relate to the following events

Event	Meaning
DFLT	DFLT = 1 while a data stream is present. It goes to 0 when a lift off occurs (either a lift packet is seen or liftoff time is reached).
EVnn	A user defined event bit. Set to 1 as required by the controller.
HWnnn	Relates to port hardware lines, e.g. with a UART, processed directly by UPDD, HW64 = RI, HW32 = DSR and HW16 = CTS.
Z	Z changes when the value of the Z data (for controllers with pressure axis) passes through the "Z Threshold" as defined in the UPDD DCU Settings.
L	Set to 1 when a left click event has occurred. Typically defined in mouse data packets.
R	Set to 1 when a right click event has occurred. Typically defined in mouse data packets.

e.g. a data packet has the following 1st byte defined in UPDD

Byte 1 = 1 LIFT EV00 EV01 EV02 EV03 TY08 TX08

1 is a sync bit, LIFT indicates the stylus contact state bit, Evnn the event bits and TYnn and TXnn are co-ordinate bits.

Whilst the data packet are being received by UPDD any Event bit(s) that change their state (0>1 or 1>0) are reported to any external application(s) that has registered an Event callback

Visual C++ Declaration/example

BOOL TBAPI TBApiGetRawEventState (HTBDEVICE aDeviceHandle, int aEventHandle, BOOL* aState);

Visual Basic Declaration/example

Public Declare Function TBApiGetRawEventState Lib "TBapi" Alias "_DLL_TBApiGetRawEventState@12" (ByVal aDeviceHandle as byte, ByVal aEventHandle as long, ByVal aState as long) as long