Skip to topic | Skip to bottom
Home
Main
Main.XmlManualr1.22 - 13 Mar 2009 - 12:36 - IvanWellesztopic end

Start of topic | Skip to actions

FingerWorks XML manual

Introduction

Several "fingerfans" have created this reference page so that it is now a useful manual on how to edit the FingerWorks XML. This was inspired by Ivanw's detailed answer in this forum post. There might exist more tags/attributes/values than listed here, so your contribution is requested! Please help us to fill in the blanks! The known gaps are marked like this:
  unknown   

Don't worry about formatting: Your knowledge is more important than the layout, so if you know something but are put off by the formatting here, just dump your data and we'll clean it up for you later!

Basic concepts

Valid XML

The configration file is valid XML. This means that all tags have matching closing tags or they are closed in-line, and any tag opened inside another tag must be closed before the other tag is closed. A tag may contain other tags. Within each tag name, there may be attributes.

Sample:

<TagOne attribute="value" another_attribute="some other value">
  <TagThree attribute="value" />
  <TagTwo attribute="more" another_attribute="any other value">
  </TagTwo>
</TagOne>

The actual names of tags, attributes, and values are not documented anywhere public. That's what this page is trying to achieve.

Header

The XML congifuration file always has this exact header, and everything else goes before that final line </MTS_config>:
<?xml?>
<!DOCTYPE MTS_config>
<MTS_config>

</MTS_config>

MTS_config_version
  unknown   
min_firmware_version
  unknown   

Exactly what do the values of MTS_config_version and min_firmware_version represent and do they matter?

Not sure about this, but it would figure these are the version numbers for the basic file. MTS_config_version is the latest version, that which is currently operating. min_firmware_version would be the basic minimum firmware version as reference. I don't know if these make any difference or are just record keeping. -- MarkSundberg - 23 Aug 2005

Sample:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MTS_config>
<MTS_config MTS_config_version="1.60" min_firmware_version="1.46">

</MTS_config>

RequireLib

Library on which some definitions refer to.
  • You can group your modifications by category.
  • Each category can be exported to a dedicated library file.
  • The file name will be used as a library name (save the XML suffix).
  • You must put this file under one of the directory searched by the editor.
  • The name attribute indicates the name of a library defining some macro_ref used in the current file.

Sample:

RequireLib name="my_lib_filename"

Touchpad coordinates

The touchpads use a numerical coordinate system with 0,0 at the bottom center of the TSLP. This means that the bottom right corner of the left pad and the bottom left corner of the right pad are 0,0. Going right from the center increases the x coordinate in the positive, and going left from the center increases the x coordinate in the negative. Going up from the bottom increases the y coordinate in the positive, while the absolute bottom of the pad is roughly y = -0.5.

The values are a centimeter measurement. The pad has a surface area of 16.5 x 12.5, and this matches the exteme values of the coordinate system: x = [-16.5;16.5] and y = [-0.5;12.0].

Ivanw's 'move your Q'.
The Tap Area Q is created with these coordinates (pay attention to xcenter, ycenter, xradius):

TOP-LEFT : <TapArea xcenter="-15.8" ycenter="11.5"><MacroRefEvent macro_ref="  Q  "/></TapArea>
TOP-RIGHT: <TapArea xcenter= "-2.0" ycenter="11.5"><MacroRefEvent macro_ref="  Q  "/></TapArea>
BOT-RIGHT: <TapArea xcenter= "-2.0" ycenter= "0.0"><MacroRefEvent macro_ref="  Q  "/></TapArea>
BOT-LEFT : <TapArea xcenter="-15.8" ycenter="-0.5"><MacroRefEvent macro_ref="  Q  "/></TapArea>
PAD-RIGHT: <TapArea xcenter=  "2.0" ycenter= "0.0"><MacroRefEvent macro_ref="  Q  "/></TapArea>
SMALL    : <TapArea xradius=  "0.5"               ><MacroRefEvent macro_ref="  Q  "/></TapArea>
BIG      : <TapArea xradius=  "1.5" xcenter= "6.0"><MacroRefEvent macro_ref="  Q  "/></TapArea> 

