Class PopupMenu

The PopupMenu class lets you create XP like context menus in the XP Menus framework.

Inheritance
System.Object
BaseComponent
PopupMenu
NavigationView.PopupMenu
PrimitiveDropDownPopupMenu
CustomizingPopupMenu
MdiPopupMenu
PropertyGridPopupMenu
ToolbarListPopupMenu
Implements
System.IDisposable
System.Windows.Forms.IMessageFilter
Inherited Members
Namespace: Syncfusion.Windows.Forms.Tools.XPMenus
Assembly: Syncfusion.Tools.Windows.dll
Syntax
public class PopupMenu : BaseComponent, IThemeProvider, IVisualStyle, IDisposable, IPopupParent, IPopupItem, IMessageFilter, IIgnoreWorkingArea
Remarks

The PopupMenu class works in conjunction with a ParentBarItem.

You should first associate a ParentBarItem with a PopupMenu (using its ParentBarItem property) and fill the ParentBarItem with BarItems that you want displayed in the popup. Then use the PopupMenu's Show(Control, Rectangle) method to popup a menu at any location.

Note that the ParentBarItem attached to this PopupMenu need not be associated with any BarManager. However, if the ParentBarItem is part of a BarManager(which itself is already in the form's designer) then you can design the PopupMenu during design time (through the PopupMenu designer's "Customize" verb) by simply dragging and dropping items from the BarManager into the PopupMenu.

Examples

Take a look at our samples under the Tools\Samples\Menus Package folder for usage example. The XPMenus sample will illustrate how to use the PopupMenu in the presence of a BarManager. The XPToolbarsAndContextMenus sample will illustrate how to use the PopupMenu in the absence of a BarManager, at stand alone.

// Create and initialize a ParentBarItem
this.editBarItem = new Syncfusion.Windows.Forms.Tools.ParentBarItem();
this.editMenu.Text = "Edit";
this.editMenu.Items.AddRange(new BarItem[]
        {   this.cutItem,
            this.copyItem,});
// Associate the ParentBarItem with the PopupMenu            
this.popupMenu1 = new Syncfusion.Windows.Forms.Tools.PopupMenu();
this.popupMenu1.ParentBarItem = this. editBarItem;

// Then associate it with a RichTextBox
this.popupMenusManager = new PopupMenusManager();
this.popupMenusManager.SetXPContextMenu(this.richTextBox1, this.popupMenu1);

	' Create and initialize a ParentBarItem
    Me.editBarItem = New Syncfusion.Windows.Forms.Tools.ParentBarItem()
    Me.editMenu.Text = "Edit"
    Me.editMenu.Items.AddRange(New BarItem() {Me.cutItem, Me.copyItem})

    ' Associate the ParentBarItem with the PopupMenu
    Me.popupMenu1 = New Syncfusion.Windows.Forms.Tools.PopupMenu()
    Me.popupMenu1.ParentBarItem = Me.editBarItem

	' Then associate it with a RichTextBox
	Me.popupMenusManager = New PopupMenusManager()
	Me.popupMenusManager.SetXPContextMenu(Me.richTextBox1, Me.popupMenu1)

Constructors

PopupMenu()

Overloaded. Creates a new instance of the PopupMenu class.

Declaration
public PopupMenu()

PopupMenu(IContainer)

Creates a new instance of the Popupmenu class and adds itself to the specified container.

Declaration
public PopupMenu(IContainer container)
Parameters
Type Name Description
System.ComponentModel.IContainer container

The container into which to add.
Remarks

This constructor is used at design-time to add a component to the form's IContainer field so that it gets disposed when the form gets disposed.

Fields

childMenuUI

Declaration
protected IPopupChild childMenuUI
Field Value
Type
IPopupChild

Properties

DesignTimeForm

Sets the design time form.

Declaration
public Form DesignTimeForm { set; }
Property Value
Type
System.Windows.Forms.Form

IgnoreWorkingArea

Gets or sets ignore working area when menu begin popup.

Declaration
public bool IgnoreWorkingArea { get; set; }
Property Value
Type
System.Boolean

MenuGrid

Gets the available menu grid.

Declaration
protected virtual MenuGrid MenuGrid { get; }
Property Value
Type
MenuGrid

ParentBarItem

Gets or sets the ParentBarItem that specifies the items in the dropdown menu.

Declaration
public ParentBarItem ParentBarItem { get; set; }
Property Value
Type
ParentBarItem
Remarks

