XForms Select1 Element

Introduction

Allows the user to choose a single value from a list of pre-defined values (see the spec). The list of pre-defined items can be specified by either item (see the spec) or itemset (see the spec) elements. You can visually group these pre-defined items by using the choices (see the spec) element to contain them. Note, some representations of the select1 element do not support visual grouping.

Attributes

• UI Common
  • appearance - the value of this attribute gives a hint to the XForms processor as to which type of widget(s) to use to represent this control.
  • accesskey - used to specify the keyboard shortcut for focusing this control.
• Single-Node Binding
• Special
  • selection - this attribute, when set to 'open', allows the user to provide free entry to the list. Possible values are open and closed, default is closed (see #Representations section to refer if the attribute is supported for every representation).
  • incremental - supported, default value is true

Properties

• selection - see corresponding attribute
• incremental - see corresponding attribute

Type restrictions

The select1 element can be bound to a node containing simple content. The data binding restriction to simple content may be relaxed when an itemset element is used, which allows the available choices to be obtained from an XForms Model. The relaxation happens when the itemset element specifies the item value using a copy (see spec) element. This is because a copy element can be used to add a subtree of nodes underneath the element that the select1 control is bound to.

Representations

The XForms select1 element can be represented by the following widgets for the specified appearance attribute values:

• combobox - default representation (xhtml/xul)
• listbox - used when appearance = 'compact' (xhtml/xul)
• radio group - used when appearance = 'full' (xhtml/xul)

combobox

Displaying a combobox is the default representation (xhtml/xul).

XHTML widget characteristics

• analogous widgets is <html:select/>
• visual grouping by choices element is supported
• selection="open" is supported
• if incremental attribute value is false, the bound node is updated when the select1 control is blurred (i.e. loses focus), otherwise it is updated upon item selection

XUL widget characteristics

• analogous widgets are <html:select/> and <xul:menulist/>
• visual grouping by choices element isn't implemented
• selection="open" attribute isn't supported
• if incremental attribute value is false, the bound node is updated when the select control is blurred (i.e. loses focus), otherwise it is updated upon item selection

listbox

The select1 is represented as listbox (xhtml/xul).

Characteristics

• analogous widgets are <html:select size="5"/> and <xul:listbox/>
• visual grouping by choices element isn't implemented
• selection="open" attribute isn't supported
• if incremental attribute value is false, the bound node is updated when the select control is blurred (i.e. loses focus), otherwise it is updated upon item selection

radio group

The select is represented as group of radios (xhtml/xul).

Characteristics

• appearance attribute contains the value full
• there are no analogue widgets in XHTML or in XUL
• visual grouping by choices element is supported
• selection="open" attribute isn't supported
• if incremental attribute value is false then bound node is updated when item is blurred

Examples

<xf:model>
  <xf:instance>
    <data xmlns="">
      <values>g</values>
    </data>
  </xf:instance>
</xf:model>

<xf:select1 ref="/data/values">
  <xf:choices>
    <xf:label>Green colors</xf:label>
    <xf:item>
      <xf:label>Pale green</xf:label>
      <xf:value>pg</xf:value>
    </xf:item>
    <xf:item>
      <xf:label>Green</xf:label>
      <xf:value>g</xf:value>
    </xf:item>
  </xf:choices>
  <xf:choices>
    <xf:label>Red colors</xf:label>
    <xf:item>
      <xf:label>Red</xf:label>
      <xf:value>r</xf:value>
    </xf:item>
    <xf:item>
      <xf:label>Magenta</xf:label>
      <xf:value>m</xf:value>
    </xf:item>
  </xf:choices>
</xf:select>