2.2.24 item (Selection Item)

  • Article

This element specifies an item in a selection-type control.

For example, consider a drop-down control with three selection items, as follows:

A drop-down control with selection items

Figure 14: A drop-down control with selection items

This is specified using the following XML fragment:

 <dropDown id="dropDown" label="DropDown">
   <item id="item1" label="Item 1" />
   <item id="item2" label="Item 2" />
   <item id="item3" label="Item 3" />
   <button id="button" label="Button..." />
 </dropDown>

The following table summarizes the elements that are parents of this element.

Parent Elements

comboBox (section 2.2.7); dropDown (section 2.2.17); gallery (section 2.2.21); gallery (section 2.2.22)

The following table summarizes the attributes of this element.

Attributes

Description

id (custom control identifier)

Specifies the identifier for a custom control. All new custom controls MUST have unique identifiers. The identifier of a control SHOULD be passed to callback functions to identify which control corresponds to the function call.

For example, consider the following XML fragment:

 <button   id="MyButton" label="Button" />

This specifies a custom button control with an identifier of "MyButton".

The possible values for this attribute are defined by the ST_UniqueID simple type, as specified in section 2.3.13.

image (custom image identifier)

Specifies the identification information for an image to be used as the icon for this control. This attribute is used to specify an embedded picture that resides locally within the containing file.

The image, and imageMso attributes are mutually exclusive.

For example, consider the following XML fragment:

 <button   id="button" image="ForestPic" />

In this example, the custom button has an icon that is the embedded image file referenced by the relationship identifier of "ForestPic".

The possible values for this attribute are defined by the ST_Uri simple type, as specified in section 2.3.14.

imageMso (built-in image identifier)

Specifies the identifier of a built-in image to be used as the icon of this control.

The contents of this attribute are application-defined and SHOULD be ignored if not understood.

The image, and imageMso attributes are mutually exclusive.

For example, consider the following XML fragment:

 <button   id="button" imageMso="Bold" />

In this example, the custom button uses the built-in image with an identifier of "Bold".

The possible values for this attribute are defined by the ST_ID simple type, as specified in section 2.3.5.

label (label)

Specifies a string to be used as the label for this control.

For example, consider the following XML fragment:

 <button   id="button" label="Custom Button" />

This specifies a custom button with a label of "Custom Button".

The possible values for this attribute are defined by the ST_String simple type, as specified in section 2.3.11.

screentip (screentip)

Specifies a string to be shown as the screentip for this control.

For example, consider a button with a screentip, as follows:

Button with screen tip string

This is specified using the following XML fragment:

 <button   id="button" imageMso="HappyFace" label="Button"
     size="large" screentip="This is the screentip" />

The possible values for this attribute are defined by the ST_String simple type, as specified in section 2.3.11.

supertip (supertip)

Specifies a string to be shown as the supertip of the control.

For example, consider a control with a supertip, as follows:

Button with super tip string

This is specified using the following XML fragment:

 <button   id="button" imageMso="HappyFace" label="Button"
     size="large" screentip="Screentip"
     supertip="This is the supertip string" />

The possible values for this attribute are defined by the ST_String simple type, as specified in section 2.3.11.

The following XML schema fragment defines the contents of this element:

 <xsd:complexType name="CT_Item">
    <xsd:attribute name="id" type="ST_UniqueID" use="optional"/>
    <xsd:attribute name="label" type="ST_String" use="optional"/>
    <xsd:attribute name="image" type="ST_Uri" use="optional"/>
    <xsd:attribute name="imageMso" type="ST_ID" use="optional"/>
    <xsd:attribute name="screentip" type="ST_String" use="optional"/>
    <xsd:attribute name="supertip" type="ST_String" use="optional"/>
 </xsd:complexType>