Hints for Numeric Parameters with Other Constraints

The following hints are for INT16, INT16_ARRAY, INT32, INT32_ARRAY, FLOAT, and FLOAT_ARRAY parameters and arrays with constraints other than choices. Most hints have specific restrictions. Details for each hint are provided below.

Widget Name

Value

Description

WIDGET_SLIDER_HORIZONTAL

3

Displays a horizontal slider control. This is the default control for range-bounded integer and floating point parameters when they are not used in an array

WIDGET_SLIDER_VERTICAL

4

Displays a vertical slider control. This is the default control for range-bounded integer and floating point array parameters

WIDGET_SPINNER

5

Displays a spinner (entry field plus up/down arrows). This is the default for unbounded INT16 parameters. This cannot be used for unbounded FLOAT or INT32 parameters.

WIDGET_TEXTBOX

6

Displays a numeric entry field. This is the default for unbounded FLOAT and INT32 parameters.

WIDGET_IP_ADDRESS

14

Displays an IP Address entry field.
Only works with unconstrained INT32 parameters.

WIDGET_PROGRESS_BAR

17

Displays a read-only progress bar control.

WIDGET_AUDIO_METER

19

Displays a read-only audio level meter control with green, yellow, and red markers.

WIDGET_TIMER

21

Displays a label that counts down from the parameter value to 0 when double-clicked.

WIDGET_COLOR_CHOOSER

23

Put a colour chooser as an element in the UI. Changes made to the colour chooser are instantly sent to the device.

Color values are INT32 values in ARGB format.

WIDGET_SLIDER_HORIZONTAL_NO_LABEL

24

Displays a horizontal slider control with no label

WIDGET_SLIDER_VERTICAL_NO_LABEL

25

Displays a vertical slider control with no label

WIDGET_VERTICAL_FADER

26

Displays a vertical slider that looks like a fader bar

WIDGET_TOUCH_WHEEL

27

Displays a touch wheel control

WIDGET_HEX_SPINNER

28

Displays a spinner (entry field plus up/down arrows). Display the value in Base 16.

WIDGET_ABSOLUTE_POSITIONER

29

Provides a 2-axis absolute positioning element. When used as an INT16, the 8 LSBs represent the X coordinate and the 8 MSBs represent the Y coordinate. When used as an INT32, the 16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.

A crosshair in a box can be dragged to the absolute position of the value in 2-D space.

WIDGET_ABSOLUTE_CROSSHAIR

30

Position a value in 2-D space. When used as an INT16, the 8 LSBs represent the X coordinate and the 8 MSBs represent the Y coordinate. When used as an INT32, the 16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.

A crosshair that snaps to the center when released makes changes in +/- X, +/- Y relative to the offset from the center.

WIDGET_JOY_STICK

34

Position a value in 2-D space. When used as an INT16, the 8 LSBs represent the X coordinate and the 8 MSBs represent the Y coordinate. When used as an INT32, the 16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.

Displays a joystick and modifies the X, Y values as the joystick is dragged north, south, east, and west of the center.

WIDGET_COLOR_CHOOSER_POPUP

33

Display a combo box control showing the ‘current’ colour. On click, show the colour chooser. If “Live” is togged on, update the parameter value immediately. If “Live” is toggled off, update the parameter value when the popup is closed.

Color values are INT32 values in ARGB format.

WIDGET_GRAPH

256

Displays a plot graph of a parameter’s value over time.

WIDGET_SLIDER_HORIZONTAL (3)

Horizontal sliders are the default widgets used for range-bounded integer and floating point numbers when they are not used in an array. Sliders are not available for unbounded (null constraint) parameters.

Figure 27 shows an integer parameter with a range constraint bounded by (0, 200) and a WIDGET_SLIDER_HORIZONTAL hint.

Figure 27 - WIDGET_SLIDER_HORIZONTAL hint


 

WIDGET_SLIDER_VERTICAL (4)

