UIElement.MouseRightButtonDown Event

In UI design for applications, a mouse right button click action is generally considered to be the user action that displays a context-sensitive menu or similar UI. The menu or UI is often specifically related to the UI element the mouse pointer is currently over, rather than the application as a whole. Silverlight is often hosted in a browser and the right-click menu outside the Silverlight content area is controlled by the browser host and possibly integrated with other regions that have right-click handling available. For this reason it is also an appropriate UI design to use right-click handling to display menus or UI that are relevant to your entire application, and not necessarily related to specific UI elements.

Menu display for right-click mouse user actions is not an automatically enabled feature. It is up to your application design to handle MouseRightButtonDown, to note the mouse pointer position, to create or make visible a UI element that serves as the context menu, and to position it at a location in UI that is visually appropriate.

A common choice for a UI element that serves as a context menu is Popup. A Popup uses dialog metaphors for opening and closing (it is not a true dialog in terms of modality, however). In terms of layout and rendering, a Popup will display on top of and independent to the other UI elements in the Silverlight content area. This makes it simpler to display and produces a more natural UI experience. Other techniques for inserting the context menu into existing primary layout might require a layout pass over the application UI and could be visually distracting.

The following example shows a possible event handler for right-click mouse buttons on a UI element. The variable p references an existing Popup that is defined in the same page as the UI element. GetPosition is called on the event data to set the offsets of where the Popup displays, such that the popup appears slightly below and right of where the mouse pointer was when the right mouse button was pressed.

private void Image_MouseRightButtonDown(object sender, MouseButtonEventArgs e)
{
    p.HorizontalOffset = e.GetPosition(null).X+10;
    p.VerticalOffset = e.GetPosition(null).Y + 10;
    p.IsOpen = true;
    e.Handled = true;
}

Previous versions of Silverlight (Silverlight 3 and previous) did not provide right click events to application code, because these were used by the plug-in to display the Silverlight configuration dialog.

To preserve the behavior of displaying the Silverlight configuration dialog to end users when the Silverlight content area is right-clicked, the Silverlight runtime acts as a last-chance handler for a MouseRightButtonDown routed event. If there is no specific handler at any point in the route between the initiating UI element and the visual root that processes the event data and sets Handled to true, then Silverlight displays the configuration dialog. MouseRightButtonUp is only raised if a preceding MouseRightButtonDown handler in application code sets Handled to true.

The MouseRightButtonDown event is a bubbling event. This means that if multiple MouseRightButtonDown event handlers are registered for a sequence of objects connected by parent-child relationships in the object tree, the event is received by each object in that relationship. The bubbling metaphor indicates that the event starts at the object that directly receives the input condition, and works its way up the object tree. For a bubbling event, the sender available to the event handler identifies the object where the event is handled, not necessarily the object that actually received the input condition that initiated the event. To get the object that initiated the event, use the OriginalSource value of the event's RoutedEventArgs event data.

When handling MouseRightButtonDown and displaying your own UI, you should set Handled to true in the event data. Failing to do so will result in your own UI as well as the Silverlight configuration dialog being displayed at the same time, which will be a confusing user experience. Also, you must set Handled to true in order to enable any handlers for MouseRightButtonUp.

Controls that inherit MouseRightButtonDown can provide handling for the event that acts as handler for all instances, by overriding the OnMouseRightButtonDown method. This might include marking the Handled value of the event as true, which has the effect of suppressing the MouseRightButtonDown event on any instance of the control (and potentially any subclass of the control). For more information, see OnMouseRightButtonDown.

Do not routinely handle MouseRightButtonDown from control code, unless your control has a specific scenario where the right-click handling is useful. Handling MouseRightButtonDown interferes with the default mode of displaying the Silverlight configuration dialog if that area of the UI is right-clicked.

Silverlight 3: This event is not available in Silverlight 3.

Silverlight 4: This event exists in Silverlight 4. However, you cannot use AddHandler to register for already-handled MouseRightButtonDown occurrences, because there is no public RoutedEvent identifier available for the event in Silverlight 4.