2.2.17 dropDown (Drop-down Control)

  • Article

This element specifies a drop-down control that allows users to make a selection from a list of options. A drop-down control can optionally have buttons after its selection items.

For example, consider a drop-down control, as follows:

A drop-down control

Figure 9: A drop-down control

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

box (section 2.2.1); group (section 2.2.23)

The following table summarizes the child elements of this element.

Child Elements

Section

button (Unsized Button)

2.2.3

item (Selection Item)

2.2.24

The following table summarizes the attributes of this element.

Attributes

Description

enabled (enabled state)

Specifies the enabled state of the control.

The getEnabled and enabled attributes are mutually exclusive. If neither attribute is specified, the control SHOULD default to being enabled.

This attribute cannot be used to enable a built-in control that would otherwise be disabled by the application.

For example, consider the following XML fragment:

 <button   id="button" label="Disabled Button"   enabled="false" />

This specifies a new button that is disabled. A permanently disabled button is not very useful, thus the enabled attribute is not commonly used.

The possible values for this attribute are defined by the XML schema boolean datatype.

getEnabled (getEnabled callback)

Specifies the name of a callback function to be called to determine the enabled state of this control.

The getEnabled and enabled attributes are mutually exclusive. If neither attribute is specified, the control SHOULD default to being enabled.

For example, consider the following XML fragment:

 <button   id="button" getEnabled="IsButtonEnabled" />

In this example, the IsButtonEnabled callback function is called when the application needs to determine the enabled state of the button.

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

getImage (getImage callback)

Specifies the name of a callback function to be called to determine the icon of this control.

The getImage, image, and imageMso attributes are mutually exclusive. If none of these attributes are specified, no icon SHOULD be displayed.

For example, consider the following XML fragment:

 <button   id="button" getImage="GetButtonImage" />

In this example, the GetButtonImage callback function is called when the application needs to determine the icon of the button.

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

getItemCount (getItemCount callback)

Specifies the name of a callback function to be called to determine the number of selection items in this control.

If this attribute is omitted, the control SHOULD display any selection items that are specified as child elements. If no such items are specified, the control SHOULD be empty.

For example, consider the following XML fragment:

 <gallery   id="gallery" getItemCount="GetGalleryItemCount" />

In this example, the GetGalleryItemCount callback function is called when the application needs to determine the number of items in the gallery.

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

getItemID (getItemID callback)

Specifies the name of a callback function to be called to determine the identifier of a specific dynamically-created selection item, identified by index.

If this attribute is omitted, dynamically-created selection items SHOULD have empty identifiers.

For example, consider the following XML fragment:

 <gallery   id="gallery" getItemCount="GetGalleryItemCount" 
     getItemID="GetGalleryItemID" />

In this example, the GetGalleryItemID callback function is called when the application needs to determine the identifier of a selection item.

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

getItemImage (getItemImage callback)

Specifies the name of a callback function to be called to determine the icon of a specific dynamically-created selection item, identified by index.

If this attribute is omitted, dynamically-created selection items SHOULD NOT display icons.

For example, consider the following XML fragment:

 <gallery   id="gallery" getItemCount="GetGalleryItemCount" 
     getItemImage="GetGalleryItemImage" />

In this example, the GetGalleryItemImage callback function is called when the application needs to determine the icon of a selection item.

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

getItemLabel (getItemLabel callback)

Specifies the name of a callback function to be called to determine the label of a specific dynamically-created selection item, identified by index.

If this attribute is omitted, dynamically-created selection items SHOULD NOT display labels.

For example, consider the following XML fragment:

 <gallery   id="gallery" getItemCount="GetGalleryItemCount" 
     getItemLabel="GetGalleryItemLabel" />

In this example, the GetGalleryItemLabel callback function is called when the application needs to determine the label of a selection item.

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

getItemScreentip (getItemScreentip callback)

Specifies the name of a callback function to be called to determine the screentip of a specific dynamically-created selection item, identified by index.

If this attribute is omitted, dynamically-created selection items SHOULD use their labels as their screentips, or display no screentips at all.

For example, consider the following XML fragment:

 <gallery   id="gallery" getItemCount="GetGalleryItemCount" 
     getItemScreentip="GetGalleryItemScreentip" />

In this example, the GetGalleryItemScreentip callback function is called when the application needs to determine the screentip of a selection item.

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

getItemSupertip (getItemSupertip callback)

Specifies the name of a callback function to be called to determine the supertip of a specific dynamically-created selection item, identified by index.

If this attribute is omitted, dynamically-created selection items SHOULD NOT display supertips.

For example, consider the following XML fragment:

 <gallery   id="gallery" getItemCount="GetGalleryItemCount" 
     getItemSupertip="GetGalleryItemSupertip" />

