2.2.1 box (Box Grouping Container)

  • Article

This element specifies a grouping container control that can be used to align controls vertically or horizontally. Box elements can be nested to create complex UI layouts.

For example, consider a group of controls that are laid out horizontally, as follows:

Controls grouped horizontally

Figure 1: Controls grouped horizontally

This layout is specified using the following XML fragment:

 <box id="box" boxStyle="horizontal">
   <button id="button1" label="Button 1" imageMso="HappyFace" />
   <button id="button2" label="Button 2" imageMso="HappyFace" />
 </box>

This is contrasted to the default vertical layout that is used if the box element is not specified.

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 child elements of this element.

Child Elements

Section

box (Box Grouping Container)

2.2.1

button (Button)

2.2.2

buttonGroup (Button Grouping Container)

2.2.5

checkBox (Check Box)

2.2.6

comboBox (Combo Box)

2.2.7

control (Control Clone)

2.2.12

dropDown (Drop-down Control)

2.2.17

dynamicMenu (Dynamic Menu)

2.2.19

editBox (Edit Box)

2.2.20

gallery (Gallery)

2.2.21

labelControl (Text Label)

2.2.25

menu (Menu)

2.2.28

splitButton (Split Button)

2.2.38

toggleButton (Toggle Button)

2.2.43

The following table summarizes the attributes of this element.

Attributes

Description

boxStyle (box style)

Specifies the layout direction for the child controls inside of the box element.

If this attribute is omitted, the child controls SHOULD be laid out horizontally.

For example, consider a group of controls to be laid out vertically. This is specified using the following XML:

 <box   id="box" boxStyle="vertical">
     …
 </box>

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

getVisible (getVisible callback)

Specifies the name of a callback function that is 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 and idQ attributes are mutually exclusive. At least one of these attributes is to 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.

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 is to 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 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 id 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, 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.

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 to be 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_Box">
    <xsd:group ref="EG_Controls" minOccurs="0" maxOccurs="1000"/>
    <xsd:attributeGroup ref="AG_IDCustom"/>
    <xsd:attributeGroup ref="AG_Visible"/>
    <xsd:attributeGroup ref="AG_PositionAttributes"/>
    <xsd:attribute name="boxStyle" type="ST_BoxStyle" use="optional"/>
 </xsd:complexType>