2.2.30 menuSeparator (Menu Separator)

  • Article

This element specifies a horizontal separator line in a menu control.  Menu separators can optionally have title strings, which SHOULD display as headers in the menu.

For example, consider a menu with a separator in between two of its items, as follows:

Menu control with separator

Figure 19: Menu control with separator

This is specified using the following XML fragment:

 <menu id="menu" label="Menu" imageMso="HappyFace" >
   <button id="button1" label="Button 1" imageMso="FileSave" />
   <menuSeparator id="separator" />
   <button id="button2" label="Button 2" imageMso="Bold" />
 </menu>

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

Parent Elements

menu (section 2.2.28); menu (section 2.2.26); menu (section 2.2.29); menu (section 2.2.27); officeMenu (section 2.2.31)

The following table summarizes the attributes of this element.

Attributes

Description

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.

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 and idQ 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.

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 and idQ 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.

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.

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.

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

 <xsd:complexType name="CT_MenuSeparator">
    <xsd:attributeGroup ref="AG_IDCustom"/>
    <xsd:attributeGroup ref="AG_PositionAttributes"/>
    <xsd:attributeGroup ref="AG_Title"/>
 </xsd:complexType>