Search Menu

• Nov 30, 2023
• 4 minutes to read

The ribbon can display a search box that allows users to search for a bar item by its caption or tags.

To display the search box, set the RibbonControl.ShowSearchItem property to true. For a Ribbon Form, use the SearchItemPosition property to display the Search box at the top of the form or in a page header, or to hide it from the Ribbon UI.

Note

Skinnable forms (XtraForm) cannot display the Search box at the top of the form. Setting the RibbonControl.SearchItemPosition to SearchItemPosition.Caption hides the search box.

The SearchItemShortcut property allows you to specify the shortcut used to focus the search box.

C#

using DevExpress.XtraBars;

ribbonControl1.ShowSearchItem = true;
ribbonControl1.SearchItemShortcut = new BarShortcut((System.Windows.Forms.Keys.Control | System.Windows.Forms.Keys.F));

VB.NET

Imports DevExpress.XtraBars

RibbonControl1.ShowSearchItem = True
RibbonControl1.SearchItemShortcut = New BarShortcut((System.Windows.Forms.Keys.Control Or System.Windows.Forms.Keys.F))

Note

In an MDI application, a child form’s search box is not added to the parent form when ribbons are merged. You should enable the search box on the parent and child forms individually.

Bar Items in the Menu

The search menu finds a bar item by its Caption. Use the SearchTags property to provide custom keywords that can be used to locate the bar item.

C#

using DevExpress.XtraBars;

BarButtonItem closeButton = new BarButtonItem();
closeButton.Caption = "Close";
closeButton.SearchTags = "Quit, Exit";
closeButton.ItemClick += CloseButton_ItemClick;
ribbonControl1.Items.Add(closeButton);
ribbonPageGroup1.ItemLinks.Add(closeButton);

private void CloseButton_ItemClick(object sender, ItemClickEventArgs e) {
    this.Close();
}

VB.NET

Imports DevExpress.XtraBars

Dim closeButton As New BarButtonItem()
closeButton.Caption = "Close"
closeButton.SearchTags = "Quit, Exit"
AddHandler closeButton.ItemClick, AddressOf CloseButton_ItemClick
ribbonControl1.Items.Add(closeButton)
ribbonPageGroup1.ItemLinks.Add(closeButton)

Private Sub CloseButton_ItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
    Me.Close()
End Sub

To hide a bar item in the search menu, set its VisibleInSearchMenu property to false.

C#

helpButton.VisibleInSearchMenu = false;

VB.NET

helpButton.VisibleInSearchMenu = False

Customize the Menu

The CustomizeSearchMenu event fires when the query in the search box changes, and allows you to customize the menu. The following properties provide information specific to this event:

• SearchString - gets the search query;
• Menu - gets the search menu (see PopupMenu). The Menu.ItemLinks collection contains all the available bar item links. An item link is visible or hidden based on the current search query.

The code below shows how to add a custom button to the menu, show an item regardless of the current query.

C#

using DevExpress.XtraBars;

ribbonControl1.CustomizeSearchMenu += RibbonControl1_CustomizeSearchMenu;

BarButtonItem shareButton;
BarButtonItem ShareButton {
    get {
        if (shareButton == null) {
            BarButtonItem shareButton = new BarButtonItem();
            shareButton.Caption = "Share";
            shareButton.ItemClick += (s, e) => MessageBox.Show("Share");
            shareButton.Manager = ribbonControl1.Manager;
            this.shareButton = shareButton;
        }
        return shareButton;
    }
}

private void ribbonControl1_CustomizeSearchMenu(object sender, DevExpress.XtraBars.Ribbon.RibbonSearchMenuEventArgs e) {
    // Add a custom button that is always visible.
    e.Menu.AddItem(ShareButton);
    // Show the Online Help command regardless of the current query.
    e.Menu.ItemLinks.Where(x => x.Item == biOnlineHelp).First().Visible = true;
}

VB.NET

Imports DevExpress.XtraBars

Private shareButton1 As BarButtonItem
Private ReadOnly Property ShareButton() As BarButtonItem
    Get
        If shareButton1 Is Nothing Then
            Dim share As New BarButtonItem()
            share.Caption = "Share"
            AddHandler share.ItemClick, Sub(s, e) MessageBox.Show("Share")
            shareButton1.Manager = ribbonControl1.Manager
            Me.shareButton1 = share
        End If
        Return shareButton1
    End Get
End Property

Private Sub ribbonControl1_CustomizeSearchMenu(ByVal sender As Object, ByVal e As Ribbon.RibbonSearchMenuEventArgs) _
    Handles ribbonControl1.CustomizeSearchMenu
    ' Add a custom button that is always visible.
    e.Menu.AddItem(ShareButton)
    ' Show the Online Help command regardless of the current query.
    e.Menu.ItemLinks.Where(Function(x) x.Item Is biOnlineHelp).First().Visible = True
End Sub

Localize the Menu

Use the Localization Service to add culture-specific messages to the search menu. The code below shows how to localize the message shown when the menu has no search query and the message shown when no matches are found.

C#

using DevExpress.XtraBars.Localization;

BarLocalizer.Active = new CustomBarLocalizer();

public class CustomBarLocalizer : BarLocalizer {
    public override string GetLocalizedString(BarString id) {
        if (id == BarString.RibbonSearchItemNullText)
            return "Suche";
        if (id == BarString.RibbonSearchItemNoMatchesFound)
            return "Keine Treffer gefunden";
        return base.GetLocalizedString(id);
    }
}

VB.NET

Imports DevExpress.XtraBars.Localization

BarLocalizer.Active = New CustomBarLocalizer()

Public Class CustomBarLocalizer
    Inherits BarLocalizer

    Public Overrides Function GetLocalizedString(ByVal id As BarString) As String
        If id = BarString.RibbonSearchItemNullText Then
            Return "Suche"
        End If
        If id = BarString.RibbonSearchItemNoMatchesFound Then
            Return "Keine Treffer gefunden"
        End If
        Return MyBase.GetLocalizedString(id)
    End Function
End Class