Key definitions

The TSLP doesn't really have keys; it just has tap areas. This is logical when you realize that the keyboard is really just a flat sensor area without any fixed borders. Any point on the surface can be a "key area" for anything. In fact, there doesn't need to be the number of tap areas that the printed surface indicates. You might modify the configuration so that there are only ten areas, or two hundred (depends on the size of the internal memory, a Touchstream ST allows appr. 28 additional areas), if you like! It's just a matter of training yourself to use a configuration that is different from the printed surface, but of course it's most practical if the surface printing corresponds to the actual configuration. It's a matter of personal preferences.

TapArea

Each TapArea defines a "key" on the surface.

Nesting: The TapArea tag must be inside the MTS_config tag.

xcenter
The x coordinate for the center of the tap area. Valid values are x = [-16.5;16.5].
ycenter
The y coordinate for the center of the tap area. Valid values are y = [-0.5;12.0].
xradius
The radius for the tap area. The tap area has an elliptical shape and xradius defines the horizontal radius.
yradius
The radius for the tap area. Use yradius to make the tap area a nonstandard elliptical size.
keymatrix_version
The relevant Hardware identifier (i.e. 34=TouchStream). It is used by the editor to actually apply parameters that correspond to the detected AND selected hardware.
surface_version
The hardware version of the sensor array. The detected hardware will be considered for relevance. Valid values are:
  • surface_version="0" (DFU)
  • surface_version="7" (iGesturePad)
  • surface_version="8" (iGestureNumPad)
  • surface_version="9" (iGestureRetro)
  • surface_version="10" (iGestureMini)
  • surface_version="11" (TS ST/LP)
  • surface_version="12" (TS Ultrathin)
  • surface_version="13" (TS MacNTouch)
  • surface_version="17" (TS Tablet)
lib
The name of the configuration-file where a tag is defined.
inHomeRow
The value true makes this area appear in bold in the MyGestureEditor?. Valid values are true, false.
fingerColumn
  unknown    Valid values are thumb, index, middle, fourth, pinky.
isFixed
  unknown    Valid values are true, false.
isRectangular
Valid values are true, false.
  • When true, width and height attributes may define the area.
        <TapArea xcenter="-15.7" ycenter="4.25" width="2.5" height="2.0" isRectangular="true">
            <MacroRefEvent macro_ref="Left Ctrl"/>
        </TapArea>
    
  • When false (or absent):
    • radius attributes may define the area.
      These keys are the only one defined with the radius attribute in the TS factory lib file FW_straight_stealth_keys.xml:
          <TapArea xcenter="14.15" ycenter="12.05" radius=".9" >
              <MacroRefEvent macro_ref="  _-  "/>
          </TapArea>
          <TapArea xcenter="15.80" ycenter="12.00" radius=".9">
              <MacroRefEvent macro_ref="  +=  "/>
          </TapArea>
      
    • xradius attributes may define the area.
      These keys are the only one defined with the xradius attribute in the TS factory lib file FW_straight_stealth_keys.xml:
          <TapArea xcenter="4.13" ycenter="2.91" xradius="1.30" inHomeRow="true" fingerColumn="thumb">
              <MacroRefEvent macro_ref="  Space  "/>
          </TapArea>
          <TapArea xcenter="1.70" ycenter="0.60" xradius="1.10" fingerColumn="thumb">
              <MacroRefEvent macro_ref="  Enter (Thumb)  "/>
          </TapArea>
          <TapArea xcenter="-4.03" ycenter="2.91" xradius="1.30" inHomeRow="true" fingerColumn="thumb">
              <MacroRefEvent macro_ref="  BackSpace  "/>
          </TapArea>
          <TapArea xcenter="-1.60" ycenter="0.60" xradius="1.10" fingerColumn="thumb" >
              <MacroRefEvent macro_ref="  Delete  "/>
          </TapArea>
          <TapArea xcenter="-15.0" ycenter="11.84" xradius="1.05" isFixed="true">
              <MacroRefEvent macro_ref="  Escape  "/>
          </TapArea>
          <TapArea xcenter="-14.8" ycenter="10.0" xradius="1.1">
              <MacroRefEvent macro_ref="  Tab  "/>
          </TapArea>
          <TapArea xcenter="-15.75" ycenter="8.27" xradius="0.85" isFixed="true">
              <MacroRefEvent macro_ref="  Caps Lock  "/>
          </TapArea>
          <TapArea xcenter="-14.2" ycenter="8.2" xradius="0.7" >
              <MacroRefEvent macro_ref="  ~`  "/>
          </TapArea>
          <TapArea xcenter="-15.7" ycenter="6.3" xradius="1.0" >
              <MacroRefEvent macro_ref="  Left Shift (Outer)  "/>
          </TapArea>
          <TapArea xcenter="-13.7" ycenter="6.3" xradius="1.0" layoutContext="US101 US101AltGrZones">
              <MacroRefEvent macro_ref="  Left Shift  "/>
          </TapArea>
          <TapArea xcenter="-13.7" ycenter="6.3" xradius="1.0" layoutContext="INTERNATIONAL102">
              <MacroRefEvent macro_ref="  |\ (Non-US)  "/>
          </TapArea>
      
      ALERT! what are the differences between radius and xradius ?   unknown   