In this example, the GetGalleryItemSupertip callback function is called when the application needs to determine the supertip of a selection item.

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

getKeytip (getKeytip callback)

Specifies the name of a callback function to be called to determine the suggested KeyTip of this control.

The getKeytip and keytip attributes are mutually exclusive. If neither attribute is specified, the application SHOULD generate a KeyTip for the control automatically.

For example, consider the following XML fragment:

 <button   id="button" getKeytip="GetButtonKeytip" />

In this example, the GetButtonKeytip callback function is called when the application needs to determine the KeyTip of the button.

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

getLabel (getLabel callback)

Specifies the name of a callback function to be called to determine the label of this control.

The getLabel and label attributes are mutually exclusive. If neither attribute is specified, no label SHOULD be displayed.

For example, consider the following XML fragment:

 <button   id="button" getLabel="GetButtonLabel" />

In this example, the GetButtonLabel callback function is called when the application needs to determine the label of the button.

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

getScreentip (getScreentip callback)

Specifies the name of a callback function to be called to determine the screentip of this control.

The getScreentip and screentip attributes are mutually exclusive. If neither attribute is specified, the application SHOULD display the label of the control as the screentip or display no screentip at all.

For example, consider the following XML fragment:

 <button   id="button" getScreentip="GetButtonScreentip" />

In this example, the GetButtonScreentip callback function is called when the application needs to determine the screentip of the button.

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

getSelectedItemID (getSelectedItemID callback)

Specifies the name of a callback function to be called to determine the identifier of the item to be selected in this control.

The getSelectedItemID and getSelectedItemIndex attributes are mutually exclusive. If neither attribute is specified, the control SHOULD NOT display a selected item.

For example, consider the following XML fragment:

 <gallery   id="gallery" getItemCount="GetGalleryItemCount"
     getItemID="GetItemID"
     getSelectedItemID="GetGallerySelectedItemID" />

In this example, the GetGallerySelectedItemID callback function is called when the application needs to determine the selected item in the gallery. In this example the callback function returns one of the identifiers returned by the GetItemID callback function.

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

getSelectedItemIndex (getSelectedItemIndex callback)

Specifies the name of a callback function to be called to determine the index of the item to be selected in this control.

The getSelectedItemID and getSelectedItemIndex attributes are mutually exclusive. If neither attribute is specified, the control SHOULD NOT display a selected item.

For example, consider the following XML fragment:

 <gallery   id="gallery" getItemCount="GetGalleryItemCount"
     getSelectedItemIndex="GetGallerySelectedItemIndex" />

In this example, the GetGallerySelectedItemIndex callback function is called when the application needs to determine the selected item in the gallery.

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

getShowImage (getShowImage callback)

Specifies the name of a callback function to be called to determine whether the application displays the icon of this control.

The showImage and getShowImage attributes are mutually exclusive. If neither attribute is specified, the control SHOULD display its icon.

For example, consider the following XML fragment:

 <button   id="button" getShowImage="IsButtonImageVisible" />

In this example, the IsButtonImageVisible callback function is called when the application needs to determine whether to display the icon of the button.

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

getShowLabel (getShowLabel callback)

Specifies the name of a callback function to be called to determine whether the application displays the label of this control.

The showLabel and getShowLabel attributes are mutually exclusive. If neither attribute is specified, the control SHOULD default to showing its label.

For example, consider the following XML fragment:

 <button   id="button" getShowLabel="IsButtonLabelVisible" />

In this example, the IsButtonLabelVisible callback function is called when the application needs to determine whether to display the label of the button.

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

getSupertip (getSupertip callback)

Specifies the name of a callback function to be called to determine the supertip of this control.

The getSupertip and supertip attributes are mutually exclusive. If neither attribute is specified, no supertip for this control SHOULD be shown.

For example, consider the following XML fragment:

 <button   id="button" getSupertip="GetButtonSupertip" />

In this example, the GetButtonSupertip callback function is called when the application needs to determine the supertip of the button.

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

getVisible (getVisible callback)

Specifies the name of a callback function to be called to determine the visibility state of this control.

The getVisible and visible attributes are mutually exclusive. If neither attribute is specified, the control SHOULD default to being visible.

For example, consider the following XML fragment:

 <button   id="button" getVisible="IsButtonVisible" />

In this example, the IsButtonVisible callback function is called when the application needs to determine the visibility of the button.

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

id (control identifier)

Specifies the identifier for a custom control. All 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.

The id, idQ, and idMso attributes are mutually exclusive. At least one of these attributes MUST be specified.

For example, consider the following XML fragment:

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

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

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

idMso (built-in control identifier)

Specifies the identifier of a built-in control.

The contents of this attribute are application-defined.

The id, idQ, and idMso attributes are mutually exclusive. At least one of these attributes MUST be specified.

