Class RadDropDownMenu

Represents a drop-down menu control that can be used as a popup menu for various UI elements. Provides functionality for displaying menu items with support for hierarchical menus, animations, and keyboard navigation.

Inheritance
System.Object
RadControl
RadPopupControlBase
RadItemsPopupControl
RadDropDownMenu
RadContextMenuDropDown
RadDropDownButtonPopup
RadGalleryDropDown
SchedulerInplaceDropDownMenu
VirtualGridContextMenu
SpreadsheetFilteringDropDownMenu
Inherited Members
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

[RadToolboxItem(false)]
public class RadDropDownMenu : RadItemsPopupControl, INotifyPropertyChanged, ISupportInitializeNotification, ISupportInitialize, IComponentTreeHandler, ILayoutHandler, IPCHost, IAnalyticsProvider, IPopupControl, IItemsControl

Constructors

RadDropDownMenu()

Initializes a new instance of the RadDropDownMenu class with no owner element.

Declaration
public RadDropDownMenu()

RadDropDownMenu(RadElement)

Initializes a new instance of the RadDropDownMenu class with the specified owner element.

Declaration
public RadDropDownMenu(RadElement ownerElement)
Parameters
RadElement ownerElement

The RadElement that represents the owner of this drop-down menu, or null if no owner is specified.

Properties

CausesValidation

This property is not relevant for this class.

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

ClickedItem

Gets the item that has been clicked. This property is valid when the drop-down is closed by an item click.

Declaration
public RadItem ClickedItem { get; }
Property Value
RadItem

HeaderImage

Gets or sets the image displayed in the header column of the menu.

Declaration
public Image HeaderImage { get; set; }
Property Value
System.Drawing.Image

HeaderText

Gets or sets the text displayed in the header column of the menu.

Declaration
public string HeaderText { get; set; }
Property Value
System.String

IsTwoColumnMenu

Gets or sets a value indicating whether the drop-down menu contains one or two columns of items. This property is currently not implemented and always returns false.

Declaration
public virtual bool IsTwoColumnMenu { get; set; }
Property Value
System.Boolean

PopupElement

Gets or sets the popup element that contains the menu items and provides the visual representation of the drop-down menu.

Declaration
public RadElement PopupElement { get; set; }
Property Value
RadElement

RootTreeHandler

Gets the root component tree handler by traversing up the popup ownership hierarchy to find the topmost control's tree handler.

Declaration
public IComponentTreeHandler RootTreeHandler { get; }
Property Value
IComponentTreeHandler

ThemeClassName

Gets or sets the theme class name for the drop-down menu. The theme class name resolution follows a hierarchy: checking owner inheritance, local settings, owner control theme capability, and finally the default class name.

Declaration
public override string ThemeClassName { get; set; }
Property Value
System.String

Overrides

Methods

CanClosePopup(RadPopupCloseReason)

Determines whether the popup can be closed for the specified reason, considering owner element state and mouse interaction.

Declaration
public override bool CanClosePopup(RadPopupCloseReason reason)
Parameters
RadPopupCloseReason reason

The reason for closing the popup.
Returns
System.Boolean

True if the popup can be closed; otherwise, false.
Overrides

CanNavigate(Keys)

Determines whether the drop-down menu can handle navigation with the specified key.

Declaration
public override bool CanNavigate(Keys keyData)
Parameters
System.Windows.Forms.Keys keyData

The key data to evaluate for navigation capability.
Returns
System.Boolean

True if the key can be used for navigation; otherwise, false.
Overrides

CanProcessItem(RadMenuItemBase)

Determines whether the specified menu item can be processed for user interaction.

Declaration
protected virtual bool CanProcessItem(RadMenuItemBase menuItem)
Parameters
RadMenuItemBase menuItem

The menu item to evaluate.
Returns
System.Boolean

True if the menu item is not null and is enabled; otherwise, false.

CanProcessMnemonic(Char)

Determines whether the drop-down menu can process the specified mnemonic character.

Declaration
public override bool CanProcessMnemonic(char keyData)
Parameters
System.Char keyData

The character to evaluate for mnemonic processing.
Returns
System.Boolean

True if the character can be processed as a mnemonic; otherwise, false.
Overrides

CheckCanNavigate(Keys)

Checks whether navigation is possible with the specified key based on the current selection and menu state.

Declaration
protected virtual bool CheckCanNavigate(Keys keyData)
Parameters
System.Windows.Forms.Keys keyData

The key to evaluate for navigation capability.
Returns
System.Boolean

