Menus

• Feb 20, 2023
• 10 minutes to read

Many DevExpress controls have built-in context-dependent popup menus. You can customize them or replace with custom menus in code. The built-in context menus are encapsulated by DXPopupMenu class objects.

The PopupMenu component allows you to create a non-context-dependent popup menu for a control. Unlike the DXPopupMenu, the PopupMenu component provides design-time customization tools.

The current document covers information on how to customize built-in context-dependent popup menus for the DevExpress controls.

Popup Menu Customization Settings

Specific DevExpress .NET controls contain properties to enable/disable predefined items in their built-in context menus. Below is a list of these controls and corresponding properties:

• Data Grid - See members provided by the GridView.OptionsMenu object.
• Tree List - See members provided by the TreeList.OptionsMenu object.
• PivotGridControl - See members provided by the PivotGridControl.OptionsMenu object.
• VGridControl, PropertyGridControl - See members provided by the VGridControlBase.OptionsMenu object.
• PictureEdit - See PictureEdit.Properties.ShowEditMenuItem, PictureEdit.Properties.ShowCameraMenuItem and PictureEdit.Properties.ShowZoomSubMenu.

Example - Enable Predefined Menu Item

The following code enables the “Show Footer” menu item via the GridView.OptionsMenu.ShowFooterItem property.

C#

gridView1.OptionsMenu.ShowFooterItem = true;

VB.NET

GridView1.OptionsMenu.ShowFooterItem = True

Popup Menu Customization Events

DevExpress .NET controls provide events to perform advanced menu customization tasks:

• Customize the order, visibility and text of all predefined menu items.
• Add custom menu items.
• Perform custom actions when a user clicks predefined menu items.

Control	Menu Customization Events
Data Grid See Popup Menus.	GridView.PopupMenuShowing and GridView.GridMenuItemClick
Tree List See Context Menus.	TreeList.PopupMenuShowing and TreeList.TreeListMenuItemClick
PivotGridControl	PivotGridControl.PopupMenuShowing and PivotGridControl.MenuItemClick
LayoutControl See Context Menu.	LayoutControl.PopupMenuShowing
VGridControl, PropertyGridControl	VGridControlBase.PopupMenuShowing
DocumentManager	BaseView.PopupMenuShowing
DockManager	DockManager.PopupMenuShowing
SpellChecker	SpellChecker.PopupMenuShowing
SchedulerControl	SchedulerControl.PopupMenuShowing
RichEditControl	RichEditControl.PopupMenuShowing
FilterControl	FilterControl.PopupMenuShowing
PictureEdit	PopupMenuShowing,
Text Editors (TextEdit descendants)	editor.Properties.BeforeShowMenu

When you handle any of these events, you can access the currently processed menu from the e.Menu event argument. The e.Menu.Items property returns a collection of menu items, encapsulated by the following objects:

• DXMenuItem
• DXMenuCheckItem
• DXSubMenuItem
• DXButtonGroupItem
• DXEditMenuItem

Example - Customize Default Menu Items

The following code handles the GridView.PopupMenuShowing event to change predefined commands in the Data Grid’s Column Header Menu:

• Captions of the “Sort Ascending” and “Sort Descending” commands are replaced with custom strings.
• A few commands are hidden.
• Two “Best Fit” commands are disabled.

C#

using DevExpress.Utils.Menu;
using DevExpress.XtraEditors;
using DevExpress.XtraGrid.Localization;
using DevExpress.XtraGrid.Views.Grid;

