A manipulation is an action the user can take by clicking on your object. (That is, the user “manipulates” your OBJ with the mouse.) Manipulations can only be used on cockpit objects!
Types of Manipulators
There are six types of manipulators supported in X-Plane 920 and later:
- None
- Panel Click
- Drag-Axis
- 2-d Drag
- Command
- Command-Axis
- Opaque
No Manipulation
Triangles are ignored when clicking. This is the default, and is usually used for anything that is not clickable. This manipulation does not require any CPU resources, so when possible, you want to leave your meshes non-manipulatable. This is the only legal manipulation for non-cockpit objects.
The none manipulation is set using either
ATTR_no_cockpit ATTR_manip_none
The none-type manipulation will show no tool tips, and uses the arrow (default) cursor.
Panel Click Manipulation
A click on the triangles is mapped through to the 2-d panel based on the panel texture’s mapping. This manipulation can only be specified for objects that are textured by the panel texture (or a panel texture region). Panel click manipulation is set using one of
ATTR_cockpit ATTR_cockpit_region <region number>
Panel click manipulations show the tooltips and cursors of the 2-d panel.
Drag-Axis Manipulation
As the user drags along an axis in 3-d object-space, a dataref value is increased or decreased. The length of the axis defines how much mouse travel (in meters of object space) is required to completely change the dataref across a range defined by a pair of parameters. The drag-axis manipulator takes the form:
ATTR_manip_drag_axis <cursor> <x> <y> <z> <value1> < value2> <dataref> <tooltip>
Here, x, y and z define the length and direction of the drag axis, and value1 and value2 define the range of values over which the manipulator runs. If the mouse is dragged beyond either of these limits, the manipulator is clamped: the value of the dataref will remain the same until the mouse is again dragged or clicked within range. The current value is retained after the mouse is released, and determines the position of the manipulator’s drag-axis relative to the next mouse click. For example, if a manipulator is currently set to a value midway between it’s minimum and maximum values, then the mouse will automatically find itself halfway along that manipulator’s drag-axis when next it clicks on it.
Drag-axis manipulation is subject to object animation. The orientation of the manipulator’s drag-axis relative to the animated mesh to which it is attached is the same each time the mouse is clicked on it. For example, if a drag-axis manipulator on an animated throttle lever has an axis perpendicular to the lever shaft when clicked in the ‘idle’ position, that axis will still be perpendicular to the lever shaft when clicked in the ‘open’ position. However, for the duration of any given drag, the orientation of the drag-axis relative to the aircraft remains constant. So if the drag-axis of the previously-described manipulator happens to be perfectly horizontal at the moment the mouse is clicked on it, it will remain perfectly horizontal and ‘locked-in’ until the mouse is released, even though the visible throttle lever has been animated to a new position. This behaviour is more intuitive in practice than it may appear on paper!
2-d Drag Manipulation
The 2-d drag manipulator effectively combines two manipulators into one, allowing two datarefs to be modified simultaneously by dragging the mouse along a pair of perpendicular axes. To minimise input ambiguity, the axes are defined in 2-d screen space, not object space, and their respective orientations are fixed. The first dataref is modified by dragging the mouse horizontally across the screen and the second by dragging vertically. This type of manipulator would typically be used to control a yoke or joystick and takes the form:
ATTR_manip_drag_xy <cursor> <x> <y> <ref1 value1> <ref1 value2> <ref2 value1> <ref2 value2> <dataref1> <dataref2> <tooltip>.
Here, x defines the distance the mouse must be dragged across the screen from left to right in order to modify the output of dataref1 from ref1 value1 to ref1 value2. Similarly, y defines the distance the mouse must be dragged up the screen in order to vary the output of dataref2 from ref2 value1 to ref2 value2.
In contrast to the drag-axis manipulator, the axis orientations of the 2-d drag manipulator are not subject to object animation. The x-axis is always horizontal and the y-axis is always vertical. However, the location of the manipulator’s click-region does follow any animation of it’s mesh.
The following example shows a 2-d drag manipulator configured to control a steering yoke. The x-axis controls roll (an 80-pixel drag), and the y-axis controls pitch (a 50-pixel drag). Note: since it is more intuitive to drag down rather than up the screen in order to increase pitch, the vertical axis has been assigned a negative value):
ATTR_manip_drag_xy four_arrows 80 -50 -1 1 -1 1 sim/cockpit2/controls/yoke_roll_ratio sim/cockpit2/controls/yoke_pitch_ratio I am a tooltip.
It is not obligatory for a 2-d drag manipulator to address two datarefs. A single dataref may be manipulated in 2-d screen-space by entering a value of 0 for each of the redundant numeric parameters and null for the dataref name of the unassigned axis.
Command Manipulation
A command manipulation invokes an X-Plane command when the mouse is clicked on it. The command continues to be invoked until the mouse is released. It takes the form:
ATTR_manip_command <cursor> <command> <tooltip>
Command-Axis Manipulation
Dragging along a specified object-space axis actuates one of a pair of commands, subject to the direction of the drag. The command continues to be invoked (CommandContinue phase) until such time as the mouse is either released or else dragged back along the axis to the neutral position. Dragging right through the neutral position to the opposite end of the axis invokes the second command. The neutral position is centred on the location of the original mouse click and occupies 40% of the overall length of the axis Typical applications would be nudge-wheels and three-position toggle switches. The command-axis manipulator takes the form:
ATTR_manip_command_axis <cursor> <x> <y> <z> <command1> <command2> <tooltip>
The x, y, and z parameters define the orientation and length in meters of the drag-axis. Dragging in the positive direction triggers command 1 and in the negative direction, command 2. The following example shows a command_axis manipulator configured as a pitch trim nudge-wheel/switch:
ATTR_manip_command_axis up_down 0.00 0.00 -0.01 sim/flight_controls/pitch_trim_down sim/flight_controls/pitch_trim_up I am also a tooltip.
The axis values in the above example would be appropriate for a standard-sized toggle switch mounted on a horizontal console panel. Dragging the mouse approximately 2mm towards the nose of the aircraft triggers pitch_trim_down, and dragging it 2mm towards the tail triggers pitch_trim_up (since the X-Plane acf z-axis runs positive nose to tail).
Opaque Manipulation
This sets the manipulation to ‘no-op’ (no operation). Unlike “none” manipulation, opaque manipulation “swallows” the mouse, preventing it from clicking on other manipulators that may lie behind it. It would typically be used to act as a safety-guard over a switch.
Dataref “Button” Manipulators
These manipulators change a dataref when the mouse is clicked or held, creating button-like functionality. There are five sub-flavors. The push-button, radio button, and toggle manipulators are meant to provide button-like behavior for a mesh. The delta and wrap manipulators are meant to be used to create invisible “hot spots” over a mesh.
Push-Button Manipulator
The push-button manipulator sets a dataref to a “down” value when the mouse is clicked, then back to an “up” value when the mouse button is released.
Radio Button Manipulator
The radio button manpiulator sets a dataref to a value each time it is clicked.
(It is considered to be a “radio button” because a set of these manipulators, sharing one dataref but using differing values, can create radio-button-like behavior.)
Toggle Manipulator
The toggle manipulator switches a dataref between one of two values each time it is clicked.
Delta Manipulator
The dataref is increased (or decreased) when the button is clicked (and/or held down). If the dataref exceeds its limit range, it is clamped to that limit.
Wrapping Manipulator
The dataref is increased (or decreased) when the button is clicked (and/or held down). If the dataref exceeds its limit range, it wraps around to the other end of the range.
Manipulator Properties
These properties apply to some or all of the manipulators except for:
- None and opaque manipulators (which have no real action).
- Panel manipulator (which gets its properties from the panel).
Cursor
All manipulators let you specify the cursor that appears when the mouse is over the manipulator. (The panel manipulator takes its cursor from the underlying panel.) The OBJ8 specification lists all possible cursor choices.
3-D Axis
The axis and command-axis manipulators allow a drag in 3-d; they require the specification of an axis.
- The axis is a 3-d axis, so it is specified as a length in X, Y, and Z (in meters).
- This axis is affected by animation; if the manipulator is inside a rotation, the axis will rotate.
- The axis manipulators imply an “increasing” and “decreasing” direction; the values specify the increasing direction.
EXAMPLE: for an axis of X = 1, Y = 1, Z = 0, as you drag to the upper right (in object coordinates) the dataref will increase.
The axis’s position in the 3-d cockpit is set based on the current value of the dataref when the user clicks. For example, if the dataref for the axis manipulator is the throttles and the throttles are at maximum value, the entire axis will be in the direction to decrease the throttles. If the throttles are at 50%, the mid-point of the axis will be at the click point. In other words, axis positioning is relative based on the dataref.
(For the command-axis, the axis center is always the anchor point.)
2-D Axis
The 2-d drag axis is a special case: it allows a drag in “screen space” – that is, the axes is always up-down and left-right no matter what the pilot head position. Thus the axes are lengths in pixels. A positive “x” means that a drag to the right increases the first dataref. A positive “y’ means a drag up increases the first dataref.
Datarefs and Values
For the axis and axis-2 manipulators, one or two datarefs is required, as well as low and high values. The low and high values “scale” the axis. For example, for a throttle, a low and high value of 0.0 and 1.0 would tell the manipulator what throttle values correspond with the end of the axis.
(In other words, the axis specifies the size in the 3-d cockpit of the drag, and the dataref values specify the size in terms of the actual dataref movement.)
Commands
A command can be specified for either the command manipulator (the command is invoked while the mouse button is held down) or the command-axis dataref (the command is invoked while the drag is to the left or right of the axis).
Tooltips
All manipulators let you specify a tooltip. When the mouse lingers over the manipulator region and the user enables “instrument explanations”, this tooltip will be shown. It provides a way to provide custom panel instructions. Tooltips may not have return characters. (For the panel manipulator, the tool tip is taken from the underlying 2-d manipulator.)
Setups For Typical Switches and Elements
Here are some typical setups for making 3-d animated switches and other cockpit parts.
Terms
- Rotary: any part with rotational movement.
- Momentary: any part that returns to its original position when released.
- 2-way,3-way,n-way, continuous: how many distinct positions a part can take. A dimmer is continuous; an on-off switch is 2-way.
Non-Momentary Parts
These parts retain their original position after being clicked.
2-way parts
Datarefs: use the “toggle” manipulator – the on and off values match the two possible values for the underlying dataref.
Command: if a “toggle” command (e.g. sim/flight_controls/landing_gear_toggle) exists, you can use a command manipulator. You cannot use a “set to X” command like sim/flight_controls/landing_gear_up.
N-way switch
Use the axis manipulator along the axis the user can drag. Important: to get “N”-way action, be sure the underlying dataref is of type “integer” so the switch “snaps” to each position.
N-way rotary
Use the 2-d axis manipulator, but only use the X axis. This will allow a horizontal drag to turn the rotary. To get “N”-way action, be sure the underlying dataref is of type “integer” so the switch “snaps” to each position.
Radio Buttons
Radio buttons can take on N positions, by having any one button pressed in. Set each button to have a manipulator of type “radio button”. All buttons should have the same datarefs but different values.
Continuous Switch
Use the axis manipulator along the axis the user can drag. The underlying dataref should be of type “float”.
Continuous Rotary
Use the 2-d axis manipulator, but only use the X axis. The dataref should be of type “float”.
Momentary Parts
These parts snap back when done.
2-way momentary
Dataref: use the “push button” manipulator with appropriate on and off dataref values. Command: if the action is a “hold-it-down” command (like sim/starters/engage_starter_1) you can use a command manipulator.
3-way momentary
Use the command-axis manipulator, with one command for each direction.