User input¶
The view elements on this page additionally accept the attributes common to all view elements.
View-Element: edit¶
The edit element displays an edit box, which takes data from the user and writes it to a buffer. The output is defined by a simple output tag within the value block and needs to be a data-container.
<edit signed="BOOLEAN" decimal="BOOLEAN" min="FLOAT" max="FLOAT" unit="STRING"
factor="FLOAT" default="FLOAT">
<output>TEXT</output>
</edit>
Attributes
- signed
- If set to false the user may not enter negative numbers.
- optional, boolean, default:
true - decimal
- If set to false the user may not enter decimal (i.e. non-integer) numbers.
- optional, boolean, default:
true - min
- The minimum value allowed. Disable by not setting this attribute. Available from phyphox file format 1.1 (phyphox 1.0.2).
- added in 1.1 optional, float, default:
-Infinity - max
- The maximum value allowed. Disable by not setting this attribute. Available from phyphox file format 1.1 (phyphox 1.0.2).
- added in 1.1 optional, float, default:
Infinity - unit
- A unit to be displayed after the value
- optional, translatable
- factor
- A factor to be applied to the value before displaying it. This is usually used for unit conversion. Example: The data is in meters, but should be displayed in cm. The factor would be 100
- optional, float, default:
1.0 - default
- The default value of the edit box. The experiment will start with this value.
- Applied whenever the buffer is EMPTY, not only once at load: when the experiment is opened, after the data is cleared, and at the start of each analysis cycle. Without the last two an experiment loses the setting the moment anything empties the buffer - a clear, or an analysis input without keep - and only gets it back if that element's own view happens to be on screen. A value the user has set is not overwritten while it is in the buffer; CLEARING IT RESTORES THE DEFAULT, even though the control was showing something else, because clearing is how a user deliberately returns an experiment to its starting state. An author who wants a setting to survive that says so with clearGroup on the data container, which is what it is for. A NaN at the end of the buffer is replaced by the default as well: an input control cannot show NaN and the user could never enter it, so the buffer would hold something the control does not. The default is written as it stands, never clamped to the element's range - a default is deliberate. Replacing a NaN is not user input: it came from an analysis write, and an analysis with onUserInput must not re-run on its own output.
- optional, float, default:
0.0
Text content: Name of the data container.
View-Element: button¶added in 1.3
The button element displays a simple button, which interacts with the buffers outside the analysis cycle. Whenever the user presses the button, the last value from each input (which may be value types or data-containers) is written to each output (the first input is written to the first output, the second to the second and so on). Note that this does not happen at a certain point during analysis, but between analysis cycles, independent of when the user pushes the button.
Since version 1.4 (phyphox 1.0.6) you may define empty inputs (type="empty"), effectively making it possible to clear a buffer when pressing the button.
Since version 1.8 (phyphox 1.1.3), in addition to defining input and output buffers (or, usually, as an alternative), you can set a trigger tag defining an id. This triggers matching processes with the same id, such as a network connection.
Since version 1.19 (phyphox 1.2.0) you can additionally define map tags that work similarly to the map function of the value element. Each map tag defines a minimum and/or maximum value and an associated text. In contrast to the value element, the button uses an attribute dynamicLabel to define a data-container that is used with these map values. Phyphox sequentially goes through the map tags in the order they have been defined, and for the first one for which the value in the buffer given in dynamicLabel falls within min/max of the map tag, the text in the tag is used as the label for the button. If no map tag matches, then the normal label from the label tag is used.
<button dynamicLabel="STRING">
<input>TEXT</input>
<output>TEXT</output>
<map>TEXT</map>
<trigger>TEXT</trigger>
</button>
Attributes
- dynamicLabel
- A buffer (data-container) that controls the label of the button. The last value in this buffer is compared to the map tags in the button element and the first matching map tag determines the button's label.
- optional
Text content: Name of a data container, or a literal number when type is value.
Attributes
- type
- Whether the text names a data container, is a literal value, or stands for an empty buffer.
- optional, one of
buffer,value,empty, default:buffer
Text content: Name of the data container.
Text content: The id to trigger.
Text content: The label to show when the value falls in this range.
Attributes
- min
- Lower bound of the range, inclusive.
- optional, float, default:
-Infinity - max
- Upper bound of the range, inclusive.
- optional, float, default:
Infinity
View-Element: toggle¶added in 1.19
The toggle element displays a simple toggle (or a checkbox in the remote control interface), which allows the user to turn something off or on. The output buffer receives a 0 for off and a 1 for on. If the buffer is changed externally, a 0 is always interpreted as off while any other value is displayed as on.
Attributes
- default
- The value with which the associated buffer should start.
- Applied whenever the buffer is EMPTY, not only once at load: when the experiment is opened, after the data is cleared, and at the start of each analysis cycle. Without the last two an experiment loses the setting the moment anything empties the buffer - a clear, or an analysis input without keep - and only gets it back if that element's own view happens to be on screen. A value the user has set is not overwritten while it is in the buffer; CLEARING IT RESTORES THE DEFAULT, even though the control was showing something else, because clearing is how a user deliberately returns an experiment to its starting state. An author who wants a setting to survive that says so with clearGroup on the data container, which is what it is for. A NaN at the end of the buffer is replaced by the default as well: an input control cannot show NaN and the user could never enter it, so the buffer would hold something the control does not. The default is written as it stands, never clamped to the element's range - a default is deliberate. Replacing a NaN is not user input: it came from an analysis write, and an analysis with onUserInput must not re-run on its own output.
- optional, float, default:
0.0
Text content: Name of the data container.
View-Element: slider¶added in 1.19
This is a view element used to input values from a limited range determined by a minimum and maximum value as well as a step size. The current value is also shown separately. With type="range" the slider can be used as a range slider with two handles, allowing the user to select a range by picking a lower and an upper value.
<slider minValue="FLOAT" maxValue="FLOAT" stepSize="FLOAT" default="FLOAT"
precision="INTEGER" type="STRING" showValue="BOOLEAN" color="COLOR">
<output value="STRING">TEXT</output>
</slider>
Attributes
- minValue
- Value for a handle at the lower end of the slider.
- optional, float, default:
0.0 - maxValue
- Value for a handle at the upper end of the slider.
- optional, float, default:
1.0 - stepSize
- Determines the minimum distance between two values that can be selected with the slider. This is always relative to minValue, so a stepSize of 0.2 and a minValue of 0.1 will force the user to pick 0.1, 0.3, 0.5, etc.
- optional, float, default:
1.0 - default
- The value with which the associated buffer should start. (Does not work in range slider mode. Use the init property of the data containers instead.)
- Applied whenever the buffer is empty, as for the other input elements, and likewise when the buffer ends in NaN (see the remark on the edit element's default). In RANGE mode this attribute has no effect and the two buffers start from the containers' init property; where that is not given they start at the slider's own min and max, which is what the handles show - a slider displaying a range its buffers do not contain would leave any analysis reading them with no values at all.
- optional, float, default:
0.0 - precision
- The number of decimal places shown in the field with the current value
- optional, integer, default:
2 - type
- Can either be "normal" or "range". Normal is a slider representing a single value, while "range" is a range slider with two handles that allow picking a lower and an upper value.
- optional, one of
normal,range, default:normal - showValue
- Show a title and the current value above the slider. If turned off, the title is also hidden, making the slider very thin and compact.
- optional, boolean, default:
true - color
- Color of the slider.
- optional, color
Text content: Name of the data container.
Attributes
- value
- Which handle of a range slider this output follows. Omitted for a normal slider.
- optional, one of
lowerValue,upperValue
View-Element: dropdown¶added in 1.19
The dropdown view element gives the user a list of options, each of which is associated with a value. The user simply taps the dropdown box, picks an option and the associated value is written to the output buffer.
<dropdown default="FLOAT" color="COLOR">
<output>TEXT</output>
<map value="FLOAT">TEXT</map>
</dropdown>
Attributes
- default
- The value with which the associated buffer should start.
- Applied whenever the buffer is EMPTY, not only once at load: when the experiment is opened, after the data is cleared, and at the start of each analysis cycle. Without the last two an experiment loses the setting the moment anything empties the buffer - a clear, or an analysis input without keep - and only gets it back if that element's own view happens to be on screen. A value the user has set is not overwritten while it is in the buffer; CLEARING IT RESTORES THE DEFAULT, even though the control was showing something else, because clearing is how a user deliberately returns an experiment to its starting state. An author who wants a setting to survive that says so with clearGroup on the data container, which is what it is for. A NaN at the end of the buffer is replaced by the default as well: an input control cannot show NaN and the user could never enter it, so the buffer would hold something the control does not. The default is written as it stands, never clamped to the element's range - a default is deliberate. Replacing a NaN is not user input: it came from an analysis write, and an analysis with onUserInput must not re-run on its own output.
- optional, float, default:
0.0 - color
- Color of the menu.
- optional, color
Text content: Name of the data container.
Text content: The option text shown to the user. Translatable.
Attributes
- value
- Value written to the data container when this entry is chosen.
- optional, float, default:
0.0