This element compares a dialog variable with a value. If the result is true, the inner nodes are expanded and the condition code is set to true; otherwise the inner nodes are ignored, and the conditon code is set to false.

The domain of comparisons that can be performed by ui:ifvar overlaps with ui:if. Especially the comparison of a non-associative variable with a value can be expressed by both elements. In doubt, use the shorter and more common ui:if.

Level: Control structure

<!ELEMENT ui:ifvar ANY>

<!ATTLIST ui:ifvar
          variable NMTOKEN           #REQUIRED
          index    NMTOKEN           #IMPLIED
          value    CDATA             #REQUIRED
          op       CDATA             "eq"
>

• variable: The name of the variable that is compared with the value.

• index: If the variable is associative, the index can select the component. However, it is also possible to compare associative variables as such if one of the list operators is applied.

• value: The second operand of the comparison besides the value of the variable.

• op: Selects the comparison operator

All page body elements may occur as sub elements.

The following operators are defined for ui:if (we call the value of the variable the "first operand", and the value denoted by the value attribute the "second operand"):

• Operators for string variables

  • eq: string equality

  • ne: string inequality

  • match: the first operand matches the regular expression denoted by the second operand (see notes on regular expressions below)

  • nomatch: the first operand does not match the regular expression denoted by the second operand (see notes on regular expressions below)

  • int-eq: integer equality

  • int-ne: integer inequality

  • int-lt: the first operand is less than the second operand

  • int-le: the first operand is less or equal than the second operand

  • int-gt: the first operand is greater than the second operand

  • int-ge: the first operand is greater or equal than the second operand

• Operators for enumerators (declared or dynamic), and for associative variables

  • contains: The first operand contains the second operand as component (key). For enumerators, this means that the first operand has an internal value equal to the second operand. For associations, this means that the first operand has a component indexed by the second operand.

  • mentions: The first operand contains the second operand as component (value). For dynamic enumerators, this means that the first operand has an external value equal to the second operand (the operation is not defined for declared enumerators). For associations, this means that the first operand has a component in whose value the second operand occurs.

  • card-eq, card-ne, card-lt, card-le, card-gt, card-ge: The cardinality of the first operand is compared with the number in the second operand.

• Operators for variables of type dialog

  • dialog-exists: The first operand is of dialog type, and the second operand is either yes or no. The comparison yields a true result, if the first operand contains a dialog and the second operand is yes, or if the first operand does not contain a dialog, and the second operand is no.

Since WDialog-2.1, it is possible to call any function defined for bracket expressions. The function is called with two arguments, and it is expected that the function returns a number indicating a boolean result: 0 is considered as the false value, and a non-zero number is considered as the true value. Currently, there aren't any other functions that would make sense to be called. The user may, however, define further functions.

The engine matching regular expressions is PCRE (Perl-compatible regular expressions), so the Perl syntax is used. The expressions are not anchored by default, so have to write ^ and $$ to force anchoring. ^ matches the beginning of the string, and $$ matches the end of the string ("single-line expressions"). Note that you have to write double dollars $$ because the dollar character is the escape character for template parameters.

<ui:dialog start-page="poll">
  <ui:enumeration name="fruit">
    <ui:enum internal="apple" external="I like apples"/>
    <ui:enum internal="orange" external="I like oranges"/>
    <ui:enum internal="bananas" external="I like bananas"/>
    <ui:enum internal="ananas" external="I like ananas"/>
  </ui:enumeration>

  <ui:variable name="pref" type="fruit"/>

  <ui:page name="poll">
     ...
     Please click at your preferred fruit:
     <ui:select variable="pref" multiple="yes"/>
     ...
  </ui:page>

  <ui:page name="check">
    ...
    <ui:ifvar variable="pref" value="0" op="card-eq">
      You don't have selected any fruit sort. ...
    </ui:ifvar>
    ...
  </ui:page>
</ui:dialog>

Note that template parameters and bracket expressions within ui:ifvar are unconditionally evaluated. See ui:cond for a discussion of the consequences of this fact.