Page Groups

Items (commands) in ribbon pages can be logically divided into groups. Ribbon page groups are delimited by vertical separators. They display captions at the bottom when the Classic command layout is applied. The following image demonstrates the File, Clipboard, Font and Styles page groups displayed within the Home page:

Define and Access Ribbon Page Groups

Ribbon page groups are encapsulated by RibbonPageGroup class objects. In code-behind, you can create, access and modify page groups using the RibbonPage.Groups collection. To define page groups in XAML, add RibbonPageGroup objects between the <RibbonPage> start and end tags.

<mxr:RibbonPage Header="Home" KeyTip="H" Name="pageHome">
    <mxr:RibbonPageGroup Header="File" IsHeaderButtonVisible="True">
        <!-- ... -->
    </mxr:RibbonPageGroup>
    <mxr:RibbonPageGroup Header="Clipboard" IsHeaderButtonVisible="True">
        <!-- ... -->
    </mxr:RibbonPageGroup>
    <mxr:RibbonPageGroup Header="Font" IsHeaderButtonVisible="True">
        <!-- ... -->
    </mxr:RibbonPageGroup>
    <!-- ... -->
</mxr:RibbonPageGroup>

You can also use the RibbonPage.GroupsSource property to create page groups from a collection of business objects in a View Model. A corresponding data template should define a RibbonPageGroup object and initialize its settings from a business object.

Page Group Header

When the Classic command layout is applied, page groups have headers at the bottom. A group header displays a caption (RibbonPageGroup.Header) and a header button.

A click on the header button has no default action. You can associate an action with the header button as follows:

• Handle the RibbonPageGroup.HeaderButtonClick or RibbonPageGroup.HeaderButtonPress event. For instance, your event handler can display a dialog or menu that brings up more settings related to the group.

  The HeaderButtonClick event is raised after the left mouse button is pressed and released over the header button. The HeaderButtonPress event is raised immediately after a user presses any mouse button over the header button.

• Assign a command to the RibbonPageGroup.HeaderButtonCommand property. You can specify an optional command parameter using the RibbonPageGroup.HeaderButtonCommandParameter property.

Use the RibbonPageGroup.IsHeaderButtonVisible property to hide the header button.

Page Group Content

A page group displays a set of closely related ribbon items. Ribbon items are buttons, check buttons, button groups, sub-menus, in-place editors, galleries and more. See the following topics for more information: Ribbon Items and Galleries

To populate a ribbon page group with items, use the RibbonPageGroup.Items collection. In XAML, you can define items between the <RibbonPageGroup> start and end tags.

 <mxr:RibbonPage Header="Home" KeyTip="H">
    <mxr:RibbonPageGroup Header="File" IsHeaderButtonVisible="True">
        <mxb:ToolbarButtonItem Header="New" KeyTip="N" Glyph="{x:Static icons:Basic.Docs_Add}"
                               mxr:RibbonControl.DisplayMode="Large"/>
        <mxb:ToolbarButtonItem Header="Open" KeyTip="O"
                               Glyph="{x:Static icons:Basic.Folder_Open}" />
        <mxb:ToolbarButtonItem Header="Exit" KeyTip="E"
                               Glyph="{x:Static icons:Basic.Remove}" />
    </mxr:RibbonPageGroup>
    <mxr:RibbonPageGroup Header="Font" IsHeaderButtonVisible="True">
        <mxb:ToolbarCheckItemGroup ShowSeparator="True">
            <mxb:ToolbarCheckItem Header="Bold" KeyTip="B" Glyph="{x:Static icons:Basic.Font_Bold}" />
            <mxb:ToolbarCheckItem Header="Italic" KeyTip="I" Glyph="{x:Static icons:Basic.Font_Italic}" />
            <mxb:ToolbarCheckItem Header="Underline" KeyTip="U" Glyph="{x:Static icons:Basic.Font_Underline}"  />
        </mxb:ToolbarCheckItemGroup>
       <!-- ... -->
    </mxr:RibbonPageGroup>
</mxr:RibbonPage>

You can also use the RibbonPageGroup.ItemsSource property to create items from a collection of business objects in a View Model. Corresponding data templates should define ribbon items and initialize their settings from underlying business objects.

Page Group Image

When a Ribbon control is resized, the adaptive layout feature may collapse specific page groups. In the collapsed state, a group's items are displayed in a dropdown window.

You can use the RibbonPageGroup.Glyph property to display an image in a collapsed group's button:

xmlns:icons="https://schemas.eremexcontrols.net/avalonia/icons"
<mxr:RibbonPageGroup Header="File" Glyph="{x:Static icons:Basic.Doc}">

Layout of Items in Page Groups

Adaptive Layout

The Ribbon control supports the adaptive layout feature, which adjusts the layout of items in ribbon page groups when the Ribbon control is resized.

Combining Items in Groups

You can combine sets or ribbon items in non-breaking groups (ToolbarItemGroup or ToolbarCheckItemGroup). These groups function as a whole. They are not broken by the adaptive layout feature. Only an entire group can be collapsed when the Ribbon is resized, not its individual items.

For instance, in the animation above the , and items are combined in a non-breaking group.

Item Images

When the Classic command layout is applied, the adaptive layout functionality also adjusts the display size of items as you resize the ribbon — from large to small with text to small glyphs, and backwards.

