Search Menu

• May 08, 2024
• 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.OptionsSearchMenu.SearchItemShortcut = new BarShortcut((System.Windows.Forms.Keys.Control | System.Windows.Forms.Keys.F));

VB.NET

Imports DevExpress.XtraBars

RibbonControl1.ShowSearchItem = True
RibbonControl1.OptionsSearchMenu.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.
• AddHeader(String) – Adds a header to the search menu.
• AddItem(BarItem) – Adds an item to the search menu.
• ShowNoMatchesItem – Specifies whether to display the No matches found item.

Enable the RibbonOptionsSearchMenu.UseCustomRibbonSearch option to populate the search menu only through the CustomizeSearchMenu event.

The code below shows how to add a custom button to the menu and 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.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.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

Enter Key Behavior

The RibbonControl.SearchMenuEnterPressed event allows you to specify actions executed when a user presses Enter in the search box.

The following code snippet saves the user query, executes the first found item, and closes the Search Menu on the Enter key press:

C#

List<string> mruStrings = new List<string>();

void ribbonControl1_SearchMenuEnterPressed(object sender, RibbonSearchMenuEnterPressedEventArgs e) {
    if (!mruStrings.Contains(e.SearchString))
        mruStrings.Insert(0, e.SearchString);
    e.ExecuteFirstSearchResult();
    e.HideSearchMenu();
}

VB.NET

Private mruStrings As List(Of String) = New List(Of String)()

Private Sub ribbonControl1_SearchMenuEnterPressed(ByVal sender As Object, ByVal e As RibbonSearchMenuEnterPressedEventArgs)
    If Not mruStrings.Contains(e.SearchString) Then mruStrings.Insert(0, e.SearchString)
    e.ExecuteFirstSearchResult()
    e.HideSearchMenu()
End Sub

Localize the Menu

Use the Localization Service to add culture-specific messages to the search menu. The code sample below shows how to localize the message shown when the menu has no search query and the message displayed 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