What are Bar Items and Bar Item Links

• May 22, 2020
• 3 minutes to read

 

What are Bar Items and Bar Item Links

If you look at Ribbon Page Groups, status bar or the Quick Access Toolbar, you may see various visual elements (command buttons, static text, editors, menus, galleries, etc.), each of which provides specific functionality.

If you need to add a command button, static text or any other element to a RibbonControl, RibbonStatusBarControl, any bar or popup menu, you need to create a specific bar item. Bar items provide multiple display and behavior options that can be customized: the content, large and small images, a command and event that occur when the corresponding elements are clicked, etc. For instance, to add a regular button to a bar, you need to create a BarButtonItem object. Its Content and Glyph properties allow you to assign a specific content and image to the button. The item's BarItem.ItemClick event allows you to implement the button's functionality. You can specify a command for a BarItem via the BarItem.Command property. Note, however, that bar items are non-visual components.

All the visual elements (command buttons, submenus, static text, etc.) displayed within Ribbon controls, bars, etc., are bar item links. A bar item link refers to a specific bar item, so it has all the necessary information to draw itself onscreen. You can create multiple links to the same bar item and display them in different places. For instance, you can display links that refer to the same BarButtonItem on the Quick Access Toolbar and on a RibbonPage at the same time. Clicking on either of them will invoke the same event handler/command that is assigned to the BarButtonItem.

In XAML, the RibbonControl and RibbonStatusBarControl controls must be defined between the start and end BarManager tags. The BarManager here represents storage of bar items. All the bar items you want to use in the Ribbon controls must be defined in the BarManager's BarManager.Items collection.

Once you defined required bar items in the BarManager, you can create links to the bar items in the Ribbon objects (Ribbon Page Groups, Ribbon Status Bar and Ribbon Quick Access Toolbar).

There are multiple bar item types that can be used to add various elements to Ribbon controls. For instance, a BarButtonItem object allows you to add a button, while a BarSubItem object is used to add a submenu, etc. For a complete list of bar items, see The List of Bar Items and Links.

Example

The following code defines a BarButtonItem (named "New") in the BarManager.Items collection and then adds a link to this item to RibbonControl. The link is added to the File group in the Home page.

XAML

<dxb:BarManager Name="barManager">
    <dxb:BarManager.Items>
        <dxb:BarButtonItem Name="bNew" Content="New" 
                           Glyph="pack://application:,,,/Images/new-16x16.png" 
                           LargeGlyph="pack://application:,,,/Images/new-32x32.png"  
                           ItemClick="bNew_ItemClick"
                           />
    ...
    </dxb:BarManager.Items>

    <DockPanel>
        <dxr:RibbonControl x:Name="RibbonControl" DockPanel.Dock="Top" >
            <dxr:RibbonDefaultPageCategory>
                <dxr:RibbonPage Caption="Home">
                    <dxr:RibbonPageGroup Name="pFile" Caption="File" >
                        <dxb:BarItemLink BarItemName="bNew" RibbonStyle="Large"/>
                        ...
                    </dxr:RibbonPageGroup>
                </dxr:RibbonPage>
            </dxr:RibbonDefaultPageCategory>
        </dxr:RibbonControl>
    </DockPanel>