For example, consider the following XML fragment:

 <control   idMso="Bold" />

This creates a clone of the control 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.

idQ (qualified control identifier)

Specifies a qualified identifier for a control.

The idQ attribute can be used to reference controls or containers created by other Custom UI documents.

The id, idQ, and idMso attributes are mutually exclusive. At least one of these attributes MUST be specified.

For example, consider the following XML fragment:

 <customUI   
     xmlns="http://schemas.microsoft.com/office/2006/01/customui"
     xmlns:ex="http://www.example.com">
     <ribbon>
       <tabs>
        <tab idQ="ex:OtherTab" label="Shared Tab">
           <group id="MyGroup" label="My Group">
             …
           </group>
         </tab>
       </tabs>
     </ribbon>
 </customUI>

In this case, ex is an XML namespace prefix for the namespace http://www.example.com. This XML fragment refers to a tab in that namespace with an identifier of "OtherTab". If that tab cannot be found, it is created. A new group belonging to this file is added to the tab.

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

image (custom image identifier)

Specifies the relationship identifier 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 getImage, image, and imageMso attributes are mutually exclusive. If none of these attributes are specified, no icon SHOULD be displayed.

For example, consider the following XML fragment:

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

This specifies a custom button whose icon 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 getImage, image, and imageMso attributes are mutually exclusive. If none of these attributes are specified, no icon SHOULD be displayed.

For example, consider the following XML fragment:

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

This specifies a custom button that 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.

insertAfterMso (identifier of built-in control to insert after)

Specifies the identifier of a built-in control that this control is to be inserted after. If the value of this attribute is not understood, it SHOULD be ignored.

The insertAfterMso, insertAfterQ, insertBeforeMso, and insertBeforeQ attributes are mutually exclusive. If none of these attributes are specified, the controls SHOULD be appended to the existing set of controls, in the order they are defined in the XML.

For example, consider the following XML fragment:

 <tab   id="MyTab" insertAfterMso="TabHome" label="Custom   Tab">
     …
 </tab>

In this example, a new custom tab with an identifier of "MyTab" is to be inserted after the built-in tab with an identifier of "TabHome".

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

insertAfterQ (qualified identifier of control to insert after)

Specifies the qualified identifier of a control that this control is to be inserted after. If the value of this attribute is not understood, it SHOULD be ignored.

The insertAfterMso, insertAfterQ, insertBeforeMso, and insertBeforeQ attributes are mutually exclusive. If none of these attributes are specified, the controls SHOULD be appended to the existing set of controls, in the order they are defined in the XML.

For example, consider the following XML fragment:

 <tab   id="MyTab" insertAfterQ="x:OtherTab" label="Custom   Tab">
     …
 </tab>

In this example, a new custom tab with an identifier of "MyTab" is to be inserted after the custom tab with a qualified identifier of "x:OtherTab".

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

insertBeforeMso (identifier of built-in control to insert before)

Specifies the identifier of a built-in control that this control is to be inserted before. If the value of this attribute is not understood, it SHOULD be ignored.

The insertAfterMso, insertAfterQ, insertBeforeMso, and insertBeforeQ attributes are mutually exclusive. If none of these attributes are specified, the controls SHOULD be appended to the existing set of controls, in the order they are defined in the XML.

For example, consider the following XML fragment:

 <tab   id="MyTab" insertBeforeMso="TabHome" label="Custom   Tab">
     …
 </tab>

In this example, a new custom tab with an identifier of "MyTab" is to be inserted before the built-in tab with an identifier of "TabHome".

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

insertBeforeQ (qualified identifier of control to insert before)

Specifies the qualified identifier of a control that this control is to be inserted before. If the value of this attribute is not understood, it SHOULD be ignored.

The insertAfterMso, insertAfterQ, insertBeforeMso, and insertBeforeQ attributes are mutually exclusive. If none of these attributes are specified, the controls SHOULD be appended to the existing set of controls, in the order they are defined in the XML.

For example, consider the following XML fragment:

 <tab   id="MyTab" insertBeforeQ="x:OtherTab" label="Custom   Tab">
     …
 </tab>

In this example, a new custom tab with an identifier of "MyTab" is to be inserted before the custom tab with a qualified identifier of "x:OtherTab".

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

keytip (keytip)

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

The keytip and getKeytip attributes are mutually exclusive. If neither attribute is specified, the application SHOULD generate a KeyTip for the control automatically.

For example, consider a button with KeyTip 'K', as follows:

Button with Key Tip K

This is specified using the following XML fragment:

 <button   id="button" imageMso="HappyFace" keytip="K"   />

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

label (label)

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

The label and getLabel attributes are mutually exclusive. If neither attribute is specified, no label SHOULD be displayed.

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.

onAction (onAction callback)

Specifies the name of a callback function to be called when this control is invoked by the user.