Vertical sliders are the default widgets used for range-bounded integer and floating point numbers when they are used in an array. Sliders are not available for unbounded (null constraint) parameters.

The following is an integer parameter with a range constraint bounded by (0, 994) and a WIDGET_SLIDER_VERTICAL hint.

Figure 28 - WIDGET_SLIDER_VERTICAL hint

WIDGET_SLIDER_HORIZONTAL_NO_LABEL (24)

Figure 29 - WIDGET_SLIDER_HORIZONTAL_NO_LABEL hint

WIDGET_SLIDER_VERTICAL_NO_LABEL (25)

Figure 30 - WIDGET_SLIDER_HORIZONTAL_NO_LABEL hint

WIDGET_VERTICAL_FADER (26)

This hint specifies that the number shall be displayed as a vertical fader bar. The user can adjust the level by dragging the handle of the fader up or down.

Figure 31 - WIDGET_VERTICAL_FADER hint

WIDGET_TOUCH_WHEEL (27)

This hint specifies that the number shall be displayed as a touch wheel (or circular slider). The user grabs the dot on the circle and drags clockwise to increment the value and counter clockwise to decrement it. The touch wheel can be configured to take a specified number of revolutions to go from the minimum value to the maximum value and can also be configured to roll over to the minimum or maximum when the limits of the range are reached.

Figure 32 - WIDGET_TOUCH_WHEEL hint

WIDGET_PROGRESS_BAR (17)

This hint specifies that the number shall be displayed as a horizontal progress bar. For a range-bounded parameter, the progress bar displays the specified range (similar to a slider). For an unbounded parameter, the progress bar displays from 0 to 100%.

Figure 33 - WIDGET_PROGRESS_BAR hint

WIDGET_SPINNER (5)

Spinner widgets provide a compact way to navigate a bounded integer or float parameter. Spinner widgets are the default widgets used for unbounded int16 parameters. The spinner widget cannot be used with an unbounded floating point or int32 parameter.

Figure 34 - WIDGET_SPINNER hint

Notes           The range of the parameter: abs(max – min) x precision cannot exceed the maximum size of a signed integer for sliders and spinners.

To aid in touch screen environments, clicking and dragging a spinner up/down will increase/decrease its value.

WIDGET_TEXTBOX (6)

This hint specifies that a simple text entry field should be used for a number. The information entered into the text field is forced to conform to the constraints provided by the parameter. This is the default widget used for unbounded floating point parameters.

Figure 35 - WIDGET_TEXTBOX hint

WIDGET_IP_ADDRESS (14)

Displays an IPv4 Address format for a 32-bit integer. Only works with unbounded INT32 parameters.

Figure 36 - WIDGET_IP_ADDRESS hint

WIDGET_AUDIO_METER (19)

This hint specifies that the number shall be displayed as a vertical audio meter. The number of red/yellow/green segments is fixed.

Figure 37 - WIDGET_AUDIO_METER hint

WIDGET_TIMER (21)

This hint applies only to integer parameters with RANGE_STEP_CONSTAINT constraints. The parameter is displayed as a label and counts down if minVal < 0 or up if minVal >= 0. Negative numbers are not displayed. The step size is used to specify the number of ticks-per-second to use and must be a number between 1 and 1000.

When the maximum or minimum values are reached, the timer will stop counting.

To initialize the counter to a specific value but not have it start counting:

·         If the minimum value is negative and the parameter value is positive, the timer will display absolute(min) –value but will not count.

·         If the minimum value is positive and the parameter value is negative, the timer will display absolute(value) but will not count.

The timer can be reset or synchronized by sending a REPORT_PARAM message with the new parameter value (typically “1”).

Examples:

·         min=-600, max=0, step=1 (count from 10:00 to 0:00 showing each second).

·         min=0, max=600, step=1 (count from 0:00 to 10:00 showing each second)

·         min=0, max=1000,step=1000 (count from 0:00:000 to 0:01:000 showing each millisecond)

