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
}toolbar;
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:
toolbar.<index>.value
Prior to UPDD V7 toolbars were associated with a device. With UPDD V7 toolbars are associated with a monitor.
The example below shows device based toolbar settings in UPDD V6 and monitor based toolbar settings for UPDD V7
| UPDD V6 - Device settings |
UPDD V7 - Global (nodevice) settings |
 |
 |
Setting meanings
| V6 and V7 |
|
| columns |
No. of columns |
| rows |
No. of rows |
| x |
left |
| w |
width |
| y |
top |
| h |
height |
| name |
Name |
| off_screen |
0 = on screen / 1 = off screen placement |
| enabled |
0 = disabled / 1 = enabled |
| count |
No. of toolbars for this device / monitor |
| hold_touch |
When selected, if a touch starts outside a toolbar and then moves into a toolbar area, the touch remains held. |
| UPDD V7 |
|
| latched |
Indicates a toolbar can be latched on rather than having to be touched to register as being touched. A latched on toolbar is set off if tapped. Touching a latched toolbar for a period of time will always set the latched toolbar off, irrespective of its current state. |
| monitor_number |
Associated monitor |
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 calibrate a toolbar:
mode must be toolbar
both device handle and toolbar index are required
TBBOOL TBAPI TBApiCalibrate(HTBDEVICE aHandle, int aToolbarIndex, TBCHAR* aMode);
| When selected, if a touch starts outside a toolbar and then moves into a toolbar area, the touch remains held. |