For example, consider the following XML fragment:

 <button   id="button" label="Button"   onAction="ButtonClicked" />

This specifies a button that calls the ButtonClicked callback function when it is invoked.

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

screentip (screentip)

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

The screentip and getScreentip attributes are mutually exclusive. If neither attribute is specified, the application SHOULD display the label of the control as the screentip or display no screentip at all.

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.

showImage (show image)

Specifies whether this control displays an icon.

The showImage and getShowImage attributes are mutually exclusive. If neither attribute is specified, the control SHOULD display its icon.

For example, consider a button that does not display an icon, as follows:

Button with no icon

This is specified using the following XML fragment:

 <button   id="button" showImage="false" 
     label="Button with no icon" />

The possible values for this attribute are defined by the XML schema boolean datatype.

showItemImage (show item image)

Specifies whether this control displays icons on its selection items.

If this attribute is omitted, the items' icons SHOULD be shown by default.

For example, consider the following XML fragment:

 <gallery   id="gallery" label="Gallery"   showItemImage="false" >
     <item id="item1" label="Item 1" />
     <item id="item2" label="Item 1" />
     <item id="item3" label="Item 2" />
     <item id="item4" label="Item 3" />
 </gallery>

This specifies a gallery control that does not show any icons on its selection items.

The possible values for this attribute are defined by the XML schema boolean datatype.

showItemLabel (show item label)

Specifies whether this control displays labels on its selection items.

If this attribute is omitted, the item's labels SHOULD be shown by default.

For example, consider the following XML fragment:

 <gallery   id="gallery" label="Gallery"   showItemLabel="false" >
     <item id="item1" image="Forest" />
     <item id="item2" image="Desert" />
     <item id="item3" image="Mountain" />
     <item id="item4" image="Ocean" />
 </gallery>

This specifies a gallery control that does not show any labels on its selection items.

The possible values for this attribute are defined by the XML schema boolean datatype.

showLabel (show label)

Specifies whether this control displays its label.

The showLabel and getShowLabel attributes are mutually exclusive. If neither attribute is specified, the control SHOULD default to showing its label.

For example, consider the following XML fragment:

 <button   id="button" label="Label" showLabel="false" 
     imageMso="HappyFace" />

This specifies a button that has a label, but does not show it. Even though the label is hidden, it is provided to accessibility tools.

The possible values for this attribute are defined by the XML schema boolean datatype.

sizeString (size string)

Specifies a string whose size is used to determine the width of the text input area of this control.

If this attribute is omitted, the application SHOULD determine the width of the text input area of the control automatically.

For example, consider the following XML fragment:

 <editBox   id="editBox" sizeString="WWWWWWWWWWWWW" />

This specifies an edit box control that is wide enough to display the string "WWWWWWWWWWWWW".

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.

The supertip and getSupertip attributes are mutually exclusive. If neither attribute is specified, no supertip for this control SHOULD be shown.

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.

tag (tag)

Specifies an arbitrary string that can be used to hold data or identify the control. The contents of this attribute SHOULD be passed to any callback functions specified on this control.

If this attribute is omitted, the control's tag value SHOULD default to an empty string.

For example, consider the following XML fragment:

 <button   id="button" label="Button" tag="123456" 
     onAction="ButtonClicked" />

This specifies a button with a tag value of "123456", which is passed to the ButtonClicked callback function.

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

visible (control visibility)

Specifies the visibility state of the control.

The getVisible and visible attributes are mutually exclusive. If these attributes are omitted, the control SHOULD default to being visible.

For example, consider the following XML fragment:

 <tab   idMso="TabHome" visible="false" />

In this example, the built-in tab with an identifier of "TabHome" is hidden.

The possible values for this attribute are defined by the XML schema boolean datatype.

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

 <xsd:complexType name="CT_DropDownRegular">
    <xsd:complexContent>
    <xsd:extension base="CT_Control">
    <xsd:sequence>
    <xsd:element name="item" type="CT_Item" minOccurs="0" maxOccurs="1000"/>
    <xsd:element name="button" type="CT_ButtonRegular" minOccurs="0" maxOccurs="16"/>
    </xsd:sequence>
    <xsd:attributeGroup ref="AG_Action"/>
    <xsd:attributeGroup ref="AG_Enabled"/>
    <xsd:attributeGroup ref="AG_Image"/>
    <xsd:attributeGroup ref="AG_DropDownAttributes"/>
    <xsd:attribute name="getSelectedItemID" type="ST_Delegate" use="optional"/>
    <xsd:attribute name="getSelectedItemIndex" type="ST_Delegate" use="optional"/>
    <xsd:attribute name="showItemLabel" type="xsd:boolean" use="optional"/>
    </xsd:extension>
    </xsd:complexContent>
 </xsd:complexType>