Sample:

<TapArea xcenter="-12.16" ycenter="10.50" keymatrix_version="34" surface_version="11" lib="user">
    </TapArea>

MacroRefEvent

The MacroRefEvent defines what the key does.

Nesting: The MacroRefEvent tag must be inside a TapArea tag.

macro_ref
This value must exactly match a macro_name attribute in an EventMacro tag in the MacroLibrary tag, or it must match a name in one of the included libraries (such as FW_main ).

Sample:

<TapArea xcenter="-12.16" ycenter="10.50" keymatrix_version="34" surface_version="11" lib="user">
        <MacroRefEvent macro_ref="  1  " />
    </TapArea>

lib

The name of the configuration-file where a tag is defined.
  • When you change a tag attribute or one of its composing tags/elements with MyGestureEditor?, all modified tags get a lib="user" attribute set in your customization file.
  • This file will be the last loaded by the editor so that your changes will override any factory-default value as well as those from previously loaded library. The top-level MTS_config tag of your configuration file is associated with this implied library-name.
  • When a tag has this lib=user attribute it is displayed with a green background in the editor tree. This is how you can easily locate you changes.
  • When you make it a library, the background turns to yellow. This means that a modification makes the tag be different from the default assumed value and that it comes from a library-type configuration file. The top-level MTS_config tag of these files is associated with a lib attribute other than the default. Its name is the name of the file you export. ...see notes on library dependencies (pending)
  • The library importer looks for libraries in these directories, in this order:
    • ~/MyGestures/
    • ~/
    • FingerWorks/user_config/
    • FingerWorks/app_config/
    • ...and the last same-tag-entry wins!

Sample:

lib="mylibfilename"

Gesture definitions

Some of us know the situation, you have configured your Touchstream with the editor, hand size adjustment inclusive, but some gestures seem to be troublesome nevertheless. There are different ways to change the Touchstream behaviour in this regard.

ArrangementTemplate

The ArrangementTemplate defines the arrangement of the fingertips in a fingertips combination.

Nesting: The ArrangementTemplate tag must be inside the MacroLibrary? tag.

The hand size value influences all fingertips combinations equally. If you want to change the setting of a certain combination (the values for the spread version of a compact combination for instance are often overdone) independent of the others you have to change the appropriate ArrangementTemplate? tag from the FW_parameter_macros.xml file.

To modify such a template, draw the desired fingertips combination on a piece of paper, measure the coordinates, use one fingertip as reference point and change all coordinates of the tag accordingly (take into account that a hand size setting different from M [corresponds to a number value of 100] will affect these values, for an accurate calculation use the hand_size value of your customization file).

