windowsforms-5473-controls-and-libraries-ribbon-bars-and-menu-popup-menus-popup-menus-customization-showing-popup-menus.md
Popup menus can be used in a number of ways. They can be displayed automatically as a result of end-user’s actions, or you can implement your own logic and show popup menus manually. See below to learn more.
Note
Before customizing and using a popup menu, add a BarManager or RibbonControl to the form and ensure that the popup menu is bound to this BarManager/RibbonControl. By default, a popup menu being added to the form at design time automatically looks for a BarManager/Ribbon Control within the form, and if it’s found, binds itself to the located object via the PopupMenuBase.Manager/PopupMenuBase.Ribbon property. When creating the menu at runtime, you may need to manually bind it to a BarManager/Ribbon Control via these properties.
It’s possible to associate a popup menu with a control and automatically display this menu when an end-user right-clicks the control. To assign a menu to a control, use the control’s external PopupContextMenu property. The external PopupContextMenu properties are added at design time for all controls within a form when you place a BarManager or RibbonControl component onto this form.
Add a popup menu to the form. Then, select a control and switch to the Properties window. Locate the external PopupContextMenu property and assign the popup menu to this property.
The menu assigned will be displayed at runtime when right-clicking within the control’s bounds.
Note that the external PopupContextMenu property is available only at design time. To associate a menu with a control via code, you can use the BarManager.SetPopupContextMenu method. Call BarManager.GetPopupContextMenu to retrieve the control’s popup menu.
Example
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.
To activate popup menus, you normally handle specific events. For instance, if you need to open a popup menu when an end-user right-clicks within a text box, you may want to handle the control’s MouseUp event. To open a menu, call PopupMenu.ShowPopup.
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
You can associate a dropdown control (including a PopupMenu object) with regular and large bar button items (BarButtonItem or BarLargeButtonItem). In this instance, this item displays a dropdown arrow and clicking this arrow shows the associated dropdown control below the item:
To associate a popup menu with a bar button item, use the BarButtonItem.DropDownControl property. In addition, the bar item’s BarButtonItem.ButtonStyle property must be set to BarButtonStyle.DropDown.