Model Behaviors Inputs

MODEL BEHAVIORS INPUTS

As part of the Model Behaviors, you can use Input Events. While this is a complex system to use, and interactions can be implemented without them, it is recommended to use this system and add an Input Event for each interaction. To use an input you will be expected to incorporate one or more presets defined by the input event. These are most often created as one input event that has everything required in the form of a template which you can then extend from elsewhere in the code.

The following is an example of a simple input event template:

<InputEvent ID="BASE_INPUT_EVENT">
    <Presets>
        <Preset ID="#PRESET_ID#">
            <!-- here we'd define one preset with every field given a parameter -->
        </Preset>
    </Presets>
</InputEvent>
<InputEvent ID="My_InputEvent">
    <Presets>
        <Extend Target="BASE_INPUT_EVENT"/>
    </Presets>
</InputEvent>
<!-- defining a custom preset -->
<UseInputEvent ID="My_InputEvent">
    <PRESET_ID>My_InputEvent_Throttle</PRESET_ID>
    <!-- + all the parameters expected by BASE_INPUT_EVENT -->
</UseInputEvent>

The preset(s) created by the UseInputEvent statement will be assigned the current component as target. A target component is what define the scope of O and I variables in Reverse Polish Notation (RPN). To display the input event tooltip when hovering over a MouseRect, you will need to specify its ID in a TooltipEntry within the <Mouserect> definition.

Input Bindings

An important feature of Input Events is that they can be bound to Event IDs or even to each other. This means that you can use an Input Event to override a default key event behavior using your own code, or you can create aliases for different presets within your own behaviors, for example:

<Parameters>
    <Param Type="Float" RPN="True">p0 16384 / 1 + 2 /</Param>
</Parameters>
<Binding EventID="THROTTLE_SET">
    <Param RPN="True">p1</Param>
</Binding>
<Code>p0 (&gt;L:XMLVAR_My_Throttle_Position)</Code>

With this binding any call made to the key THROTTLE_SET will be intercepted and with it all the original parameters associated with it. These values are fed into the pN values as follows:

p	Description
`p0`	Raw device value (0 if key was not sent from a device)
`p1`	1st event parameter
`pN`	Nth event parameter

Now, if a checklist (for example) set the throttle using the following:

16384 (&gt;K:THROTTLE_SET)

Then the event will go to the input event preset instead of to the simulation. It will first go through the binding parameters, and then through the event parameters, before finally going through the simulation code:

<!-- 16384 (&gt;K:THROTTLE_SET) -->
16384 -> p1
<!-- <Param RPN="True">p1</Param> -->
p1 -> p0
<!-- <Param Type="Float" RPN="True">p0 16384 / 1 + 2 /</Param> -->
p0 16384 / 1 + 2 / -> p0 
<!-- Here XMLVAR_My_Throttle_Position will be equal to 1 -->
<!-- ((16384 / 16384) + 1) / 2 = 1 -->

Aliases

A binding created with an alias is most often used for giving one of the aliases to an input event with a specific parameter. For example, let's say we have a switch with two positions: ON and OFF. For this we will want to setup three alias to help us manipulate this switch from the checklist or the mouserect. These alias will be:

Switch Position	Code Description
On	Set the value 1 in XMLVAR_Value
Off	Set the value 0 in XMLVAR_Value
Toggle	Set the opposite value in XMLVAR_Value

The XML used for setting up these bindings would be as follows:

<Binding Alias="My_InputEventPreset_On">
    <Param>1</Param>
</Binding>
<Binding Alias="My_InputEventPreset_Off">
    <Param>0</Param>
</Binding>
<Binding Alias="My_InputEventPreset_Toggle">
    <Param RPN="True">(L:XMLVAR_Value) !</Param>
</Binding>

Once set up, you can use these aliases from a mouserect or a checklist as shown below:

(&gt;B:My_InputEventPreset_Toggle) <!-- Toggle the switch -->
(&gt;B:My_InputEventPreset_On)     <!-- Put the switch in the On position -->
(&gt;B:My_InputEventPreset_Off)    <!-- Put the switch in the Off position -->

Full Example

Now let's look at a more complete and complex example, which has some XML code for setting a value inside the input event <Preset> "Sound_COM1_Volume":

<Set>
    <Code>p0 0 max 100 min s0 (&gt;O:MyValue) l0 (&gt;K:COM1_VOLUME_SET)</Code>
    <Parameters>
        <Param Type="Float" RPN="True">p0 100 *</Param>
    </Parameters>
    <Bindings>
        <Binding EventID="COM1_VOLUME_SET">
            <Parameters>
                <Param RPN="True">p0 16384 /</Param>
                <!-- convert -16k/16k value to -1/1 value -->
            <Parameters>
        </Binding>
        <Binding Alias="SOUND_COM_1_Volume_Min">
            <Parameters>
                <Param>0</Param>
            <Parameters>
        </Binding>
        <Binding Alias="SOUND_COM_1_Volume_Max">
            <Parameters>
                <Param>1</Param>
            <Parameters>
        </Binding>
    </Bindings>
</Set>

In this example, a binding that overrides the behavior of an Event ID has been defined with the attribute "EventID":

<Binding EventID="COM1_VOLUME_SET">

This will now intercept the simulation event KEY_COM1_VOLUME_SET and instead use the <Code> within the <Set> element. Note that when setting the binding to an event ID, the Input Parameter p0 will usually be the raw input value - which would be between -16383 and 16384 for axis input and between 0 and 1 for a single input. The parameter p1 will also always have data, and in most cases this will be the same as the p0 data, however it may also have been pre-processed in some way before being pushed to the input event. The parameters p2 - p6 may also contain data, depending on the KEY_ event being checked.

NOTE: If you plan on using KEY_ events in checklists, and those events are intercepted by an input event preset, then you have to use the p1 value and above, as p0 will always return 0 when a checklist has generated the event.

In the above example we also generate a couple of aliases that can be used to override the Input Parameters, in this case outputting a value of 0 or 1 and ignoring the p0 input:

<Binding Alias="SOUND_COM_1_Volume_Min">
<Binding Alias="SOUND_COM_1_Volume_Max">

When creating an alias, it can be whatever you want as long as it is unique, but to avoid naming conflicts we advise that you always use the base Input Event preset name suffixed by a custom name describing what the alias does. For example, to set the COM1 volume to the minimum we created the alias "SOUND_COM_1_Volume_Min" for the preset "SOUND_COM_1_Volume", which means that in RPN calling:

(&gt;B:SOUND_COM_1_Volume_Min)

would do the same thing as:

0 (&gt;B:SOUND_COM_1_Volume_Set)