Toolbar API

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

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

1. Get toolbars.count
2. Create new entries for all the above indexed values (toolbar.0.*) using toolbars.count as the new index
3. Increment and save toolbars.count

 To remove a toolbar

1. Get the values of the toolbar with the highest index (toolbars.count – 1).
2. Save these values against the index to be deleted.
3. Decrement and save the value of toolbars.count
4. 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);