Tooltips
Tooltips are a work-in-progress usability enhancement. They provide a way for a cockpit to be partially self-documenting, when a user explores, and can also provide a positive confirmation of state or action, which is often lacking in 3D cockpit interactions due to absence of audio or haptic feedback. (Which is a fancy way of saying, switches don't click or feel to move).
A tooltip is specified via a set-tooltip command in a pick (or slider or knob) animation's <hovered> bindings group. The tooltip is configured at this time, especially content and an ID. The mouse-handling system then displays the tooltip at the correct time. This design allows us to show tooltips at configurable points, either the standard method - after the mouse is stationary for a period of time - or in response to other actions, such as mouse clicks/drags.
The tooltip-id is important to distinguish when the mouse moves over different scene objects (with potentially the same tooltip), or crosses between different objects without an intervening hit on an area with no tooltip assigned. In both cases, the ID is necessary to give correct updating.
Syntax
- Label is a printf-style format string (which need not contain expansions)
- Property is a property value to display
- Measure-text is a string used to size the tooltip, i.e the largest possible string. This configuration allows adjusting the tooltip font-size in the future without tooltip data changing (which would not be the case if an explicit width was specific). If the measure-text is omitted, the actual label text is used, which can cause minor adjustments to tooltip size as the property value changes.
- Mapping defines of a (growing) set of standard mappings of the property value
Mappings
- percent - maps a 0.0 ... 1.0 property to an integer percentage
- heading - maps a double or int value to a 0...359 heading/bearing
- arm-disarm, on-off, up-down, down-up, open-close and close-open - map a boolean value to a text string
- nasal, evaluates a Nasal script each time the property changes. The property value is available to the script as arg[0]
Use from Nasal
Tooltips can also be shown from Nasal scripts.
More info can be found in $FG_ROOT/Nasal/gui.nas.
Some examples:
#Show readme in a popup
gui.popupTip("readme");
#Show readme at position 10, 10
gui.popupTip("readme", nil, nil, {y: 10, x: 10});
#Show readme at position y=10, with 2 second delay
gui.popupTip("readme", 2, nil, {y: 10});
#Show readme, with 6 second delay
gui.popupTip("readme", 6);
#Show readme at position x=10, y at default position
gui.popupTip("readme", nil, nil, {x: 10});
#Show readme at position 10, 10, with 10 second delay
gui.popupTip("readme", 10, nil, {"y": 10, "x": 10});Tooltip-on-click
This mode shows the tooltip when the user interacts with a pickable animation. The result is they get positive confirmation of the new value of the control, during and after making a change. This helps with many controls where the panel text is illegible, or the control orientation is ambiguous - e.g. overhead panel switches with a tri-state, at a 'skewed' angle to the user. For knobs and sliders the feedback is useful in being able to quickly move to a precise value.
Other Uses
Once the basic system is setup, we can investigate using the mechanism to further improve in-cockpit learnability and usability. In particular, tooltips could potentially be shown via the tutorial system in a sticky mode, guiding the user to the location and meaning of a cockpit control which requires interaction.
Examples
Basic usage:
<?xml version="1.0" encoding="utf8"?>
<PropertyList>
<animation>
<type>slider</type>
<hovered>
<binding>
<command>set-tooltip</command>
<label>Mixture: %3d%%</label>
<measure-text>Mixture: 100%</measure-text>
<tooltip-id>mixture</tooltip-id>
<mapping>percent</mapping>
<property>controls/engines/engine[0]/mixture</property>
</binding>
</hovered>
</animation>
</PropertyList>
Heading mapping and numeric formatting:
<hovered>
<binding>
<command>set-tooltip</command>
<tooltip-id>heading-bug</tooltip-id>
<mapping>heading</mapping>
<label>Heading Bug: %3.0f</label>
<property>autopilot/settings/heading-bug-deg</property>
</binding>
</hovered>
Another example, showing a Nasal mapping function. Recall that arguments to a Nasal function are available through the predefined 'arg' variable, so 'arg[0]' gives the current property value.
<hovered>
<binding>
<command>set-tooltip</command>
<tooltip-id>kt70-func</tooltip-id>
<label>Transponder mode: %s</label>
<property>instrumentation/kt-70/inputs/knob-mode</property>
<mapping>nasal</mapping>
<script>
var modes = ['OFF', 'STANBY', 'GROUND', 'ON', 'ALTITUDE', 'TEST'];
return modes[arg[0]];
</script>
</binding>
</hovered>