2.2.2 button (Button)

  • Article

This element specifies a standard push-button control that performs an action when clicked.

For example, consider a button control, as follows:

A button control

Figure 2: A button control

This is specified using the following XML fragment:

 <button id="button" label="Button" imageMso="HappyFace" />

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

Parent Elements

Section

box

2.2.1

group

2.2.23

The following table summarizes the attributes of this element.

Attributes

Description

description (description)

Specifies a detailed description of the control, which is 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 detailed 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 always 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 that is 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 that is 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 to be 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 to be 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.

getKeytip (getKeytip callback)

Specifies the name of a callback function that is 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 to be 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 to be 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 to be 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.

getShowImage (getShowImage callback)

Specifies the name of a callback function to be called to determine whether the application is to 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 to be 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 is to 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 to be 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 to be 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 to be 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 to be 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 is 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 that is 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 to 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 that is 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 id 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 id 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 id 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 id 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 that is 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 text

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.

showLabel (show label)

Specifies whether this control displays 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.

supertip (supertip)

Specifies a string that is 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:

Control with a supertip 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 id 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_Button">
    <xsd:complexContent>
    <xsd:extension base="CT_ButtonRegular">
    <xsd:attributeGroup ref="AG_SizeAttributes"/>
    </xsd:extension>
    </xsd:complexContent>
 </xsd:complexType>