2.2.21 gallery (Gallery)

This element specifies a gallery control, which displays a drop-down grid of items that the user can select from. A gallery can optionally have buttons following its selection items.

For example, consider a gallery control that shows a selection of pictures, as follows:

A gallery control

Figure 12: A gallery control

This is specified using the following XML fragment:

 <gallery id="gallery" label="Gallery" itemWidth="88" itemHeight="68" 
          size="large" imageMso="HappyFace" >
   <item id="item1" image="Desert" />
   <item id="item2" image="Forest" />
   <item id="item3" image="Toucan" />
   <item id="item4" image="Tree" />
 </gallery>

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

columns (column count)

Specifies the number of columns that the gallery's items SHOULD be arranged into.

If the columns attribute is omitted, the application SHOULD choose the number of columns automatically based on the number of items.

For example, consider a gallery control with six items arranged into two columns, as follows:

Gallery control with six items in two columns, 3 items per column

This is specified using the following XML fragment:

 <gallery   id="gallery" label="Gallery" columns="2"
     size="large" imageMso="HappyFace" >
     <item id="item1" image="Desert" />
     <item id="item2" image="Forest" />
     <item id="item3" image="Toucan" />
     <item id="item4" image="Tree" />
     <item id="item5" image="Flowers" />
     <item id="item6" image="Whale" />
 </gallery>

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

description (description)

Specifies a detailed description of the control, which SHOULD be displayed in detailed views.

The description and getDescription attributes are mutually exclusive. If neither attribute is specified, the control SHOULD NOT display any detailed text.

For example, consider a button with a detailed description, as follows:

Button with verbose description

This is specified using the following XML fragment:

 <button   id="button" label="Button" imageMso="HappyFace"
     description="This is a verbose description that describes
     the function of this control in detail." />

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

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.

getDescription (getDescription callback)

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

The getDescription and description attributes are mutually exclusive. If neither attribute is specified, the control SHOULD NOT display any detailed text.

For example, consider the following XML fragment:

 <button   id="button" getDescription="GetButtonDescription" />

In this example, the GetButtonDescription callback function is called when the application needs to determine the detailed description of the button.

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

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.

getItemHeight (getItemHeight callback)

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

The itemHeight and getItemHeight attributes are mutually exclusive. If neither attribute is specified, the items SHOULD all take the size of the first item, based on its contents.

The getItemHeight and getItemWidth attributes are mutually required. If only one of the attributes is specified, its value is ignored.

For example, consider the following XML fragment:

 <gallery   id="gallery" getItemCount="GetGalleryItemCount" 
     getItemHeight="GetGalleryItemHeight"
     getItemWidth="GetGalleryItemWidth" />

In this example, the GetGalleryItemHeight callback function is called when the application needs to determine the height of the 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.

getItemWidth (getItemWidth callback)

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

The itemWidth and getItemWidth attributes are mutually exclusive. If neither attribute is specified, the items SHOULD all take the size of the first item, based on its contents.

The getItemHeight and getItemWidth attributes are mutually required. If only one of the attributes is specified, its value is ignored.

For example, consider the following XML fragment:

 <gallery   id="gallery" getItemCount="GetGalleryItemCount" 
     getItemHeight="GetGalleryItemHeight"
     getItemWidth="GetGalleryItemWidth" />

In this example, the GetGalleryItemWidth callback function is called when the application needs to determine the width of the 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.

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 that is 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 SHOULD display the icon of this control.

This attribute SHOULD have no effect if the size or getSize attributes specify that the control is "large".

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 SHOULD display the label of this control.

This attribute SHOULD have no effect if the size or getSize attributes specify that the control is "large".

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.

getSize (getSize callback)

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

The getSize and size attributes are mutually exclusive. If neither attribute is specified, the control's size SHOULD default to the normal size.

For example, consider the following XML fragment:

 <button   id="button" getSize="GetButtonSize" />