private void gridView1_PopupMenuShowing(object sender, PopupMenuShowingEventArgs e) {
    if(e.MenuType == GridMenuType.Column) {
        string sortAsc = "A to Z";
        string sortDesc = "Z to A";
        if (e.HitInfo.Column.ColumnType == typeof(DateTime)) {
            sortAsc = "Old to New";
            sortDesc = "New to Old";
        }
        DXMenuItem itemAsc = e.Menu.Find(GridStringId.MenuColumnSortAscending); // "Sort Ascending"
        if (itemAsc != null)
            itemAsc.Caption = sortAsc;

        DXMenuItem itemDesc = e.Menu.Find(GridStringId.MenuColumnSortDescending); // "Sort Descending"
        if (itemDesc != null)
            itemDesc.Caption = sortDesc;

        e.Menu.Hide(GridStringId.MenuFooterHide); //"Hide Footer"
        e.Menu.Hide(GridStringId.MenuColumnFilterEditor); // "Filter Editor..."
        e.Menu.Hide(GridStringId.MenuColumnFindFilterShow); // "Show Find Panel"
        e.Menu.Hide(GridStringId.MenuColumnFindFilterHide); // "Hide Find Panel"
        e.Menu.Hide(GridStringId.MenuColumnAutoFilterRowHide); // "Hide Auto Filter Row"
        e.Menu.Hide(GridStringId.MenuColumnAutoFilterRowShow); // "Show Auto Filter Row"

        DXMenuItem itemBestFit = e.Menu.Find(GridStringId.MenuColumnBestFit); // "Best Fit"
        if (itemBestFit != null)
            itemBestFit.Enabled = false;

        DXMenuItem itemBestFitAll = e.Menu.Find(GridStringId.MenuColumnBestFitAllColumns); // "Best Fit All Columns"
        if (itemBestFitAll != null)
            itemBestFitAll.Enabled = false;
    }
}

VB.NET

Imports DevExpress.Utils.Menu
Imports DevExpress.XtraEditors
Imports DevExpress.XtraGrid.Localization
Imports DevExpress.XtraGrid.Views.Grid

Private Sub gridView1_PopupMenuShowing(ByVal sender As Object, ByVal e As PopupMenuShowingEventArgs) Handles GridView1.PopupMenuShowing
    If e.MenuType = GridMenuType.Column Then
        Dim sortAsc As String = "A to Z"
        Dim sortDesc As String = "Z to A"

        If e.HitInfo.Column.ColumnType = GetType(DateTime) Then
            sortAsc = "Old to New"
            sortDesc = "New to Old"
        End If

        Dim itemAsc As DXMenuItem = e.Menu.Find(GridStringId.MenuColumnSortAscending)
        If itemAsc IsNot Nothing Then itemAsc.Caption = sortAsc
        Dim itemDesc As DXMenuItem = e.Menu.Find(GridStringId.MenuColumnSortDescending)
        If itemDesc IsNot Nothing Then itemDesc.Caption = sortDesc
        e.Menu.Hide(GridStringId.MenuFooterHide)
        e.Menu.Hide(GridStringId.MenuColumnFilterEditor)
        e.Menu.Hide(GridStringId.MenuColumnFindFilterShow)
        e.Menu.Hide(GridStringId.MenuColumnFindFilterHide)
        e.Menu.Hide(GridStringId.MenuColumnAutoFilterRowHide)
        e.Menu.Hide(GridStringId.MenuColumnAutoFilterRowShow)
        Dim itemBestFit As DXMenuItem = e.Menu.Find(GridStringId.MenuColumnBestFit)
        If itemBestFit IsNot Nothing Then itemBestFit.Enabled = False
        Dim itemBestFitAll As DXMenuItem = e.Menu.Find(GridStringId.MenuColumnBestFitAllColumns)
        If itemBestFitAll IsNot Nothing Then itemBestFitAll.Enabled = False
    End If
End Sub

Example - Add Custom Menu Items

This example demonstrates how to handle the GridView.PopupMenuShowing event to create a custom popup menu and display it within the WinForms Data Grid control.

The menu is displayed when the user right-clicks within a data row or group row. The menu includes:

• Rows submenu with the Delete this row item that calls the ColumnView.DeleteRow method.
• Cell Merging check item that toggles the GridOptionsView.AllowCellMerge option.

Note

The example displays SVG images within menu items. Drop the SvgImageCollection component onto your Form (svgImageCollection1) and add two SVG icons to the collection (at design time).

C#

using System;
using System.Windows.Forms;
using DevExpress.XtraGrid.Views.Grid;
using DevExpress.Utils.Menu;
using DevExpress.XtraEditors;

namespace DXApplication8 {
    public partial class Form1 : XtraForm {
        public Form1() {
            InitializeComponent();
            gridView1.PopupMenuShowing += GridView1_PopupMenuShowing;
        }

