Toolbars

Revision 1.5, 10^th Jan 2008

A toolbar is an area on the touch screen that acts independently from the main calibrated video area, as shown below;

Toolbars are utilised in all manner of pointer device type applications. A toolbar is sub divided into cells of equal size which are arranged into a specified number of rows and columns. They can simply be used to mask off areas of the calibrated video area or they can be used to trigger an event. They are particularly useful if a pointer device has both a calibrated, mouse emulation area and a non-mouse emulation area handled by an external application. A toolbar event can be associated with a UPDD Toolbar function or application functions. The cursor does not move from its current position when a toolbar is touched.

Toolbars can be positioned anywhere on a touch screen as suits requirements. Toolbars that reside outside the main touchscreen / video display area are normally referred to as the touch surround area. Toolbars that reside within the video display area can also have a bitmap displayed (Windows only at time of writing) within the cell to cater for an on-screen visual reference. Bitmaps can also be associated to toggled or touched cell states so there can be visual feedback on cell activation.

Toolbars can be calibrated individually or defined such their position is relative to, and calculated from, the main video calibration area.

Toolbar Definition

Toolbars can be defined and configured in a number of ways:

Using the UPDD V4 UPDD Console, toolbar dialog
Pre-defined in the UPDD configuration files
Created by external applications
Manually defined in the UPDD Configuration files (normally used in embedded environments or where a UPDD Console program is not available for the target system)

The separate definition methods are described below:

UPDD Console, Toolbar option

The Toolbar dialog is used to define and configure toolbars. If disabled this function can be enabled with the /tbr parameter when invoking the console (i.e. dcu.exe /tbr) - UPDD 4.0.4 and above

Choose “Toolbars” and “Add a new toolbar” to create toolbars.

The following example shows a toolbar definition of 1 row and 10 columns.

Individual functions are described in the UPDD Console help system and can be viewed here.

Pre-defined

The name, number of rows and columns are defined in our software production system such that they are specified in the configuration files delivered as part of the software.

Created by external applications using the UPDD API

Using the UPDD SDK, API calls to create, delete and calibrate toolbars as required.

Embedded configurations

For embedded systems, such as Windows CE and XPe, where all elements of the system are built remotely into an embedded image, the toolbars can are defined in the embedded configuration files. In this environment, UPDD is supplied in embedded component form with preset configuration files and normally the toolbars will be pre-defined in the configuration files.

If the toolbars are not pre-defined in the delivered UPDD configuration files or they need to be updated or others need to be added then they need to be created system using the UPDD Console and then extracted into the UPDD embedded configuration files as described below:

Win CE

For Win CE the procedure is as follows:

Load up the UPDD Console on the system running the CE platform builder and invoke the toolbar option. Create the toolbars as required on the target CE hardware.

Once complete, export the following registry entry (e.g. by using regedit's export option) and embed these, along with the regular UPDD settings as defined in the UPDD CE integrators guide.

Export the complete hive

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TBUPDD\Parameters\{guid}\N\Toolbars

and take the contents of the exported file and replace all occurrences of

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TBUPDD\Parameters\{guid}\1\Toolbars]

with

[HKEY_LOCAL_MACHINE\Drivers\BuiltIn\TBUPDD\Parameters\{guid}\1\Toolbars]

Take care to check that the guid value in the edited item matches that in the earlier entries in tbupddce.reg (it may differ from the exported value).

Add the file contents, keeping the same names and locations, to the end of the tbupddce.reg prior to embedding.

Windows XPe

To follow.

Calibration

Once the toolbars are defined they can be calibrated in a number of ways:

using UPDD Console, toolbar calibration option
UPDD System Tray, Calibrate option (Windows only)
via the TBcalib program, by passing the appropriate parameter
automatically extrapolated from the main video calibration.

Calibrate via the Toolbar dialog

Select the option on the UPDD Console toolbar dialog and follow the instructions to touch top left and bottom right corners of the toolbar. Touch the area of the screen where you need the toolbar to be located.

Calibrate via TBcalib program

Invoke TBcalib to calibrate an individual toolbar or all toolbars

Tbcalib {Parameters}

The calibration program can accept a number of toolbar parameters, as follows:

Bundle={specify GUID} - only calibrate devices in a specific bundle

Device=n - only calibrate the specified device and currently selected calibration mode.

Toolbar=whatever - only calibrate toolbar whatever

TOOLBAR - only calibrate toolbars