In this example, the GetButtonSize callback function is called when the application needs to determine the size 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 identifier 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 which SHOULD 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 SHOULD be 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 which SHOULD 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 SHOULD use 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 SHOULD 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 SHOULD 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 SHOULD 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 SHOULD 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.

invalidateContentOnDrop (invalidate content on drop)

Specifies whether this control SHOULD invalidate its contents and re-query for them when the user opens its drop-down menu.

If this attribute is omitted, its value SHOULD default to false.

For example, consider the following XML fragment:

 <comboBox   id="comboBox" getItemCount="GetComboBoxItemCount"
     getItemLabel="GetComboBoxItemLabel"
     invalidateContentOnDrop="true" />

In this example, this combo box SHOULD clear out its items and re-call the GetComboBoxItemCount and GetComboBoxItemLabel callback functions to populate its contents each time the user opens it.

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

itemHeight (selection item height)

Specifies the height of the selection items in this control.

The itemHeight and getItemHeight attributes are mutually exclusive. If neither attribute is specified, the items SHOULD all take the size of the first item, based on its contents.

The itemHeight and itemWidth attributes are mutually required. If only one of the attributes is specified, its value is ignored.

For example, consider a gallery control with 68 pixel tall items. This is specified using the following XML fragment:

 <gallery   id="gallery" label="Gallery" itemWidth="88"
     itemHeight="68" size="large"   imageMso="HappyFace" >
     <item id="item1" image="Desert" />
     <item id="item2" image="Forest" />
     <item id="item3" image="Toucan" />
     <item id="item4" image="Tree" />
 </gallery>

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

itemWidth (selection item width)

Specifies the width of the selection items in this control.

The itemWidth and getItemWidth attributes are mutually exclusive. If neither attribute is specified, the items SHOULD all take the size of the first item, based on its contents.

The itemHeight and itemWidth attributes are mutually required. If only one of the attributes is specified, its value is ignored.

For example, consider a gallery control with 88 pixel wide items. This is specified using the following XML fragment:

 <gallery   id="gallery" label="Gallery" itemWidth="88" 
     itemHeight="68" size="large"   imageMso="HappyFace" >
     <item id="item1" image="Desert" />
     <item id="item2" image="Forest" />
     <item id="item3" image="Toucan" />
     <item id="item4" image="Tree" />
 </gallery>

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

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" />

In this example, the button 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.

rows (row count)

Specifies the number of rows that the gallery's items are arranged into.

If the rows attribute is omitted, the application SHOULD choose the number of rows automatically based on the number of items.

For example, consider a gallery control with six items arranged into two rows, as follows:

Gallery control with six items in two rows

This is specified using the following XML fragment:

 <gallery   id="gallery" label="Gallery" rows="2"
     size="large" imageMso="HappyFace" >
     <item id="item1" image="Desert" />
     <item id="item2" image="Forest" />
     <item id="item3" image="Toucan" />
     <item id="item4" image="Tree" />
     <item id="item5" image="Flowers" />
     <item id="item6" image="Whale" />
 </gallery>

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

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.

This attribute SHOULD have no effect if the size or getSize attributes specify that the control is "large".

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>

In this example, the gallery control does not show any labels on its selection items.

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

showInRibbon (show in ribbon)

This attribute has no meaning and MUST NOT be used.

showLabel (show label)

Specifies whether this control SHOULD display its label.

This attribute SHOULD have no effect if the size or getSize attributes specify that the control is "large".

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.

size (control size)

Specifies the size of the control.

The size and getSize attributes are mutually exclusive. If neither attribute is specified, the control's size SHOULD default to the normal size.

For example, consider a large button, as follows:

Large button

This is specified using the following XML fragment:

 <toggleButton   idMso="Bold" size="large" />

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

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 screen 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_Gallery">
    <xsd:complexContent>
    <xsd:extension base="CT_GalleryRegular">
    <xsd:attributeGroup ref="AG_SizeAttributes"/>
    </xsd:extension>
    </xsd:complexContent>
 </xsd:complexType>