# vPopupMenu

A class to show a popup menu in a canvas.

### Synopsis

Header:
  `<v/vpopmenu.h>`
Class name:
  vPopupMenu
Hierarchy:
  vPopupMenu

### Description

A `vPopupMenu` is used to show a floating popup menu, usually as the result of right clicking the mouse. They use the `vMenu` structure to define the items of the menu. Submenus are supported, but hot keys are not. Just leave the hot key field blank.

Please note that `vPopupMenu`s are not implemented on all systems (as of V 1.22, they were only available on MS-Windows). Use the `vPopupMenu::isImplemented` method for platform independent implementations.

To use a popup menu, you usually track mousedown events in your canvas pane and watch for right clicks. You then can create a `vPopupMenu` object, and call the `ShowMenu` method to display the popup menu. When the user picks an item on the popup menu, a message is sent to the `WindowCommand` method of the parent window of the canvas. The application program can also change attributes of the various menu items of the popup menu using methods provided by `vPopupMenu`.

### Constructor

#### vPopupMenu(const vMenu* menu, const vWindow* parent)

When the `vPopupMenu` object is defined, you provide the `vMenu` definition, and the parent `vWindow` of the canvas. You can use `vCanvasPane::GetPaneParent()` to easily get this value.

### Utility Methods

#### int isImplemented()

This method will return true if `vPopupMenu`s are implemented on the current platform.

#### int GetValue(ItemVal itemId)

This method is used to retrieve the value of a menu item in a menu. The `itemId` is the id of the item as defined in the menu definition. This will return the menu checked state.

#### void SetValue(ItemVal itemId, int Val, ItemSetType what)

This method is used to change the state of menu items. The item with `itemId` is set to `Val` using the `ItemSetType` parameter to control what is set. Possible values of `ItemSetType` include `Checked` and `Sensitive`.

#### void SetString(ItemVal itemId, char* title)

This can be used to change the label on a menu item. The item identified by `itemId` will have its label changed to `title`.

#### void ShowMenu(int x, int y)

Call this method to display the popup menu. This method will usually be called from the overridden `MouseDown` method of your canvas. This will popup the menu at canvas coordinates x,y. (Note: for vTextCanvasPanes, you should override `MouseDown`, not `TextMouseDown`) This method does not return until the user has either picked a menu item, or dismissed the popup menu. If the user picks a menu item, then a message will be sent to the `WindowCommand` method of the parent window to the canvas pane. This is generally what you want to do, and it keeps all the command actions localized to that method.

### Example

The following example is very simple, and shows how to override the `MouseDown` method to detect a right click, and then how to display the popup menu. Remember that the parent window of the canvas will use its `WindowCommand` method to receive the messages when the user picks an item.

    //===================>>> popTextCanvasPane::TextMouseDown <<<==================
      void popTextCanvasPane::MouseDown(int x, int y, int button)
      {
        // Note - override MouseDown for all canvas types
        // Meaningless menu examples
        static vMenu SubMenu[] =
          {
            {"&Close...", M_CloseFile, isSens, notChk, noKeyLbl, noKey, noSub},
            {"Exit", M_Exit, isSens, notChk, noKeyLbl, noKey, noSub},
            {NULL}
          };
        static vMenu FileMenu[] =
          {
            {"&New", M_New, isSens, notChk, noKeyLbl, noKey, noSub},
    	{"&Open...", M_Open, isSens, notChk, noKeyLbl, noKey, noSub},
            {"Other", 0, isSens, notChk, noKeyLbl, noKey, &SubMenu[0]},
            {NULL}
          };

        vPopupMenu pm(FileMenu,GetPaneParent());  // define the popup

        if (button == 3)               // check for right button
            (void) pm.ShowMenu(x, y);
        else                           // default action otherwise
            vTextCanvasPane::MouseDown(x,y,button);
      }

### See Also

vMenu