True if navigation is possible with the specified key; otherwise, false.

CheckCanProcessMnemonic(IItemsControl, Char)

Recursively checks whether the specified mnemonic character can be processed by the items control or its child menus.

Declaration
protected virtual bool CheckCanProcessMnemonic(IItemsControl itemsControl, char keyData)
Parameters
IItemsControl itemsControl

The items control to check for mnemonic processing capability.
System.Char keyData

The character to evaluate for mnemonic processing.
Returns
System.Boolean

True if the character can be processed as a mnemonic; otherwise, false.

ControlDefinesThemeForElement(RadElement)

Determines whether this control defines the theme for the specified element, considering owner inheritance and element type.

Declaration
public override bool ControlDefinesThemeForElement(RadElement element)
Parameters
RadElement element

The element to evaluate for theme definition.
Returns
System.Boolean

True if this control defines the theme for the element; otherwise, false.
Overrides

CreateAccessibilityInstance()

Creates an accessibility object for the drop-down menu to support assistive technologies.

Declaration
protected override AccessibleObject CreateAccessibilityInstance()
Returns
System.Windows.Forms.AccessibleObject

A new RadDropDownMenuAccessibleObject if accessibility is enabled; otherwise, the base accessibility object.

CreatePopupElement()

Creates the popup element that will contain the menu items for the drop-down menu.

Declaration
protected virtual RadElement CreatePopupElement()
Returns
RadElement

A new RadDropDownMenuElement configured as the popup container.

Dispose(Boolean)

Releases the unmanaged resources used by the RadDropDownMenu and optionally releases the managed resources.

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

True to release both managed and unmanaged resources; false to release only unmanaged resources.
Overrides

DoOnItemClicked(RadMenuItemBase, MouseEventArgs)

Handles the clicking action on a menu item, managing selection, popup closure, and child menu display.

Declaration
protected virtual void DoOnItemClicked(RadMenuItemBase menuItem, MouseEventArgs e)
Parameters
RadMenuItemBase menuItem

The menu item that was clicked.
System.Windows.Forms.MouseEventArgs e

The mouse event arguments.

EnsureItemEnabled(RadItem, Boolean)

Ensures that an enabled item is selected by cycling through items in the specified direction until an enabled item is found.

Declaration
protected virtual void EnsureItemEnabled(RadItem item, bool isUp)
Parameters
RadItem item

The currently selected item to start from.
System.Boolean isUp

True to search upward; false to search downward.

GetMenuItemAtPoint(Point)

Gets the menu item at the specified location by traversing up the element tree.

Declaration
protected RadMenuItemBase GetMenuItemAtPoint(Point location)
Parameters
System.Drawing.Point location

The location to search for a menu item.
Returns
RadMenuItemBase

The RadMenuItemBase at the specified location, or null if no menu item is found.

GetOwnerScreenLocation()

Gets the screen location of the owner element used for positioning the drop-down menu.

Declaration
protected virtual Point GetOwnerScreenLocation()
Returns
System.Drawing.Point

The screen coordinates of the owner element.

GetOwnerSize()

Gets the size of the owner element used for positioning calculations.

Declaration
protected virtual Size GetOwnerSize()
Returns
System.Drawing.Size

The size of the owner element, or System.Drawing.Size.Empty if no owner is available.

InitializeChildren()

Initializes the child elements of the drop-down menu, setting up the root element properties and creating the popup element if necessary.

Declaration
protected virtual void InitializeChildren()

OnDropDownClosed(RadPopupClosedEventArgs)

Declaration
protected override void OnDropDownClosed(RadPopupClosedEventArgs args)
Parameters
RadPopupClosedEventArgs args

Overrides

OnDropDownLocationNeeded(Point)

Called when a drop-down location is needed and provides an opportunity to customize the location.

Declaration
protected virtual Point OnDropDownLocationNeeded(Point point)
Parameters
System.Drawing.Point point

The requested location point.
Returns
System.Drawing.Point

The location where the drop-down should be displayed.

OnItemDeselected(ItemSelectedEventArgs)

Handles item deselection events, updating the selected state of the menu item.

Declaration
protected override void OnItemDeselected(ItemSelectedEventArgs args)
Parameters
ItemSelectedEventArgs args

The item selection event arguments.
Overrides

OnItemsChanged(RadItemCollection, RadItem, ItemsChangeOperation)

Handles changes to the menu items collection, updating hierarchy relationships and ownership.

Declaration
protected virtual void OnItemsChanged(RadItemCollection changed, RadItem target, ItemsChangeOperation operation)
Parameters
RadItemCollection changed