Sample:

        <ArrangementTemplate macro_name="3F Spread" best_fingers="SMRP" icon_name="3FS.gif">
            <TemplatePoint X="-4.0" Y="-0.7"/>
            <TemplatePoint X="0.4" Y="0.9"/>
            <TemplatePoint X="3.6" Y="-0.2"/>
        </ArrangementTemplate>

Macro definitions

MacroLibrary

The MacroLibrary holds all the macro definitions.

Nesting: The MacroLibrary tag must be inside the MTS_config tag.

The MacroLibrary tag has no attributes.

Sample:

<MacroLibrary>
</MacroLibrary>

EventMacro

The EventMacro defines what the key does.

Nesting: The EventMacro tag must be inside a MacroRefEvent tag.

macro_name
This is the internal reference name of the macro. It is used by the MacroRefEvent tag.
description
This value is displayed on the TapArea in the MyGestureEditor?.
lib
The name of the configuration-file where a tag is defined.
user_selectable
When value is false, you can't delete this EventMacro using the MyGestureEditor?. If true, this EventMacro can be deleted using the MyGestureEditor?.

Sample:

        <EventMacro macro_name="  P  " description="PROD" lib="user" user_selectable="false">
        </EventMacro>

KeyEvent

The KeyEvent defines what the key does.

Nesting: The KeyEvent tag must be inside a EventMacro tag.

keyCode
This value must be one of the values in the Fingerworks CharacterSet. It refers to what keyboard value is sent to the computer.
driverContext
Valid values are qwerty, dvorak, qwerak, qwack. (qwack is called _old qwerak in the MultiTouchUtilities but the XML calls it qwack.)
layoutContext
The mode in which the tag applies.
  • Two mode categories are to be considered:
    • The selected keyboard layout selected by the UserOptions tag
    • The transient working mode that may be triggered by some modifier chord.
      These value are used by TS factory lib files:
    • User selected keyboard emulation:
      • "INTERNATIONAL102"
      • "INTERNATIONAL103"
      • "US101"
      • "US101AltGrZones"
    • Transient working mode (may be activated by some state-switch or by some gesture from the other hand):
      • "NumLock"
      • "PunctPadOn"
      • "ScrollLock"
      • "SymbolPadOn"

Sample:

            <KeyEvent keyCode="P" driverContext=" qwerty" />
            <KeyEvent keyCode="L" driverContext=" dvorak qwack" />
            <KeyEvent keyCode="K" driverContext=" qwerak" />
            <KeyEvent keyCode="Numpad-" layoutContext=" numlock" />
            <KeyEvent keyCode="]" layoutContext=" punctpadon" />

TextMacro

The TextMacro defines what the key does.

Nesting: The TextMacro tag must be inside the MacroLibrary tag.

text_string
The value is the output that is generated. If the text has line breaks, the attribute text_string is omitted and a different specification is used. See notes below.
macro_name
This is the internal reference name of the macro. It is used by the MacroRefEvent tag.
tree_folder
Defines where in the MyGetureEditor this text macro is listed.
lib
The name of the configuration-file where a tag is defined.

Notes on text_string: If the text has line breaks, then the attribute text_string is omitted. Instead, the value is defined by a sub-tag named CDATA. In the sample below, the macro_name="remind" has a text string containing two line breaks.

Sample:

        <TextMacro text_string="interface" macro_name="if" tree_folder="Text Strings" lib="user" />
        <TextMacro macro_name="remind" tree_folder="Text Strings" lib="user">
            <![CDATA[Kindly be reminded that we have not yet heard your comments on the below.

Looking forward to your reply,]]>
        </TextMacro>

ChordTemplate

A collection of ChordTemplate tags defines the contents of the Hand (Chord) Tree(s) to the left of MyGestureEditor?. This is a sample of the 98 tags defined in the TS factory lib file FW_chord_macros.xml.
  • Point & Click
  • Left and Right Click/Drag
  • Middle+Right Drag
  • Maya Zoom/Rotate
  • Pan/Zoom/Rotate
  • PgUp/PgDn & Home/End
  • Window Manipulation
  • Desktop Switching (Spread)
  • Shift Chord (L4F)
  • Shift Chord (R4F)
  • ...

