Bar Item Links

Dec 21, 2023
4 minutes to read

All commands end-users see within toolbars are item links. An item link is a visual representation of an existing bar item.

This tutorial requires the sample application from the Add Bar Items To Toolbars tutorial to demonstrate the “item/item link” concept. Open the main menu’s “File” sub-item, select the “New” button and press Delete. The button (item link) disappears, but the source item still remains. Right-click the BarManager component and choose the “Customize” option.
Copy the “New” and “Open” buttons to a toolbar by dragging them from the “File” sub-menu while pressing the CTRL key. You can also drag bar items from the Customization Window dialog.
Right-click the toolbar’s “New” bar button link and change its style to “Image and Text”. You can utilize the BarItemLink.PaintStyle property to do the same in code.
Right-click the same link again and choose the “Change User Caption” option, then rename your link to “New Document”. Modify the BarItemLink.UserCaption property to do the same in code.
Open the ”File” sub-menu to check that the “New” button is unaffected. This means you now have two links to the same bar item with the same functionality, but with different paint styles and captions. However, if you utilize a smart link tag to change a caption, you rename the underlying bar item which changes all other item links that have no custom user captions.

Additional Item and Link Settings

BarItemLink.Visible and BarItemLink.Enabled - manage visibility and availability for bar item links.
BarItemLink.BeginGroup - if set to true , the link displays a separator before itself. In the figure below, the “Exit” button link starts a new group.
BarItemLink.MostRecentlyUsed - specifies whether or not this link is in the recently used items.
BarButtonItem.ButtonStyle - allows you to turn a regular push button into a check button and/or provide a drop-down menu for it.
BarBaseButtonItem.GroupIndex - allows you to combine multiple check button links into a radio group. In these groups, a pressed button automatically elevates when a user presses another button that belongs to the same group.
BarItem.Category - gets or sets the item category. Item categories organize bar items into logical groups (“Format”, “Edit”, “Tables”, etc.). Categories do not affect item link behavior or appearance and are only visible to end-users when they work with the Customization Window.

Example

The following example demonstrates how to display bar item links for bar items in the specified category:

C#
VB.NET

csharp

using DevExpress.XtraEditors;

void AddBarItemLinksFromCategory(string categoryName) {
    bm.BeginUpdate();
    BarManagerCategory bmCategory = bm.Categories[categoryName];
    if(bmCategory == null) return;
    for(int i = 0; i < bmCategory.GetItemCount(); i++)
        bm.Bars[0].ItemLinks.Add(bmCategory.GetItem(i));
    bm.EndUpdate();
}

Imports DevExpress.XtraEditors

Private Sub AddBarItemLinksFromCategory(ByVal categoryName As String)
    bm.BeginUpdate()
    Dim bmCategory As BarManagerCategory = bm.Categories(categoryName)
    If bmCategory Is Nothing Then
        Return
    End If
    For i As Integer = 0 To bmCategory.GetItemCount() - 1
        bm.Bars(0).ItemLinks.Add(bmCategory.GetItem(i))
    Next i
    bm.EndUpdate()
End Sub