constraint
Defines the constraint of a parameter. The structure of this object depends upon the constrainttype of the parameter. Range constraints are specified as an attribute of a param tag; Choice, Alarm Table, and Struct constraints are specified using constraint tags as children to the param object.
Constraints may be defined within a param declaration, or defined globally and referenced by specific parameters.
Syntax
Constraints with inline constraint values:
<constraint constrainttype="ctype" constraint="cvalue" id="constraint-id" />
Constraints defined within a param tag with inline constraint values:
<param constrainttype="ctype" constraint="cvalue" param-attributes />
Choice and Alarm Constraints:
<param constrainttype="ctype" param-attributes>
<constraint key-attributes>cvalue</constraint>
<constraint key-attributes>cvalue</constraint>
. . .
</param>
Choice and Alarm Constraints defined within a param tag:
<param constrainttype="ctype" param-attributes />
<constraint key-attributes>cvalue</constraint>
<constraint key-attributes>cvalue</constraint>
. . .
</param>
See sections below for examples and syntax for each constraint type.
Constraint Types
Constraint |
Constraint Type |
Param Type |
INT_NULL |
INT16_PARAM INT16_ARRAY INT32_PARAM INT32_ARRAY |
|
FLOAT_NULL |
FLOAT_PARAM FLOAT_ARRAY |
|
INT_RANGE INT_STEP_RANGE |
INT16_PARAM INT16_ARRAY INT32_PARAM INT32_ARRAY |
|
FLOAT_RANGE FLOAT_STEP_RANGE |
FLOAT_PARAM FLOAT_ARRAY |
|
INT_CHOICE |
INT16_PARAM INT16_ARRAY INT32_PARAM INT32_ARRAY |
|
STRING_CHOICE |
STRING_PARAM STRING_ARRAY |
|
ALARM_TABLE |
INT16_PARAM INT32_PARAM |
|
ID_REFERENCE |
All |
|
STRUCT |
STRUCT_PARAM STRUCT_ARRAY |
Note If no constraint is specified for a parameter, it will be unconstrained by default.
Refer to the appropriate section below for definition of the constraint object for each constraint type.
Specifies that a parameter is unconstrained. All parameters are considered unconstrained by default if no constraint is applied.
Syntax
<param constrainttype="constraint-type" attributes />
Attributes
Attribute |
Values |
Restrictions |
Description |
constrainttype |
INT_NULL
|
param type: INT16_PARAM INT16_ARRAY INT32_PARAM INT32_ARRAY |
Parameter is unconstrained |
FLOAT_NULL
|
param type: FLOAT_PARAM FLOAT_ARRAY |
Examples
The following constraint specifies an integer to be unconstrained:
<param constrainttype="INT_NULL" name="Delay" oid="0x500" type="INT16_PARAM"/>
constraint (Constraint Reference)
References a globally-defined constraint. A constraint may be specified globally in the <meta> block. These globally-defined constraints may then by referenced by specific parameters.
Syntax
<constraint id="constraint-id" constrainttype="constraint-type">
<param constrainttype="ID_REFERENCE" constraint="constraint-id" attributes />
Attributes
Attribute |
Values |
Restrictions |
Description |
id |
String |
|
Unique identifier for this constraint |
constrainttype |
Any valid constraint type |
Param type must be compatible with the referenced constraint. |
See Constraint Types for valid constraint types. |
Examples
The following example creates a global constraint VideoFormat. Params 0x501, 0x502 and 0x503 are all constrained using this constraint definition.
<constraint constrainttype="INT_CHOICE" id="VideoFormat">
<constraint key="0">480i-59.94</constraint>
<constraint key="1">576i-50</constraint>
<constraint key="2">1080i-29.97</constraint>
<constraint key="3">1080i-25</constraint>
<constraint key="4">720p-59.94</constraint>
<constraint key="5">720p-50</constraint>
<constraint key="6">1080p-59.94</constraint>
<constraint key="7">1080p-50</constraint>
</constraint>
<param constrainttype="ID_REFERENCE" constraint="VideoFormat" name="Vid1" oid="0x501" type="INT16_PARAM"/>
<param constrainttype="ID_REFERENCE" constraint="VideoFormat" name="Vid2" oid="0x502" type="INT16_PARAM"/>
<param constrainttype="ID_REFERENCE" constraint="VideoFormat" name="Vid3" oid="0x503" type="INT16_PARAM"/>
constraint (Range Constraints)
Constrains a numeric parameter type to a specific range. Minimum and maximum values effect the parameter’s valid range. Display minimum and maximum values scale the parameter value to a different range for display purposes. Finally a step value can be set to constrain the minimum step size a value may be changed by.
Syntax
Min / Max Constraint:
<param constraint="min;max;" constrainttype="constraint-type" attributes />
Min / Max Constraint with Display-Min and Display-Max:
<param constraint="min;max;display-min;display-max;"
constrainttype="constraint-type" attributes />
Min / Max Step Constraint:
<param constraint="min;max;step" constrainttype="constraint-type" attributes />
Min / Max Step Constraint with Display-Min and Display-Max:
<param constraint="min;max;display-min;display-max;step"
constrainttype="constraint-type" attributes />
Attributes
Attribute |
Values |
Restrictions |
Description |
constrainttype |
INT_RANGE INT_STEP_RANGE |
param type: INT16_PARAM INT16_ARRAY INT32_PARAM INT32_ARRAY |
Type of constraint |
FLOAT_RANGE FLOAT_STEP_RANGE |
param type: FLOAT_PARAM FLOAT_ARRAY |
||
constraint |
min |
Required |
Minimum value to which a parameter can be set |
max |
Required |
Minimum value to which a parameter can be set |
|
display-min |
Optional; must be used with display_max. |
The displayed value of the parameter when the parameter has a value of min. The default value is min. |
|
display-max |
Optional; must be used with display_min. |
The displayed value of the parameter when the parameter has a value of max. The default value is max. |
|
step |
xxx_STEP_RANGE constraints only |
Smallest increment a value may be changed by. Spinner widgets will increment a parameter by the step value. Note that the step increment is applied to the parameter value, not the display value. |
Examples
The following example constrains a FLOAT_PARAM to [0,100]:
<param constraint="0.0;100.0;" constrainttype="FLOAT_RANGE" name="Delay" oid="audio.delay" type="FLOAT_PARAM"/>
The following example constrains an integer to [0, 255] mapping it to a display range of [0, 100], and the value increments by steps of 2:
<param constraint="0;255;0;100;2" constrainttype="INT_STEP_RANGE" name="Gain" oid="key1.gain" type="INT16_PARAM"/>
constraint (Integer Choice Constraints)
Choice constraints provide a list of possible values for a parameter, based upon a text selection. For integer parameters, the parameter may only be assigned a value specified in the constraint.
Syntax
<param constrainttype="INT_CHOICE" type="param-type" attributes >
<constraint key="choice1-key">choice1-value</constraint>
<constraint key="choice2-key">choice2-value</constraint>
. . .
</param>
Attributes
Attribute |
Values |
Restrictions |
Description |
type |
INT16_PARAM INT32_PARAM INT16_ARRAY INT32_ARRAY |
|
Parameter must be integer type. |
key |
Integer |
|
Numeric assignment of current enumerated choice. |
value |
String |
|
Text name for the current enumerated choice |
Examples
The following constraint provides an enumerated choice:
<param constrainttype="INT_CHOICE" name="Channel" oid="0x503" type="INT16_PARAM">
<constraint key="0">Channel 01</constraint>
<constraint key="1">Channel 02</constraint>
<constraint key="2">Channel 03</constraint>
<constraint key="3">Channel 04</constraint>
</param>
constraint (String Choice Constraints)
Choice constraints provide a list of possible values for a parameter, based upon a text selection. For String parameters, the constraint provides a set of defaults, but the user may arbitrarily enter any other value for the parameter.
Syntax
<param constrainttype="STRING_CHOICE" type="param-type" attributes >
<constraint>value</constraint>
<constraint>value</constraint>
. . .
</param>
Attributes
Attribute |
Values |
Restrictions |
Description |
type |
STRING_PARAM STRING_ARRAY |
|
Parameter must be string type. |
value |
String |
|
Available strings for drop-down widget |
Examples
The following constraint provides five string options for a String parameter.
<param constrainttype="STRING_CHOICE" name="Name" oid="0x504" type="STRING_PARAM">
<constraint>Zeus Test Card</constraint>
<constraint>ZTC</constraint>
<constraint>Johnny</constraint>
<constraint>Matilda</constraint>
</param>
Figure 76 – String Choice
Alarm constraints map a set of alarms as bitfields into an INT16_PARAM or INT32_PARAM. Each bit represents an independent alarm which may have a message and severity assigned to it. Alarm parameters contribute to the device’s overall alarm status in DashBoard; the most severe alarm set will determine the device’s overall reported alarm status.
Syntax
<param constrainttype="ALARM_TABLE" type="param-type" attributes >
<constraint key="bit-number" severity="severity">value</constraint>
<constraint key="bit-number" severity="severity">value</constraint>
. . .
</param>
Attributes
Attribute |
Values |
Restrictions |
Description |
type |
INT16_PARAM INT32_PARAM |
|
Parameter must be integer type. |
key |
Integer |
INT16: 0..15 INT32: 0..31 |
The bit position for the alarm (0 is LSB).
|
severity |
Integer |
|
The severity of the alarm: 0 = OK 1 = WARN 2 = ERROR |
value |
String |
|
Alarm message text |
Examples
The following constraint creates an alarm table:
<param constrainttype="ALARM_TABLE" name="Alarm" oid="0x504" type="INT16_PARAM">
<constraint key="0" severity="0">Hardware OK</constraint>
<constraint key="1" severity="2">Hardware Error</constraint>
<constraint key="2" severity="1">Flash Memory Full</constraint>
</param>
constraint (Struct Constraints)
Struct Constraints allow a parameter to define a complex structure of multiple parameters. The Struct Constraint is applied to each parameter that is an instance of a Struct.
Syntax
<param constrainttype="STRUCT" structtype="struct-type" templateoid="template-oid"
type="STRUCT" param-attributes>
Attributes
Attribute |
Values |
Restrictions |
Description |
type |
String |
Required |
Set to "STRUCT" |
templateoid |
String |
|
Specifies a template OID to pre-populate the structure. All parameters, constraints and widgets for the sub-OIDs are copied from the template. |
structtype |
String |
Must be unique |
Defines the structure type. Used by PanelBuilder to type-check custom widgets against defined struct parameters. |
Examples
The following code is an example of a struct definition.
<param constrainttype="STRUCT" name="Clip Info" oid="clipInfo"
structtype="playinfo" type="STRUCT" widget="36">
<value>
<subparam name="Clip Name" suboid="ClipName" type="STRING" value="Test"/>
<subparam name="Director" suboid="Director" type="STRING" value="Test"/>
<subparam name="Date" suboid="AirDate" type="STRING" value="Test"/>
<subparam name="Author" suboid="Author" type="STRING" value="Test"/>
</value>
</param>
The following declaration utilizes the previous example as a template, by specifying the templateoid attribute:
<param constrainttype="STRUCT" name="Clip List" oid="clipList"
structtype="playinfo" templateoid="clipInfo" type="STRUCT_ARRAY" widget="36">
<value>
<subparam suboid="ClipName" value="Winter is Coming"/>
<subparam suboid="Director" value="Tim Van Patten"/>
<subparam suboid="OriginalAirDate" value="April 24, 2011"/>
<subparam suboid="Author" value="David Benoiff & D.B. Weiss"/>
</value>
<value>
<subparam suboid="ClipName" value="The Kingsroad"/>
<subparam suboid="Director" value="Brian Kirk"/>
<subparam suboid="OriginalAirDate" value="April 24, 2011"/>
<subparam suboid="Author" value="David Benoiff & D.B. Weiss"/>
</value>
<value>
<subparam suboid="ClipName" value="Lord Snow"/>
<subparam suboid="Director" value="Brian Kirk"/>
<subparam suboid="OriginalAirDate" value="May 1, 2011"/>
<subparam suboid="Author" value="David Benoiff & D.B. Weiss"/>
</value>
<value>
<subparam suboid="ClipName" value="A Golden Crown"/>
<subparam suboid="Director" value="Daniel Minahan"/>
<subparam suboid="OriginalAirDate" value="May 22, 2011"/>
<subparam suboid="Author" value="David Benioff & D. B. Weiss"/>
</value>
</param>