Nesting: The ChordTemplate tag must be inside the MTS_config tag.

macro_name
This is the internal reference name of the macro. It is used by the MacroRefEvent tag.
lib
The name of the configuration-file where a tag is defined.
speed_param_ref
Command gestures Motion Speed/Sensitivity, one of the pre-set sensitivity categories.
Taken from the factory lib XML file FW_chord_macros.xml:
  • These are used for common gestures:
    • Palm Gesture Sensitivity 1.0 [ Medium Accell]
    • Extra Coarse Command Sensitivity 1.5 [ Medium Accell]
    • Coarse Command Sensitivity 2.0 [ Medium Accell]
    • Medium-Slow Command Sensitivity 2.5 [ High Accell]
    • Medium Command-Gesture Sensitivity 0.5 [Very High Accell]
    • Medium-Fine Command Sensitivity 3.5 [ High Accell]
    • Fine Command Sensitivity 4.0 [ High Accell]
    • Text Pointing Sensitivity 5.0 [ High Accell]
    • Fast Text Pointing Sensitivity 6.5 [ Medium Accell]
    • Text Scroll Sensitivity 8.0 [ Medium Accell]
  • These seem to be used for specific gestures:
    • Game Arrow Sensitivity 10.0 [Very High Accell]
    • Super Arrow Sensitivity 13.0 [ High Accell]
    • Game Pointing Speed 140.0 [Medium Accell]
    • Hand Nav Speed 250.5 [High Accell]
    • Mouse Dragging Speed 115.0 [High Accell]
    • Mouse Pointing Speed 130.0 [Low Accell]
    • Scroll Speed 35.0 [Very High Accell]
    • Discrete Zoom Speed 5.0 [Medium Accell]
  • ALERT! Some details on each of these would REALLY be appreciated! ...  unknown   

GestureCategories
  unknown   
list
  unknown   

Slide
  unknown   
macro_name
This is the internal reference name of the macro. It is used by the MacroRefEvent tag.
axes_template_ref
  unknown   
oneShot
Valid values are true, false.
  • If false, a gesture will trigger an action repeatedly until the gesture ends, like Shift or Tab.
  • If true, a gesture will only fire once, regardless how long the gesture is made, like Escape.

Sample:

        <ChordTemplate macro_name="File Operations" lib="user" speed_param_ref="Medium Command-Gesture Sensitivity">
            <GestureCategories list=" file_op" />
            <Slide macro_name="Expand Hand  {in File Operations}" axes_template_ref="Expand Hand" oneShot="true" speed_param_ref="Extra Coarse Command Sensitivity">
                <MacroRefEvent macro_ref="New" />
            </Slide>
        </ChordTemplate>

UserOptions

This defines which device settings are active.

Nesting: The UserOptions tag must be inside the MTS_config tag.

driverContext
  unknown   
layoutContext
The mode in which the tag applies.
These value are used by TS factory lib files:
  • User selected keyboard emulation:
    • "INTERNATIONAL102"
    • "INTERNATIONAL103"
    • "US101"
    • "US101AltGrZones"
thumb_can_click
  unknown   
european_50Hz_filter
Configures the internal noise filtering to work with your local power frequency. Valid values are true, false. Turn on the 50Hz filter if you live in Europe, leave it off if you live in USA+Japan. I don't know about other regions of the world.
thumb_triggers_button
  unknown   
pinky_triggers_button
  unknown   
hand_size
A size factor to adjust the recognition of chords compared to your hand size. Value 100 is default (Medium).

EnabledRighthandGestures
  unknown   
EnabledLefthandGestures
  unknown   
EnabledBimanualGestures
  unknown   
list
  unknown   