The collection that was changed.
RadItem target

The menu item that was affected by the change.
ItemsChangeOperation operation

The type of change operation that occurred.

OnItemSelected(ItemSelectedEventArgs)

Handles item selection events, updating the selected state and accessibility notifications.

Declaration
protected override void OnItemSelected(ItemSelectedEventArgs args)
Parameters
ItemSelectedEventArgs args

The item selection event arguments.
Overrides

OnKeyDown(Keys)

Handles key down events for menu navigation, item selection, and mnemonic processing.

Declaration
public override bool OnKeyDown(Keys keyData)
Parameters
System.Windows.Forms.Keys keyData

The key data to process.
Returns
System.Boolean

True if the key was handled; otherwise, false.
Overrides

OnLoad(Size)

Handles the load event for the drop-down menu, setting up image list and binding context from the owner element if available.

Declaration
protected override void OnLoad(Size desiredSize)
Parameters
System.Drawing.Size desiredSize

The desired size for the menu.
Overrides

OnMouseClick(MouseEventArgs)

Declaration
protected override void OnMouseClick(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

OnMouseDown(MouseEventArgs)

Handles mouse down events for the drop-down menu, processing menu item interactions and child drop-down display.

Declaration
protected override void OnMouseDown(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

The mouse event arguments.
Overrides

OnMouseMove(MouseEventArgs)

Handles mouse move events for the drop-down menu, managing item selection and child menu timing.

Declaration
protected override void OnMouseMove(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

The mouse event arguments.
Overrides

OnMouseWheel(Control, Int32)

Handles mouse wheel events to scroll the menu content when the vertical scrollbar is visible.

Declaration
public override bool OnMouseWheel(Control target, int delta)
Parameters
System.Windows.Forms.Control target

The target control for the mouse wheel event.
System.Int32 delta

The wheel delta value indicating scroll direction and amount.
Returns
System.Boolean

True if the mouse wheel event was handled; otherwise, false.
Overrides

OnScreenTipNeeded(Object, ScreenTipNeededEventArgs)

Handles screen tip needed events by delegating to the root owner control in the hierarchy.

Declaration
protected override void OnScreenTipNeeded(object sender, ScreenTipNeededEventArgs e)
Parameters
System.Object sender

The source of the event.
ScreenTipNeededEventArgs e

The screen tip needed event arguments.
Overrides

OnToolTipTextNeeded(Object, ToolTipTextNeededEventArgs)

Handles tooltip text needed events by delegating to the root owner control in the hierarchy.

Declaration
protected override void OnToolTipTextNeeded(object sender, ToolTipTextNeededEventArgs e)
Parameters
System.Object sender

The source of the event.
ToolTipTextNeededEventArgs e

The tooltip text needed event arguments.
Overrides

PerformItemClick(RadMenuItemBase)

Performs a click action on the specified menu item, handling child menu expansion or popup closure as appropriate.

Declaration
protected void PerformItemClick(RadMenuItemBase menuItem)
Parameters
RadMenuItemBase menuItem

The menu item to perform the click action on.

PerformMenuItemClick(RadMenuItemBase)

Performs the click action on a menu item if conditions are met (not in design time and not under mouse).

Declaration
protected virtual void PerformMenuItemClick(RadMenuItemBase menuItem)
Parameters
RadMenuItemBase menuItem

The menu item to perform the click action on.

ProcessDialogChar(Char)

Processes dialog character input for the drop-down menu.

Declaration
protected override bool ProcessDialogChar(char charCode)
Parameters
System.Char charCode

The character code to process.
Returns
System.Boolean

Always returns true to indicate the character was processed.

ProcessLeftRightNavigationKey(Boolean)

Processes left and right navigation keys for expanding/collapsing child menus and closing parent menus.

Declaration
protected virtual bool ProcessLeftRightNavigationKey(bool isLeft)
Parameters
System.Boolean isLeft

True for left navigation; false for right navigation.
Returns
System.Boolean

True if the navigation was processed; otherwise, false.

ProcessMnemonic(Keys)

Processes mnemonic key input to find and activate matching menu items.

Declaration
protected virtual bool ProcessMnemonic(Keys keyData)
Parameters
System.Windows.Forms.Keys keyData

The key data to process as a mnemonic.
Returns
System.Boolean

True if a mnemonic was found and processed; otherwise, false.

ProcessUpDownNavigationKey(Boolean)

Processes up and down navigation keys, selecting the appropriate item in the specified direction.

Declaration
protected virtual bool ProcessUpDownNavigationKey(bool isUp)
Parameters
System.Boolean isUp

True for up navigation; false for down navigation.
Returns
System.Boolean

True if the navigation was processed; otherwise, false.

SetVisibleCore(Boolean)

Sets the visible state of the control, managing popup positioning and selection state.

Declaration
protected override void SetVisibleCore(bool value)
Parameters
System.Boolean value

True to make the control visible; false to hide it.

Show()

Displays the RadDropDownMenu in its default position.

Declaration
public void Show()

Show(Point)

Displays the RadDropDownMenu at the specified screen location.

Declaration
public void Show(Point point)
Parameters
System.Drawing.Point point

The screen coordinates where the menu should be displayed.

Show(Point, RadDirection)

Displays the RadDropDownMenu at the specified screen location with the specified popup direction.

Declaration
public void Show(Point point, RadDirection popupDirection)
Parameters
System.Drawing.Point point

The screen coordinates where the menu should be displayed.
RadDirection popupDirection

The direction in which the menu should open.

Show(Int32, Int32)

Displays the RadDropDownMenu at the specified screen coordinates.

Declaration
public void Show(int x, int y)
Parameters
System.Int32 x

The horizontal screen coordinate, in pixels.
System.Int32 y

The vertical screen coordinate, in pixels.

Show(Control, Point)

Displays the RadDropDownMenu relative to the specified control at the given offset point.

Declaration
public void Show(Control control, Point point)
Parameters
System.Windows.Forms.Control control

The control that serves as the reference point for positioning the menu.
System.Drawing.Point point

The offset from the control's location where the menu should be displayed.

Show(Control, Point, RadDirection)

Displays the RadDropDownMenu relative to the specified control with the given popup direction.

Declaration
public void Show(Control control, Point point, RadDirection popupDirection)
Parameters
System.Windows.Forms.Control control

The control that serves as the reference point for positioning the menu.
System.Drawing.Point point

The offset from the control's location where the menu should be displayed.
RadDirection popupDirection

The direction in which the menu should open.

Show(Control, Int32, Int32)

Displays the RadDropDownMenu relative to the specified control at the given offset coordinates.

Declaration
public void Show(Control control, int x, int y)
Parameters
System.Windows.Forms.Control control

The control that serves as the reference point for positioning the menu.
System.Int32 x

The horizontal offset from the control's location, in pixels.
System.Int32 y

The vertical offset from the control's location, in pixels.

Show(RadItem, Point)

Displays the RadDropDownMenu relative to the specified RadItem at the given offset point.

Declaration
public void Show(RadItem item, Point point)
Parameters
RadItem item

The RadItem that serves as the reference point for positioning the menu.
System.Drawing.Point point

The offset from the item's location where the menu should be displayed.

Show(RadItem, Point, RadDirection)

Displays the RadDropDownMenu relative to the specified RadItem with the given popup direction.

Declaration
public void Show(RadItem item, Point point, RadDirection popupDirection)
Parameters
RadItem item

The RadItem that serves as the reference point for positioning the menu.
System.Drawing.Point point

The offset from the item's location where the menu should be displayed.
RadDirection popupDirection

The direction in which the menu should open.

Show(RadItem, Int32, Int32)

Displays the RadDropDownMenu relative to the specified RadItem at the given offset coordinates.

Declaration
public void Show(RadItem item, int x, int y)
Parameters
RadItem item

The RadItem that serves as the reference point for positioning the menu.
System.Int32 x

The horizontal offset from the item's location, in pixels.
System.Int32 y

The vertical offset from the item's location, in pixels.

Show(RadItem, Int32, RadDirection)

Displays the RadDropDownMenu relative to the specified RadItem with the specified direction and owner offset.

Declaration
public void Show(RadItem item, int ownerOffset, RadDirection popupDirection)
Parameters
RadItem item

The RadItem that serves as the reference point for positioning the menu.
System.Int32 ownerOffset

The offset from the owner element, in pixels.
RadDirection popupDirection

The direction in which the menu should open.

ShowCore(Point, Int32, RadDirection)

Core implementation for displaying the drop-down menu at the specified location with the given direction and offset. Handles DPI scaling, theme setup, layout calculation, and popup positioning.

Declaration
protected virtual void ShowCore(Point point, int ownerOffset, RadDirection popupDirection)
Parameters
System.Drawing.Point point

The screen coordinates where the menu should be displayed.
System.Int32 ownerOffset

The offset from the owner element, in pixels.
RadDirection popupDirection

The direction in which the menu should open.

Extension Methods