        private void GridView1_PopupMenuShowing(object sender, PopupMenuShowingEventArgs e) {
            GridView view = sender as GridView;
            if (e.MenuType == GridMenuType.Row) {
                int rowHandle = e.HitInfo.RowHandle;
                // Deletes existing menu items, if any.
                e.Menu.Items.Clear();
                // Adds the 'Rows' submenu with the 'Delete Row' command to the context menu.
                e.Menu.Items.Add(CreateSubMenuRows(view, rowHandle));
                // Adds the 'Cell Merging' check item to the context menu.
                DXMenuItem item = CreateMenuItemCellMerging(view, rowHandle);
                item.BeginGroup = true;
                e.Menu.Items.Add(item);
            }
        }
        DXMenuItem CreateSubMenuRows(GridView view, int rowHandle) {
            DXSubMenuItem subMenu = new DXSubMenuItem("Rows");
            string deleteRowsCommandCaption;
            if (view.IsGroupRow(rowHandle))
                deleteRowsCommandCaption = "&Delete rows in this group";
            else
                deleteRowsCommandCaption = "&Delete this row";

            // Drop the 'svgImageCollection' component onto the Form1 and add two SVG icons to the collection.
            DXMenuItem menuItemDeleteRow = new DXMenuItem(deleteRowsCommandCaption, new EventHandler(OnDeleteRowClick), svgImageCollection1[1], DXMenuItemPriority.Normal);
            menuItemDeleteRow.Tag = new RowInfo(view, rowHandle);
            menuItemDeleteRow.Enabled = view.IsDataRow(rowHandle) || view.IsGroupRow(rowHandle);
            subMenu.Items.Add(menuItemDeleteRow);
            return subMenu;
        }

        DXMenuCheckItem CreateMenuItemCellMerging(GridView view, int rowHandle) {
            DXMenuCheckItem checkItem = new DXMenuCheckItem("Cell &Merging",
              view.OptionsView.AllowCellMerge, null, new EventHandler(OnCellMergingClick));
            checkItem.Tag = new RowInfo(view, rowHandle);
            checkItem.ImageOptions.SvgImage = svgImageCollection1[0];
            return checkItem;
        }

        void OnDeleteRowClick(object sender, EventArgs e) {
            DXMenuItem menuItem = sender as DXMenuItem;
            RowInfo ri = menuItem.Tag as RowInfo;
            if (ri != null) {
                string message = menuItem.Caption.Replace("&", "");
                if (XtraMessageBox.Show(message + " ?", "Confirm the operation", MessageBoxButtons.YesNo) != DialogResult.Yes)
                    return;
                ri.View.DeleteRow(ri.RowHandle);
            }
        }

        void OnCellMergingClick(object sender, EventArgs e) {
            DXMenuCheckItem item = sender as DXMenuCheckItem;
            RowInfo info = item.Tag as RowInfo;
            info.View.OptionsView.AllowCellMerge = item.Checked;
        }

        class RowInfo {
            public RowInfo(GridView view, int rowHandle) {
                RowHandle = rowHandle;
                View = view;
            }
            public GridView View;
            public int RowHandle;
        }
    }
}

VB.NET

Imports System
Imports System.Windows.Forms
Imports DevExpress.XtraGrid.Views.Grid
Imports DevExpress.Utils.Menu
Imports DevExpress.XtraEditors