The ParentBarItem that specifies the items in the dropdown menu. The default value is null.

If this property is null, then calling Show on the PoupMenu will not have any effect (will Assert in debug mode).

SourceControl

Returns the control that is displaying the PopupMenu.

Declaration
public Control SourceControl { get; set; }
Property Value
Type Description
System.Windows.Forms.Control

The control that is displaying the context menu. If no control has displayed the context menu, the property returns a null reference (Nothing in Visual Basic).
Remarks

This property enables you to determine which control currently displays the context menu defined in this PopupMenu. If the context menu is not currently displayed, you can use this property to determine which control last displayed the context menu. You can use this property in the event to ensure that the control displays the proper menu items. You can also use this property to pass a reference to the control to a method that performs the tasks associated with a menu command displayed in the popup menu. Since the Form class inherits from control, you can also use this property if the context menu is associated with a form.

You can use this property in the BeforePopup event to figure out in which control the context menu was shown.

This can also be used when a shortcut key triggers a BarItem. event to determine in which control's context the shortcut was processed, if a PopupMenu is associated with multiple controls.

SynchronousPopup

Indicates whether the PopupMenu should be displayed within the WM_CONTEXTMENU message processing stack or if the PopupMenu should be shown after a short delay (using a timer). Use the Asynchronous (timer based) approach if you intend to dispose the underlying SourceControl from within a Popup event.

Declaration
public bool SynchronousPopup { get; set; }
Property Value
Type
System.Boolean

ThemeStyle

Gets or sets the BarItemStyleInfo value used to customize the appearance of the PopupMenu.

Declaration
public PopupMenuVisualStyle ThemeStyle { get; set; }
Property Value
Type
PopupMenuVisualStyle
Remarks

This ThemeStyle settings will be applied only when the VisualStyleBased theme has been applied to the control.

Methods

ChildClosing(IPopupChild, PopupCloseType)

Child closing method.

Declaration
public virtual void ChildClosing(IPopupChild childUI, PopupCloseType popupCloseType)
Parameters
Type Name Description
IPopupChild childUI
PopupCloseType popupCloseType

Dispose(Boolean)

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
System.Boolean disposing

GetBorderOverlapCue(PopupRelativeAlignment)

Serves to get the border overlap cue.

Declaration
public Point[] GetBorderOverlapCue(PopupRelativeAlignment rAlignment)
Parameters
Type Name Description
PopupRelativeAlignment rAlignment
Returns
Type
System.Drawing.Point[]

GetControlName(String)

Helps to get the ControlName settings in control

Declaration
public override string GetControlName(string controlName)
Parameters
Type Name Description
System.String controlName
Returns
Type
System.String
Overrides

GetLocationForPopupAlignment(PopupRelativeAlignment, out PopupRelativeAlignment)

Serves to get the location for pop-up alignment.

Declaration
public Point GetLocationForPopupAlignment(PopupRelativeAlignment prevAlign, out PopupRelativeAlignment newAlign)
Parameters
Type Name Description
PopupRelativeAlignment prevAlign
PopupRelativeAlignment newAlign
Returns
Type
System.Drawing.Point

GetParentControl()

Declaration
protected virtual Control GetParentControl()
Returns
Type
System.Windows.Forms.Control

GetPopupParentControl()

Returns the parent control.

Declaration
public virtual Control GetPopupParentControl()
Returns
Type
System.Windows.Forms.Control

GetSize()

Gets the size of MenuGrid.

Declaration
public Size GetSize()
Returns
Type Description
System.Drawing.Size

Returns size of the popup menu grid.

Hide()

Hides a Popup if it is being displayed.

Declaration
public void Hide()

IsRelatedControl(Control, Boolean)

Indicates whether a specified control is part of the popup hierarchy.

Declaration
public virtual bool IsRelatedControl(Control control, bool askParent)
Parameters
Type Name Description
System.Windows.Forms.Control control
System.Boolean askParent
Returns
Type
System.Boolean

IsShowing()

Indicates whether the Popup is currently open and dropped down.

Declaration
public bool IsShowing()
Returns
Type Description
System.Boolean

True if the Popup is open; false otherwise.

OnBeforePopup(CancelMouseEventArgs)

Raises the BeforePopup event.

Declaration
protected virtual void OnBeforePopup(CancelMouseEventArgs e)
Parameters
Type Name Description
CancelMouseEventArgs e

