windowsforms-devexpress-dot-xtrabars-1156533b.md
A popup menu managed by a BarManager or RibbonControl. It can be used in controls (such as GridControl, TreeList, etc.) as a custom popup menu.
Namespace : DevExpress.XtraBars
Assembly : DevExpress.XtraBars.v25.2.dll
NuGet Package : DevExpress.Win.Navigation
public class PopupMenu :
PopupMenuBase,
IHasRibbonKeyTipManager,
PopupControl,
IDXDropDownControlEx,
IDXDropDownControl,
IAppearanceOwner,
IOptionsMultiColumnOwner
Public Class PopupMenu
Inherits PopupMenuBase
Implements IHasRibbonKeyTipManager,
PopupControl,
IDXDropDownControlEx,
IDXDropDownControl,
IAppearanceOwner,
IOptionsMultiColumnOwner
The following members return PopupMenu objects:
The PopupMenu can be used to provide easy access to frequently used commands for a specific control. When associated with an object, the popup menu is opened by right-clicking the object. The popup menu can also be displayed in code, using the PopupMenu.ShowPopup method.
The PopupMenu needs to be associated with a BarManager or RibbonControl. If your project does not contain these components, add one of them to the form. At design time, the PopupMenu is automatically associated with a BarManager or RibbonControl if they are present on the form. When creating a PopupMenu in code, ensure that the PopupMenuBase.Manager or PopupMenuBase.Ribbon property refers to an existing BarManager or RibbonControl component.
At design time, the PopupMenu can be customized by clicking the menu’s smart tag and selecting Run Designer.
A click on this link opens the Popup Menu Editor (different editors are used when the menu is associated with the BarManager and RibbonControl).
If the PopupMenu is associated with the BarManager, the Bar Manager’s Customization window and a standalone Popup Menu Editor are invoked.
You can customize the menu in a number of ways.
If the PopupMenu is associated with a RibbonControl, the Sub Menus and Popup Menus page of the Ribbon Control’s Designer is opened, providing menu customization tools.
The designer allows you to customize the menu by:
Items in popup menus are represented by bar item objects. The PopupMenu supports the display of any bar item that is provided by the DevExpress Ribbon, Menu and Docking Library: buttons, sub-menus, editors, static text, etc. For more information, see the Bar Item Links and The List of Bar Items and Links topics.
To populate a popup menu with items in code, add a specific bar item (a BarItem descendant) to the PopupMenuBase.ItemLinks collection.
You can use the BarManager.PopupShowMode and RibbonControl.PopupShowMode properties to specify how popup menus display their sub-menus. Sub-menus can be displayed in the traditional cascaded style as shown in the figure below.
Another option is to display sub-menus in-place of their parent popup menus. In this mode, when an end-user hovers over a sub-menu button with the mouse pointer, the currently opened menu hides and in its place, the required sub-menu is displayed. This mode is more convenient for application designed for tablet devices, as it allows you to save valuable screen space. The figure below shows how the sub-menu is displayed in the in-place mode.
If the in-place mode is enabled, sub-menus can display navigation headers that allow an end-user to navigate backward. See the PopupMenu.ShowNavigationHeader setting for details.
Submenus are displayed in the traditional cascaded way when managed by the BarManager component and in all styles of the RibbonControl control, except for the TabletOffice and OfficeUniversal styles (the default setting). In these styles, submenus are displayed in the in-place mode.
An existing PopupMenus can be assigned to the BarButtonItem.DropDownControl or DropDownButton.DropDownControl property. In this instance, the PopupMenu appears when an appropriate BarButtonItem or DropDownButton‘s drop-down arrow is clicked.
When a BarManager or RibbonControl is present on the form, all controls publish the PopupContextMenu property at design time (its caption in the Properties window looks like ‘PopupContextMenu on barManager1’ or ‘PopupContextMenu on ribbonControl1’). You can use this property to assign a PopupMenu to this control. This menu will then be displayed when right-clicking on the control at runtime.
To assign a PopupMenu to a control in code, use the BarManager.SetPopupContextMenu method.
Note
Specific complex controls such as the Grid Control and Tree List do not publish the PopupContextMenu property, as these controls support different context menus for different visual elements. See the help documentation on these products, to learn how to work with context menus in these controls.
Before you begin:
The following example demonstrates how to create a popup menu and bind the menu to the Form. Right-click the form to invoke the menu (at runtime).
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using DevExpress.XtraBars;
using DevExpress.XtraEditors;
namespace DevExpressPopupMenu {
public partial class Form1 : DevExpress.XtraEditors.XtraForm {
public Form1() {
InitializeComponent();
}
private void Form1_Load(object sender, EventArgs e) {
// Completes the BarManager's initialization (to allow its further customization on the form load)
barManager1.ForceInitialize();
// Creates a popup menu.
PopupMenu menu = new PopupMenu();
menu.Manager = barManager1;
// Specifies a collection of vector (SVG) icons.
barManager1.Images = svgImageCollection1;
// Creates and initializes the items.
BarSubItem itemAdd = new BarSubItem(barManager1, "Add");
BarButtonItem itemAddFile = new BarButtonItem(barManager1, "File", 2);
BarButtonItem itemAddFolder = new BarButtonItem(barManager1, "Folder", 3);
itemAdd.AddItems(new BarItem[] { itemAddFile, itemAddFolder });
BarButtonItem itemCopy = new BarButtonItem(barManager1, "Copy", 0);
BarButtonItem itemPaste = new BarButtonItem(barManager1, "Paste", 1);
// Adds the items to the popup menu.
menu.AddItems(new BarItem[] { itemAdd, itemCopy, itemPaste });
// Creates a separator before the Copy item.
itemCopy.Links[0].BeginGroup = true;
// Attaches the popup menu to the form.
barManager1.SetPopupContextMenu(this, menu);
// Subscribes to the 'ItemClick' event handler to process item clicks.
barManager1.ItemClick += BarManager1_ItemClick;
}
void BarManager1_ItemClick(object sender, ItemClickEventArgs e) {
XtraMessageBox.Show(string.Format("The '{0}' item was clicked.", e.Item.Caption));
}
}
}
Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Data
Imports System.Drawing
Imports System.Linq
Imports System.Text
Imports System.Windows.Forms
Imports DevExpress.XtraBars
Imports DevExpress.XtraEditors
Namespace DevExpressPopupMenu
Partial Public Class Form1
Inherits DevExpress.XtraEditors.XtraForm
Public Sub New()
InitializeComponent()
End Sub
Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs)
' Completes the BarManager's initialization (to allow its further customization on the form load)
barManager1.ForceInitialize()
' Creates a popup menu.
Dim menu As New PopupMenu()
menu.Manager = barManager1
' Specifies a collection of vector (SVG) icons.
barManager1.Images = svgImageCollection1
' Creates and initializes the items.
Dim itemAdd As New BarSubItem(barManager1, "Add")
Dim itemAddFile As New BarButtonItem(barManager1, "File", 2)
Dim itemAddFolder As New BarButtonItem(barManager1, "Folder", 3)
itemAdd.AddItems(New BarItem() { itemAddFile, itemAddFolder })
Dim itemCopy As New BarButtonItem(barManager1, "Copy", 0)
Dim itemPaste As New BarButtonItem(barManager1, "Paste", 1)
' Adds the items to the popup menu.
menu.AddItems(New BarItem() { itemAdd, itemCopy, itemPaste })
' Creates a separator before the Copy item.
itemCopy.Links(0).BeginGroup = True
' Attaches the popup menu to the form.
barManager1.SetPopupContextMenu(Me, menu)
' Subscribes to the 'ItemClick' event handler to process item clicks.
AddHandler barManager1.ItemClick, AddressOf BarManager1_ItemClick
End Sub
Private Sub BarManager1_ItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
XtraMessageBox.Show(String.Format("The '{0}' item was clicked.", e.Item.Caption))
End Sub
End Class
End Namespace
The image below shows the result.
The following code sample invokes a custom context menu when a user right-clicks a column header:
Add a BarManager to the form and create a custom PopupMenu.
Handle the GridView.PopupMenuShowing event and call the e.ShowCustomMenu method to display your custom menu instead of the default header menu.
void gridView1_PopupMenuShowing(object sender, PopupMenuShowingEventArgs e) {
if (e.MenuType == GridMenuType.Column) {
popupMenu_Column.Tag = e.HitInfo;
popupMenu_Column.MenuCaption = $"{e.HitInfo.Column}";
e.ShowCustomMenu(popupMenu_Column);
}
}
GridHitInfo GetHitInfo(BarItemLink link) {
PopupMenu menu = link.LinkedObject as PopupMenu;
return menu.Tag as GridHitInfo;
}
void barButtonItem_Filter_ItemClick(object sender, ItemClickEventArgs e) {
GridHitInfo info = GetHitInfo(e.Link);
info.View.ShowFilterEditor(info.Column);
}
void barButtonItem_ColumnChooser_ItemClick(object sender, ItemClickEventArgs e) {
GridHitInfo info = GetHitInfo(e.Link);
info.View.ShowCustomization();
}
Private Sub gridView1_PopupMenuShowing(ByVal sender As Object, ByVal e As PopupMenuShowingEventArgs)
If e.MenuType = GridMenuType.Column Then
popupMenu_Column.Tag = e.HitInfo
popupMenu_Column.MenuCaption = $"{e.HitInfo.Column}"
e.ShowCustomMenu(popupMenu_Column)
End If
End Sub
Private Function GetHitInfo(ByVal link As BarItemLink) As GridHitInfo
Dim menu As PopupMenu = TryCast(link.LinkedObject, PopupMenu)
Return TryCast(menu.Tag, GridHitInfo)
End Function
Private Sub barButtonItem_Filter_ItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
Dim info As GridHitInfo = GetHitInfo(e.Link)
info.View.ShowFilterEditor(info.Column)
End Sub
Private Sub barButtonItem_ColumnChooser_ItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
Dim info As GridHitInfo = GetHitInfo(e.Link)
info.View.ShowCustomization()
End Sub
The following code displays a specific PopupMenu if the right mouse button is pressed:
private void Form1_MouseUp(object sender, System.Windows.Forms.MouseEventArgs e) {
if(e.Button == MouseButtons.Right)
popupMenu1.ShowPopup(Control.MousePosition);
}
Private Sub Form1_MouseUp(ByVal sender As Object, _
ByVal e As System.Windows.Forms.MouseEventArgs) Handles MyBase.MouseUp
If e.Button = MouseButtons.Right Then
PopupMenu1.ShowPopup(Control.MousePosition)
End If
End Sub
Object MarshalByRefObject Component PopupMenuBase PopupMenu ApplicationMenu
See Also