Sample:

    <UserOptions driverContext=" win dvorak" layoutContext=" international102" thumb_can_click="true" european_50Hz_filter="true" thumb_triggers_button="3" pinky_triggers_button="2" hand_size="94">
        <EnabledRighthandGestures list=" scroll_mouse clipboard_op text_styles file_op window_op text_nav tap_range_chord weird_chords search_edit" />
        <EnabledLefthandGestures list=" clipboard_op text_styles text_nav tap_range_chord weird_chords" />
        <EnabledBimanualGestures list=" hand_nav tap_range_chord weird_chords" />
    </UserOptions>

Sample:


Sample:


Sample:


Sample:


built-in library files

FW_main.xml

The library mentioned in the customization file.
  • This top-level library is the one that loads all the others:
  • All theses factory libraries are located in the Java ARchive file: C:/program files/FingerWorks/lib/FW_defaults.jar
  • This file has been placed there by the setupfw160.exe installer.
Here is the actual contents of this file:
  • Note: (conditional) ...the detected hardware will be considered for relevance.
    <?xml version="1.0" encoding="UTF-8" ?> 
    <!DOCTYPE MTS_config (View Source for full doctype...)> 
    <MTS_config
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="file:///mtsConfig.xsd"
    copyright="Copyright (C) 1999-2003 FingerWorks, Inc. All Rights Reserved."
    lib="FW_main"
    MTS_config_version="1.6.0"
    min_firmware_version="1.4.6"
    >

    <!-- generic macro library includes -->
    <Include filename="FW_key_macros.xml" /> 
    <Include filename="FW_command_macros.xml" /> 
    <Include filename="FW_parameter_macros.xml" /> 
    <Include filename="FW_chord_macros.xml" /> 

    <!-- "winpad/digitalpad" product class (conditional) includes -->
    <Include filename="FW_winpad_chords.xml" /> 
    <Include filename="FW_igesturepad_chords.xml" /> 

    <!-- "numpad/retro" product class (conditional) includes -->
    <Include filename="FW_igesture_chords.xml" /> 
    <Include filename="FW_igesture_numpadkeys.xml" /> 
    <Include filename="FW_DCA50_keys.xml" /> 
    <Include filename="FW_DCA50_options.xml" /> 

    <!-- "mini" product class (conditional) includes -->
    <Include filename="FW_mini_chords.xml" /> 
    <Include filename="FW_mini_qwertykeys.xml" /> 

    <!-- "stealth" & "ultrathin" product class (conditional) includes -->
    <Include filename="FW_stealth_chords.xml" /> 
    <Include filename="FW_mirror_stealth_keys.xml" /> 
    <Include filename="FW_straight_stealth_keys.xml" /> 
    <Include filename="FW_slanted_stealth_keys.xml" /> 
    <Include filename="FW_ultrathin_keys.xml" /> 
    <Include filename="FW_macntouch_keys.xml" /> 
    <Include filename="FW_macntouch_options.xml" /> 

    </MTS_config>

Attached files


to top

I Attachment sort Action Size Date Who Comment
pixelmapofpadareas.gif manage 71.4 K 22 Aug 2005 - 10:24 TorbenGB Ivanw's 'move your Q'.
z_sample_by_rows.xml manage 38.4 K 22 Aug 2005 - 13:47 TorbenGB Defining each key, sorted by rows.
fitb.gif manage 1.2 K 23 Aug 2005 - 11:06 TorbenGB FITB = Fill In the Blanks
Fingerworkscustomizations20050812.xml manage 26.0 K 25 Aug 2005 - 07:52 TorbenGB TorbenGB's current customizations.
Fingerworkscustomizations0Factory.xml manage 0.7 K 25 Aug 2005 - 07:54 TorbenGB TSLP factory settings.
FITB.gif manage 1.2 K 13 Mar 2009 - 11:04 TWikiGuest  
MyGestures_custom_ivanw.zip manage 281.8 K 13 Mar 2009 - 12:36 IvanWellesz  

You are here: Main > XmlManual

to top

-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- © 2017 All material on this website is the property of the contributing authors.
Copyright Notice - PrivacyPolicy - TermsOfService - Ideas, requests, problems regarding The Fingerfans Community? Send feedback.