2.2.27 menu (Menu with Title)

This element specifies a menu control that, because of its location, can optionally include a title string via the title or getTitle attributes. It otherwise behaves identically to the regular menu element, as specified in section 2.2.28.

For example, consider a menu control with a title, as follows:

A menu control with title

Figure 16: A menu control with title

This is specified with the following XML fragment:

 <menu id="menu" label="Menu With Title" title="Title String">
   <button id="button" label="Button" />
 </menu>

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

Parent Elements

menu (section 2.2.27); officeMenu (section 2.2.31); splitButton (section 2.2.37)

The following table summarizes the child elements of this element.

Child Elements

Section

button (Unsized Button)

2.2.3

checkBox (Check Box)

2.2.6

control (Unsized Control Clone)

2.2.11

dynamicMenu (Unsized Dynamic Menu)

2.2.18

gallery (Unsized Gallery)

2.2.22

menu (Menu with Title)

2.2.27

menuSeparator (Menu Separator)

2.2.30

splitButton (Split Button with Title)

2.2.37

toggleButton (Unsized Toggle Button)

2.2.42

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.

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.

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.

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.

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.

getTitle (getTitle callback)

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

The title and getTitle attributes are mutually exclusive. If neither attribute is specified no title SHOULD be shown.

For example, consider the following XML fragment:

 <menu   id="menu" label="Menu"   getTitle="GetMenuTitle">
  …
 </menu>

In this example, the GetMenuTitle callback function is called when the application needs to determine the title of the menu.

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.

itemSize (item size)

Specifies the size of the child controls in this menu.

If this attribute is omitted, the menu's child controls SHOULD default to the normal size.

For example, consider a menu control with large menu items, as follows:

Menu control with 3 large buttons

This is specified using the following XML fragment:

 <menu   id="menu" label="Menu with large items"   itemSize="large">
     <button id="button1" label="Button 1" imageMso="HappyFace"   />
     <button id="button2" label="Button 2"   imageMso="Paste" />
     <button id="button3" label="Button 3"   imageMso="Copy" />
 </menu>

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

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.

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.

showLabel (show label)

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

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.

title (title)

Specifies a string to be displayed as the title of the control.

The title and getTitle attributes are mutually exclusive. If neither attribute is specified, no title SHOULD be shown.

For example, consider a menu control with a title, as follows:

Menu control with a title

This is specified with the following XML fragment:

 <menu   id="menu" label="Menu With Title" title="Title   String">
     <button id="button" label="Button" />
 </menu>

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_MenuWithTitle">
    <xsd:complexContent>
    <xsd:extension base="CT_ControlBase">
    <xsd:sequence>
    <xsd:choice minOccurs="0" maxOccurs="1000">
    <xsd:group ref="EG_MenuControlsBase"/>
    <xsd:group ref="EG_MenuOrSplitButtonWithTitle"/>
    </xsd:choice>
    </xsd:sequence>
    <xsd:attributeGroup ref="AG_IDAttributes"/>
    <xsd:attribute name="itemSize" type="ST_ItemSize" use="optional"/>
    <xsd:attributeGroup ref="AG_Title"/>
    </xsd:extension>
    </xsd:complexContent>
 </xsd:complexType>