Namespace DXApplication8
    Partial Public Class Form1
        Inherits XtraForm

        Public Sub New()
            InitializeComponent()
            AddHandler gridView1.PopupMenuShowing, AddressOf GridView1_PopupMenuShowing
        End Sub

        Private Sub GridView1_PopupMenuShowing(ByVal sender As Object, ByVal e As PopupMenuShowingEventArgs)
            Dim view As GridView = TryCast(sender, GridView)
            If e.MenuType = GridMenuType.Row Then
                Dim rowHandle As Integer = e.HitInfo.RowHandle
                ' Deletes existing menu items, if any.
                e.Menu.Items.Clear()
                ' Adds the 'Rows' submenu with the 'Delete Row' command to the context menu.
                e.Menu.Items.Add(CreateSubMenuRows(view, rowHandle))
                ' Adds the 'Cell Merging' check item to the context menu.
                Dim item As DXMenuItem = CreateMenuItemCellMerging(view, rowHandle)
                item.BeginGroup = True
                e.Menu.Items.Add(item)
            End If
        End Sub
        Private Function CreateSubMenuRows(ByVal view As GridView, ByVal rowHandle As Integer) As DXMenuItem
            Dim subMenu As New DXSubMenuItem("Rows")
            Dim deleteRowsCommandCaption As String
            If view.IsGroupRow(rowHandle) Then
                deleteRowsCommandCaption = "&Delete rows in this group"
            Else
                deleteRowsCommandCaption = "&Delete this row"
            End If

            ' Drop the 'svgImageCollection' component onto the Form1 and add two SVG icons to the collection.
            Dim menuItemDeleteRow As New DXMenuItem(deleteRowsCommandCaption, New EventHandler(AddressOf OnDeleteRowClick), svgImageCollection1(1), DXMenuItemPriority.Normal)
            menuItemDeleteRow.Tag = New RowInfo(view, rowHandle)
            menuItemDeleteRow.Enabled = view.IsDataRow(rowHandle) OrElse view.IsGroupRow(rowHandle)
            subMenu.Items.Add(menuItemDeleteRow)
            Return subMenu
        End Function

        Private Function CreateMenuItemCellMerging(ByVal view As GridView, ByVal rowHandle As Integer) As DXMenuCheckItem
            Dim checkItem As New DXMenuCheckItem("Cell &Merging", view.OptionsView.AllowCellMerge, Nothing, New EventHandler(AddressOf OnCellMergingClick))
            checkItem.Tag = New RowInfo(view, rowHandle)
            checkItem.ImageOptions.SvgImage = svgImageCollection1(0)
            Return checkItem
        End Function

        Private Sub OnDeleteRowClick(ByVal sender As Object, ByVal e As EventArgs)
            Dim menuItem As DXMenuItem = TryCast(sender, DXMenuItem)
            Dim ri As RowInfo = TryCast(menuItem.Tag, RowInfo)
            If ri IsNot Nothing Then
                Dim message As String = menuItem.Caption.Replace("&", "")
                If XtraMessageBox.Show(message & " ?", "Confirm the operation", MessageBoxButtons.YesNo) <> DialogResult.Yes Then
                    Return
                End If
                ri.View.DeleteRow(ri.RowHandle)
            End If
        End Sub

        Private Sub OnCellMergingClick(ByVal sender As Object, ByVal e As EventArgs)
            Dim item As DXMenuCheckItem = TryCast(sender, DXMenuCheckItem)
            Dim info As RowInfo = TryCast(item.Tag, RowInfo)
            info.View.OptionsView.AllowCellMerge = item.Checked
        End Sub

        Private Class RowInfo
            Public Sub New(ByVal view As GridView, ByVal rowHandle As Integer)
                Me.RowHandle = rowHandle
                Me.View = view
            End Sub
            Public View As GridView
            Public RowHandle As Integer
        End Class
    End Class
End Namespace

Tip

You can also create a custom DXPopupMenu menu and assign it to the e.Menu event argument.

Display Modes

A DXPopupMenu object can be displayed as a regular menu, popup bar or RibbonMiniToolbar. To specify the menu’s display mode, set the DXPopupMenu.MenuViewType property to the required enumeration value and use a corresponding menu manager.

When you invoke a DXPopupMenu manually in code, you can specify a menu manager via the popup menu’s IDXDropDownControl.Show method. For built-in menus in DevExpress controls, you can specify a menu manager via a control’s MenuManager property.

The following menu managers are available.