Figure 29 shows an INT_32 parameter with a WIDGET_TIMER hint, a precision of 1000, and a value of 13794088.

Figure 38 - WIDGET_TIMER hint

WIDGET_HEX_SPINNER (28)

Displays a spinner (entry field plus up/down arrows). Display the value in Base 16.

Figure 39 - WIDGET_HEX_SPINNER hint

Notes           Due to the lack of unsigned data types in OGP, hex spinners do not function properly in the following circumstances:
- An INT16 parameter with any values in the range of 0x8000 – 0xFFFF
- An INT32 parameter with any values in the range of 0x80000000 – 0xFFFFFFFF
- To allow a spinner to function in the range from 0x0000 – 0xFFFF, it is recommended that an INT32 parameter be used.

WIDGET_ABSOLUTE_POSITIONER (29)

Position a value in 2-D space.

·         When used as an INT16, the 8 LSBs represent the X coordinate and the 8 MSBs represent the Y coordinate.

·         When used as an INT32, the 16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.

A crosshair in a box is dragged to the absolute position of the value in 2-D space. The ratio of width to height is the ratio of xmax-xmin to ymax-ymin with the assumption that the screen pixels are square. Values are updated and sent to the device as the crosshair is dragged.

Figure 40 - WIDGET_ABSOLUTE_POSITIONER hint

WIDGET_CROSSHAIR (30)

Position a value in 2-D space.

·         When used as an INT16, the 8 LSBs represent the X coordinate and the 8 MSBs represent the Y coordinate.

·         When used as an INT32, the 16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.

A crosshair that snaps to the center when released makes changes in +/- X, +/- Y relative to the offset from the center. The ratio of width to height is the ratio of xmax-xmin to ymax-ymin. Values are updated and sent to the device as the crosshair is dragged.

Figure 41 - WIDGET_CROSSHAIR hint

WIDGET_JOY_STICK(34)

Position a value in 2-D space.

·         When used as an INT16, the 8 LSBs represent the X coordinate and the 8 MSBs represent the Y coordinate.

·         When used as an INT32, the 16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.

Displays a joystick and modifies the X,Y values as the joystick is dragged north, south, east, and west of the center.

Figure 42 - WIDGET_JOY_STICK hint

WIDGET_COLOR_CHOOSER(23)

Display a color chooser as an element in the UI. Changes made to the color chooser are immediately sent to the device. Note that the color chooser provides control for Hue, Saturation, Lightness, but color values are INT32 values in ARGB format.

Figure 43 - WIDGET_COLOR_CHOOSER hint

WIDGET_COLOR_CHOOSER_POPUP(33)

Display a combo box control showing the ‘current’ color. On click, show the color chooser.

·         If “Live” is togged on, update the parameter value immediately.

·         If “Live” is toggled off, update the parameter value when the popup is closed.

Color values are INT32 values in ARGB format.

Figure 44 - WIDGET_COLOR_CHOOSER hint

 

WIDGET_GRAPH (256)

The graph widget provides a plot graph which tracks the value of a numeric parameter over time.

Figure 45 - WIDGET_GRAPH hint

A parameter utilizing a WIDGET_GRAPH widget may also specify additional configuration parameters in the config object of the parameter.

Properties

Property

Type

Default

Description

w.time

Integer

 

Sets the timescale of the plot. If set to 0, the timescale will adapt to display entire change history.

w.grid

String

 

Sets the color of the gridlines

w.plotfg

String

 

Sets the color of the plot foreground

w.plotbg

String

 

Sets the color of the plot background

w.hidelegend

Boolean

 

true – Legend is not shown

false – Legend is shown

w.hidex

Boolean

 

true – X-axis scale is not shown

false – X-axis scale is shown

w.hidey

Boolean

 

true – Y-axis scale is not shown

false – Y-axis scale is shown

w.autoadvance

Booelan

 

true – graph will auto-update every 1 second

false – graph will only update upon parameter change.