Magic Logo
top
notifications
methods
properties
events
sample code
Class PopupMenu
Use this class to present the user with a context menu. Typically this is required as a result of the user right clicking the mouse button when over a control. For example, you might create a new UserControl derived class that needs to present the user with a set of options via a context menu, in the same way that the RichTextBox will allow you to cut, paste and copy text via its own context menu.

Notifications
Most windows applications will update the status bar with a menu description as the user selects different menu items. To help support this scenario the Selected and Deselected events are provided. As the names suggest, the Selected event is generated as the selection enters a menu item and the Deselected event when it moves away. The following example code shows how to use the MenuCommand.Description property of the MenuCommand class in conjunction with these events to provide status bar feedback.

   protected void ShowPopupMenu(Point screenPos)
   {
      // Create the menu items
      MenuCommand menu1 = new MenuCommand("&Cut");
      MenuCommand menu2 = new MenuCommand("&Paste");

      // Associate appropriate status bar descriptions for each menu
      menu1.Description = "Cut selection to the clipboard";
      menu2.Description = "Paste selection from the clipboard";

      // Create the popup menu object
      PopupMenu popup = new PopupMenu();

      // Define the list of menu commands
      popup.MenuCommands.AddRange(new MenuCommand[]{menu1, menu2});

      // Hook into selection events
      popup.Selected += new CommandHandler(OnSelected);
      popup.Deselected += new CommandHandler(OnDeselected);

      // Show it!
      MenuCommand selected = popup.TrackPopup(screenPos);
   }

   protected void OnSelected(MenuCommand mc)
   {
      _statusBarPanel.SetStatusBarText(mc.Description);
   }

   protected void OnDeselected(MenuCommand mc)
   {
      _statusBarPanel.SetStatusBarText("");
   }

Methods
public MenuCommand TrackPopup(Point screenPos)
Create menu at the given screen position and return the MenuCommand that is selected.

public MenuCommand TrackPopup(Point screenPos, bool selectFirst)
As above except it will automatically show the first valid menu item as the initial selection.

NOTE: The returned reference from both of the methods below can be null.
This happens when the user presses the escape key to dismiss the displayed menu.

public void Dismiss()
Use this to remove a displayed instance.

Properties
public MenuCommandCollection MenuCommands
Collection of MenuCommand instances for the PopupMenu.

public VisualStyle Style
Has two possible values.

  • VisualStyle.IDE shows in Visual Studio .NET style
  • VisualStyle.Plain shows in a simpler Visual C++ v6 style
Default: VisualStyle.IDE

public Font Font
The font to use when drawing menu text
Default: SystemInformation.MenuFont

public bool ShowInfrequent
Items marked as Infrequent are shown immediately on displayed menu.
Default: false

public bool RememberExpansion
Expansion button selection updates the menu collection auto expand when next shown.
Default: true

public bool HighlightInfrequent
Items marked as Infrequent are drawn in a different visual style.
Default: true

public Color BackColor
Base color used when drawing the background.
Default: SystemColors.Control

public Color TextColor
Text drawing color for items that are not highlighted.
Default: SystemColors.MenuText

public Color HighlightColor
Base color for highlighting of items.
Default: SystemColors.Highlight

public Color HighlightTextColor
Text drawing color for item that is highlighted.
Default: SystemColors.HighlightTextpublic Animate Animate
Can be set to one of the following enumeration values

  • Animate.No do not animate popup menus
  • Animate.Yes always animate popup menus
  • Animate.System use system setting
Default: Animate.System property.
public int AnimateTime
Determines the total time the animation should take in milliseconds.
Default: 100

Animation AnimateStyle
Can be set to one of the following enumeration values

  • Animation.Blend
  • Animation.SlideCenter
  • Animation.SlideHorVerPositive
  • Animation.SlideHorVerNegative
  • Animation.SlideHorPosVerNegative
  • Animation.SlideHorNegVerPositive
  • Animation.System
Default: Animation.System property.
Events
public event CommandHandler Selected
Fired when the user moves the selection over this item.
Use this event to update any status bar description appropriate for the item.

public event CommandHandler Deselected
Fired when the user selection moves away from this item.
Use this event to remove any status bar description previously set.

Delegate Signatures


    void CommandHandler(MenuCommand item);

Sample code
C#

   protected void OnMyControlButtonUp(object sender, MouseEventArgs e)
   {
      if (e.Button == MouseButtons.Right)
      {
         Control ctl = sender as Control;

         // Create the menu items
         MenuCommand menu0 = new MenuCommand("First");
         MenuCommand menu1 = new MenuCommand("Second");
         MenuCommand menu2 = new MenuCommand("Third");

         // Create the popup menu object
         PopupMenu popup = new PopupMenu();

         // Define the list of menu commands
         popup.MenuCommands.AddRange(new MenuCommand[]{menu0, 
                                                       menu1, 
                                                       menu2});

         // Show it!
         MenuCommand selected = 
              popup.TrackPopup(ctl.PointToScreen(new Point(e.X, e.Y)));

         // Was an item selected?
         if (selected != null)
         {
            // Selection specific actions...
			if (selected == menu0)
               Console.WriteLine("Menu0 selected");
            else if (selected == menu1)
               Console.WriteLine("Menu1 selected");
            else if (selected == menu2)
               Console.WriteLine("Menu2 selected");
         }
      }
   }

VB.NET

   Protected Sub OnMyControlButtonUp(ByVal sender As object, 
                                     ByVal e As MouseEventArgs)
                                     
      If e.Button = MouseButtons.Right Then
         Dim ctl As Control = sender

         ' Create the menu items
         Dim menu0 As New MenuCommand("First")
         Dim menu1 As New MenuCommand("Second")
         Dim menu2 As New MenuCommand("Third")

         ' Create the popup menu object
         Dim popup As New PopupMenu()

         ' Define the list of menu commands
         popup.MenuCommands.AddRange(new MenuCommand(){menu0, _ 
                                                       menu1, _ 
                                                       menu2})

         ' Show it!
         Dim selected As MenuCommand =
              popup.TrackPopup(ctl.PointToScreen(New Point(e.X, e.Y)))

         ' Was an item selected?
         If Not (selected Is Nothing) Then
            ' Selection specific actions...
			If (selected Is menu0) Then
               Console.WriteLine("Menu0 selected")
            ElseIf (selected Is menu1)
               Console.WriteLine("Menu1 selected")
            ElseIf (selected Is menu2)
               Console.WriteLine("Menu2 selected")
            End If
         End If
      End If
   End Sub