The UPDD version 6 implementation of toolbars allows for the following API based operations.
Receiving event callbacks.
Setting or changing toolbar options.
Event callbacks follow the standard UPDD model for callbacks.
A program should register for events of type _EventTypeToolbar.
Information about toolbar events are delivered to the registered callback function with toolbar specific information in the following struct.
struct _toolbar // a toolbar area was touched
int16_t htoolbar; // tooolbar handle
int16_t row; // row # of cell
int16_t column; // column # of cell
uint8_t touching; // 1 = touching 0 = not touching
The following general fields are relevant to toolbar events
HTBDEVICE hDevice; // device handle that this event relates to or 0 if it is not device specific
TBSTYLUS hStylus; // stylus number, (also know as contact number or touch number) was HTBSTYLUS prior to V6
Note; at the end of a toolbar touch a not touching event is received. The report always shows the information for the last touched location, which might not be the toolbar or cell originally touched.
The client software must consider and handle this appropriately. For example, if the intention is to generate an action related to the originally touched cell then this cell must be recorded and utilized at the time of the not touching event. This information is identified by the key fields, hDevice + hStylus + htoolbar. If the end of touch occurs outside a toolbar the value of htoolbar is -1 . This scheme provides the maximum flexibility.
Settings for toolbars are held in standard UPDD settings and so can be simply managed by using regular API functions.
A toolbar setting takes the form:
The example below shows an example toolbar definition and the toolbar.count setting that gives the number of toolbars for a given device.
|| No. of columns
|| No. of rows
|| 0 = on screen / 1 = off screen placement
|| 0 = disabled / 1 = enabled
|| No. of toolbars for this device
Changing any of these values is simply a matter of using TBApiSetSettingFromInt or TBApiSetSetting.
Toolbars can also be added, removed and calibrated using standard APIs.
To add a toolbar
- Get toolbars.count
- Create new entries for all the above indexed values (toolbar.0.*) using toolbars.count as the new index
- Increment and save toolbars.count
To remove a toolbar
- Get the values of the toolbar with the highest index (toolbars.count – 1).
- Save these values against the index to be deleted.
- Decrement and save the value of toolbars.count
- Optionally delete the values with the previous highest index index.
To calibrate a toolbar
Use the TBApiCalibrate API function to calibrated a toolbar:
mode must be toolbar
both device handle and toolbar index are required
TBBOOL TBAPI TBApiCalibrate(HTBDEVICE aHandle, int aToolbarIndex, TBCHAR* aMode);