• SkinMenuManager - Displays a DXPopupMenu as a regular menu.

  

  Note

  SkinMenuManager presents DXEditMenuItem objects as text labels without edit boxes. DXButtonGroupItem objects are displayed as sub-menus.

  C#

  // Display a DXPopupMenu as a regular menu
  UserLookAndFeel lf = UserLookAndFeel.Default;
  Control parentControl = this;
  Point pt;
  DXPopupMenu dxPopupMenu = new DXPopupMenu();
  //...
  dxPopupMenu.MenuViewType = MenuViewType.Menu;
  dxPopupMenu.ShowPopup(parentControl, pt);
  //or
  ((IDXDropDownControl)dxPopupMenu).Show(new SkinMenuManager(lf), parentControl, pt);
  

  VB.NET

  ' Display a DXPopupMenu as a regular menu
  Dim lf As UserLookAndFeel = UserLookAndFeel.Default
  Dim parentControl As Control = Me
  Dim pt As Point
  Dim dxPopupMenu As DXPopupMenu = New DXPopupMenu()
  '...
  dxPopupMenu.MenuViewType = MenuViewType.Menu
  dxPopupMenu.ShowPopup(parentControl, pt)
  'or
  CType(dxPopupMenu, IDXDropDownControl).Show(New SkinMenuManager(lf), parentControl, pt)
  

• BarManager - Displays DXPopupMenu as a popup bar.

  

  C#

  // Display a DXPopupMenu as a popup bar
  Control parentControl = this;
  Point pt;
  DXPopupMenu dxPopupMenu = new DXPopupMenu();
  //...
  dxPopupMenu.MenuViewType = MenuViewType.Toolbar;
  dxPopupMenu.ShowPopup(parentControl, pt);
  //or
  ((IDXDropDownControl)dxPopupMenu).Show(barManager1, parentControl, pt);
  

  VB.NET

  ' Display a DXPopupMenu as a popup bar
  Dim parentControl As Control = Me
  Dim pt As Point
  Dim dxPopupMenu As DXPopupMenu = New DXPopupMenu()
  '...
  dxPopupMenu.MenuViewType = MenuViewType.Toolbar
  dxPopupMenu.ShowPopup(parentControl, pt)
  'or
  CType(dxPopupMenu, IDXDropDownControl).Show(barManager1, parentControl, pt)
  

• RibbonControl - Displays a DXPopupMenu as a RibbonMiniToolbar object.

  

  C#

  // Display a DXPopupMenu as a RibbonMiniToolbar
  Control parentControl = this;
  Point pt;
  DXPopupMenu dxPopupMenu = new DXPopupMenu();
  //...
  dxPopupMenu.MenuViewType = MenuViewType.RibbonMiniToolbar;
  dxPopupMenu.ShowPopup(parentControl, pt);
  //or
  ((IDXDropDownControl)dxPopupMenu).Show(RibbonControl1, parentControl, pt);
  

  VB.NET

  ' Display a DXPopupMenu as a RibbonMiniToolbar
  Dim parentControl As Control = Me
  Dim pt As Point
  Dim dxPopupMenu As DXPopupMenu = New DXPopupMenu()
  '...
  dxPopupMenu.MenuViewType = MenuViewType.RibbonMiniToolbar
  dxPopupMenu.ShowPopup(parentControl, pt)
  'or
  CType(dxPopupMenu, IDXDropDownControl).Show(RibbonControl1, parentControl, pt)
  

Related API

• The inherited IDXDropDownControl.Show method displays a popup menu. You do not need to use this method to open the DevExpress Controls’ built-in menus, as these menus are automatically displayed on a control’s right click.
• The DXPopupMenu.HidePopup method hides a popup menu.
• The DXPopupMenu.CloseUp event fires after the menu has been closed.
• The DXPopupMenu.Alignment property determines a menu’s alignment relative to the mouse cursor. This property is supported only when the DXPopupMenu is displayed as a RibbonMiniToolbar object.

Examples

• How to: Implement Custom Menu in XtraGrid Control
• How to: Add DXButtonGroupItem to DXPopupMenu and Display Menu as RibbonMiniToolbar
• How to: Add DXEditMenuItem to DXPopupMenu and Display Menu as Toolbar
• How to: Display DXPopupMenu as a Regular Menu, Popup Bar or RibbonMiniToolbar

Cheat Sheets and Best Practices

DevExpress WinForms UI controls (Data Grid, Tree List, Vertical Grid, Gantt Control, etc.) ship with the built-in context menus. Read the following quick-reference guide for detailed information and examples:

Context Menus - DevExpress WinForms Cheat Sheets