The RibbonControl.DisplayMode attached property allows you to specify supported display modes for ribbon items in ribbon page groups in the Classic command layout. You can force an item to use only large images, small images, small images with text, or a combination of these display modes.

<mxb:ToolbarButtonItem Header="Open" KeyTip="O" mxr:RibbonControl.DisplayMode="Large"
                          Glyph="{x:Static icons:Basic.Folder_Open}" />

See the following topic for more information: Adaptive Glyph Size in the Classic Command Layout

Related API

• AllowCollapse — Specifies whether a group can be collapsed when the Ribbon control's width is reduced.
• IsCollapsed — Returns if the current group is currently collapsed.

Arrange Items in Two or Three Rows in Page Groups

If a page group is wide enough, small commands in that group are arranged in two rows. If the group width is reduced, the commands are arranged in three rows, creating a more compact layout.

In specific cases, you may need to forcibly arrange items in two or three rows, as a column. This can be accomplished as follows:

• Use non-breaking groups (ToolbarItemGroup or ToolbarCheckItemGroup) to combine items that need to be displayed in separate rows. For instance, if you need to create three rows of items, combine the items in three non-breaking groups.
• Set the RibbonPageGroup.ItemGroupLayoutMode attached property for the first non-breaking group to Layout2Rows or Layout3Rows (the property's default value is AdaptiveLayout). This property specifies the number of rows in which the current and subsequent non-breaking groups are arranged.
• Optionally, add a ToolbarSeparatorItem object after the last non-breaking group in the created column. This prevents other small commands to be displayed in line with the last non-breaking group in the column.

Example

The following example shows how to forcibly arrange items in three rows by using non-breaking groups and the RibbonPageGroup.ItemGroupLayoutMode attached property.

• The first row in this example should display the Find text box and Find button. These items are combined in a non-breaking group (ToolbarItemGroup). The RibbonPageGroup.ItemGroupLayoutMode property is set to Layout3Rows for this ToolbarItemGroup object to indicate that the current and subsequent non-breaking groups should form three rows.
• The second row should display only the Replace text box. This item also needs to be combined in a separate non-breaking group (ToolbarItemGroup).
• The third row should display the Match case, Match whole word and Use regular expressions check buttons. They are combined in a ToolbarCheckItemGroup group, named groupFindProperties.

For demonstration purposes, two additional buttons () are added after the groupFindProperties group. These buttons are combined in a separate group (groupAdvProperties).

The Ribbon's item layouting mechanism tries to keep the arrangement of neighboring non-breaking groups compact. That's why the groupAdvProperties group is positioned in line with the groupFindProperties group (see the image above). You can insert a separator (a ToolbarSeparatorItem object) before the groupAdvProperties group, to forcibly move it to a new column, as demonstrated in the image below:

<mxr:RibbonPageGroup Header="Find" Name="groupFind" >
    <mxb:ToolbarItemGroup mxr:RibbonPageGroup.ItemGroupLayoutMode="Layout3Rows">
        <mxb:ToolbarEditorItem Header="Find      " EditorWidth="150" >
            <mxb:ToolbarEditorItem.EditorProperties>
                <mxe:TextEditorProperties/>
            </mxb:ToolbarEditorItem.EditorProperties>
        </mxb:ToolbarEditorItem>
        <mxb:ToolbarButtonItem 
            Header="Find"
            Glyph="{SvgImage 'avares://DemoCenter/Assets/arrow-right.svg'}"
            Command="{Binding FindCommand}"/>
    </mxb:ToolbarItemGroup>

    <mxb:ToolbarItemGroup>
        <mxb:ToolbarEditorItem Header="Replace" EditorWidth="150" >
            <mxb:ToolbarEditorItem.EditorProperties>
                <mxe:TextEditorProperties/>
            </mxb:ToolbarEditorItem.EditorProperties>
        </mxb:ToolbarEditorItem>
    </mxb:ToolbarItemGroup>

    <mxb:ToolbarCheckItemGroup Name="groupFindProperties">
        <mxb:ToolbarCheckItem
            Header="Match case"
            IsChecked="{Binding IsMatchCase}"
            Glyph="{SvgImage 'avares://DemoCenter/Assets/match-case.svg'}"/>
        <mxb:ToolbarCheckItem 
            Header="Match whole word"
            IsChecked="{Binding IsMatchWholeWord}"
            Glyph="{SvgImage 'avares://DemoCenter/Assets/match-whole-word.svg'}"/>
        <mxb:ToolbarCheckItem
            Header="Use regular expressions"
            IsChecked="{Binding IsUseRegExp}"
            Glyph="{SvgImage 'avares://DemoCenter/Assets/match-regexp.svg'}"/>
    </mxb:ToolbarCheckItemGroup>

    <!--<mxb:ToolbarSeparatorItem/>-->

    <mxb:ToolbarItemGroup Name="groupAdvProperties">
        <mxb:ToolbarButtonItem
            Header="Add search folder"
            mxr:RibbonControl.DisplayMode="SmallGlyph"
            Glyph="{SvgImage 'avares://DemoCenter/Assets/add-folder.svg'}"/>
        <mxb:ToolbarButtonItem
            Header="Open expression manager"
            mxr:RibbonControl.DisplayMode="SmallGlyph"
            Glyph="{SvgImage 'avares://DemoCenter/Assets/manager.svg'}"/>
    </mxb:ToolbarItemGroup>
</mxr:RibbonPageGroup>