Please note parameters are case sensitive and must be defined as shown above.

and follow the instructions to touch top left and bottom right corners of the toolbar.

Calibrate via the UPDD system tray, calibrate option

The UPDD System Tray, Calibrate option lists both the desktop calibration styles and toolbars. Select the Toolbar from the list to initiate calibration.

Calculated automatically relative to the desktop calibration

UPDD version 04.00.02 introduces a new relative toolbar concept. Relative toolbars allow the position of the toolbar to be specified relative to the calibrated desktop area. This allows the toolbars to be calibrated from a single calibration. In addition to simplifying the end user experience relative toolbars make it practical to implement larger numbers of toolbars and more complex toolbar layouts in the touch environment.

Calculating the toolbar position

In order to specify the position of a toolbar it is required to calculate the toolbar’s position relative to the desktop. UPDD works with a nominal video co-ordinate system which defines the primary display having a range of 0 – 65535 for x and y with the origin at the top left.

For each toolbar it is required to calculate the left to right and bottom co-ordinates of each toolbar. The following example illustrates how this is done for a toolbar outside the video area.

Firstly take physical measurements of the 6 values illustrated above.

WT=width of toolbar

HT=height of toolbar

WV=width of video area

HV=height of video area

TT=top of toolbar

LT=left of toolbar

Next calculate left, top, bottom, and right offsets as follows.

Left = LT / WV * 65535
Right = (WT / WV * 65535) + Left
Top = TT / HV * 65535
Bottom = (HT / HV * 65535) + Top

Defining the toolbar position

Having calculated the relative positions you need to associate these values with the toolbar. This can be performed through the UPDD Console, Toolbar dialog, Change Toolbar option or directly editing the configuration files (if you have embedded configuration files with toolbars currently defined)

Change toolbar option

Select the “Change toolbar options” function in the UPDD console, toolbar dialog.

Select the option “placement relative to primary display” and enter the 4 values calculated above.

Embedded Configuration files

Win CE

In the Win CE configuration file (tbupddce.reg) locate the entry

[HKEY_LOCAL_MACHINE\Drivers\BuiltIn\TBUPDD \Parameters\{guid}\1\Toolbars\N\]

and change keys

RelativeMode to 1

and

RPosX0, RPosX1, RPosY0 and RPosY1 to the calculated relative values (which may be negative!).

PosX0, PosX1, PosY0 and PosY1 are used by the calibration program to store the actual position of the toolbars.

Windows XPe

To follow.

Toolbar Options

Toolbar options are defined in the Change Toolbar dialog.

Option	Description
Rows and Columns	Defines the number of rows and columns
Placement	Relative placement values. Defines the position of the toolbar relative to the main desktop calibration. See above.
Placement relative to primary display	Indicates the toolbar position is relative to main video area calibration. See above.
Follow rotate	Indicates if toolbar is locked (associated) to the desktop display and should be relocated if the video is rotated. If not set, toolbar remains in same physical position irrespective of video rotation. See Rotate documentation.
Dragable	Indicates if toolbar can be repositioned by drag. Touching and holding the toolbar for a short period of time allows the toolbar to be moved to a new position.

Toolbar Cell Actions

Toolbars cells can be associated with UPDD Toolbar functions or are useful for providing control input to an application program via the UPDD SDK API calls.

UPDD Toolbar functions

These functions, which are tailored to individual operating systems (Window, Mac OS X, Linux), can be used to invoke UPDD utilities (such us on-screen annotation), generate virtual keys, invoke applications, to playback macros (recorded keystrokes and mouse usage), to rotate the display area, to display on-screen keyboards etc.

Selecting the UPDD Console, Toolbar dialog, Change cell options invokes a dialog to configure the UPDD event associated with a toolbar cell. Depending on the operating system in use the dialog and available functions will differ. The dialog and available functions for each OS is discussed below:

Windows desktop

This dialog is used to associate an action with the Toolbar when it is pressed.

The various settings are described below:

Type of Action	Description
Ascii Key	Generate an ASCII key(s). Key to generate can be manually defined or the ‘Copy next keyboard input’ can be selected so the next input is used to set up the desired ASCII text. Control (modifer) keys Ctrl, Alt, Shift and Windows can be set as required. Repeat means the key is repeated as long as the toolbar is touched. Sticky means the key is held down.
Execute a command	The command to execute is defined. You can either define the full path or use the command ‘cmd /c Start [program]’ e.g. cmd /c Start Winword, such that the system will use a command shell to locate the program.
None	No action defined.
Play Macro	Playback a UPDD mouse and keyboard macro created for the UPDD macro recorder
UPDD Action	UPDD Action. Offers a list of specific actions to associate with the toolbar.
	Annotate xxxx	Start, stop, pause, erase the UPDD Annotate program
	Cal-style	Select or Switch calibration styles
	Calculator	Load the system calculator
	Calibrate	Invoke calibration
	Calibrate toolbars	Invoke toolbar calibration
	Event Selector	Switch Event states
	Event Selector Primary	Invoke primary Event
	Event Selector Secondary	Invoke secondary Event
	Keyboard	Load a virtual keyboard
	None	No Action
	Rotate	Rotate the screen using one of the supported rotate methods
	Touch	On, off or toggled
Virtual Key	Generate a virtual key. Key to generate can be manually defined or the ‘Copy next keyboard input’ can be selected so the next input is used to set up the desired Virtual Key.

Enabled - When checked indicates the cell is active.

Copy next keyboard input – can be selected at any time such that the next keyboard input will be used to set up a desired ASCII or Virtual key, depending on the key sequence entered. Note that due to the odd dual mode behavior of the Windows modifier key the “copy next” option does not work with for this key.

Cell Images
A toolbar cell can contain a transparent image. Any colour defined with RGB of 0 will be deemed transparent when displayed on the desktop. Toolbar images are displayed ‘on top’ so that no other applications (even ‘on top’ applications) can cover the toolbar images. Some images are shipped with the UPDD software. As an example of toolbar cell images, the following are used in the UPDD Annotate application which uses three toolbar cells to invoke drawing, pause and erase functions. The mouse images are used in the Event Selector toolbar cell and the button is an example of a button image:

Images can be defined for three different cell states, as described below:
Normal	Untouched state
Pressed	Whilst cell is touched
Toggled	When cell is toggled. A cell can be toggled between two stated depending on various UPDD states
	<touched>	Touched
	Alt State active	Alternative Event State active
	Anchor Mouse	Anchor mouse is enabled
	UPDD Annotate off	Annotation inactive
	UPDD Annotate on	Annotation active
	UPDD Annotate paused	Annotate pause
	Calibration style	Calibration style switched
	Enabled	Touch enabled
	Motion	Motion enabled
	Rotate	Rotate state active
	Sound	Sound active

Play sound. A Windows sound or Wave file can be associated with the cell touch / untouch.

Example

This example is shown in the Change Cell Option dialog image at the beginning of this section.

Create a cell called Start and calibrate in the top left-hand corner. Select Change cell option and define the type of action as ‘Virtual Key’ and select the Key code ‘VK_LWIN’ and select OK. Now press the toolbar and see the Windows start menu appear.

Mac OS X

This dialog is used to associate an action with the Toolbar when it is pressed.

The various settings are described below:

Type of Action	Description
Ascii Key	Generate an ASCII key(s). Enter the text that you want to be output when the toolbar cell is touched into the "Text" textbox. Controls keys Ctrl, Shift Command and Option can be set as required. For example this could be used to generate CTRL-C. The command option is a MAC “modifier” key - command + <any ascii character> will do whatever normally happens when the command key on the keyboard and the specified ascii key is pressed. E.g. if Finder is the active application then command + n will create a new finder window.
None	No action defined.
Virtual Key	Generate a virtual key.

Enabled - When checked indicates the cell is active.

Linux

To follow as no cell actions are currently available for the Linux environment.

Application functions

When a cell is touched this is reported to any application program that has used the UPDD API and registered an interest using the TBApiRegisterDataCallback function with the _ReadDataTypeToolbar option.

Integrating the toolbar settings

In order to replicate the toolbar settings on a Windows desktop system (e.g. Windows XP) use the UPDD Console, Status, Dump settings option to create a clone file and integrate this with your distributed installer as described in the Installation Notes document, Installation Options.

For Win CE and XPe see Embedded configuration section above.

Toolbar examples

In the following toolbar example, 4 toolbars are used to cater for the layout:

Toolbar	Row	Column

Left	7	1
Right	7	1
Alpha	3	13
Numpad	4	3

An external application will register with the UPDD driver to be notified when toolbars are touched and act accordingly.

Example toolbar CE code is available as described in the UPDD Source Code examples document.

Contact

For further information or technical assistance please email the technical support team at technical@touch-base.com