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      

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:


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

  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);

When selected, if a touch starts outside a toolbar and then moves into a toolbar area, the touch remains held.