A CancelMouseEventArgs that contains the event data.
Remarks

The OnBeforePopup method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Notes to Inheritors: When overriding OnBeforePopup in a derived class, be sure to call the base class's OnBeforePopup method so that registered delegates receive the event.

OnThemeNameChanged(String)

Helps to apply the ThemeName settings in control

Declaration
public override void OnThemeNameChanged(string themeName)
Parameters
Type Name Description
System.String themeName

ThemeName
Overrides

PreFilterMessage(ref Message)

Pre processing mouse messages.

Declaration
public bool PreFilterMessage(ref Message m)
Parameters
Type Name Description
System.Windows.Forms.Message m
Returns
Type
System.Boolean

ProcessShortcut(Keys)

Processes the shortcut key.

Declaration
public bool ProcessShortcut(Keys key)
Parameters
Type Name Description
System.Windows.Forms.Keys key

The shortcut key.
Returns
Type Description
System.Boolean

True if processed; false otherwise.
Remarks

In this overload, if the shortcut was processed, the PopupMenu's SourceControl property will be set to null when the BarItem's event is fired.

ProcessShortcut(Keys, Control)

Processes the shortcut key.

Declaration
public bool ProcessShortcut(Keys key, Control control)
Parameters
Type Name Description
System.Windows.Forms.Keys key

The shorcut key.
System.Windows.Forms.Control control

The control in whose context the shortcut should be processed.
Returns
Type Description
System.Boolean

True if processed; false otherwise.
Remarks

In this overload, if the shortcut was processed, the PopupMenu's SourceControl property will be set to the specified control when the BarItem's event is fired.

Show(Control, Point)

Pops up a menu beside the specified rectangle in the control.

Declaration
public void Show(Control control, Point pos)
Parameters
Type Name Description
System.Windows.Forms.Control control

The parent control for this PopupMenu.
System.Drawing.Point pos

The point in the control's client co-ordinates at which the popup will be dropped-down.
Remarks

Use this version of Show to popup the menu at a specified point. The Popup drop-down alignment will be determined based on the available screen area and the point beside which to popup.

In NT4.0 this method will return immediately and the menu will be shown asynchronously.

Exceptions
Type Condition
System.ArgumentNullException

Will be thrown if control is null.
System.Exception

Will be thrown if the control's handle is not created or if the control is not visible.

Show(Control, Rectangle)

Pops up a menu beside the specified rectangle in the control.

Declaration
public void Show(Control control, Rectangle besideRect)
Parameters
Type Name Description
System.Windows.Forms.Control control

The parent control for this PopupMenu.
System.Drawing.Rectangle besideRect

The rectangular region in client co-ordinates of the control to which the popup will be docked.
Remarks

Use this version of Show to popup the menu around a rectangle like in a combo box rather than around a point. The Popup drop-down position will be determined based on the available screen area and the docking rectangle beside which to popup.

In NT4.0 this method will return immediately and the menu will be shown asynchronously.

Exceptions
Type Condition
System.ArgumentNullException

Will be thrown if control is null.
System.Exception

Will be thrown if the control's handle is not created or if the control is not visible.

ShowChildrenUI(Point, IPopupParent)

Shows the children UI.

Declaration
public virtual IPopupChild ShowChildrenUI(Point pos, IPopupParent parentUI)
Parameters
Type Name Description
System.Drawing.Point pos
IPopupParent parentUI
Returns
Type
IPopupChild

Events

BeforePopup

Fired right before the popup menu gets displayed with the position.

Declaration
public event CancelMouseEventHandler BeforePopup
Event Type
Type
CancelMouseEventHandler
Remarks

This event gets fired before the underlying ParentBarItem's BeforePopup event gets fired. The difference is that this event also provides the mouse position of the context menu. Both events are cancellable.

Collapse

Occurs when menu is collapsed.

Declaration
public event EventHandler Collapse
Event Type
Type
System.EventHandler

ParentBarItemChanged

Fired when the ParentBarItem property changes.

Declaration
public event EventHandler ParentBarItemChanged
Event Type
Type
System.EventHandler

Popup

Occurs when menu is popped up.

Declaration
public event EventHandler Popup
Event Type
Type
System.EventHandler

Explicit Interface Implementations

IPopupParent.IsRightToLeft

Declaration
bool IPopupParent.IsRightToLeft { get; }
Returns
Type
System.Boolean

Implements

System.IDisposable
System.Windows.Forms.IMessageFilter