Loading...
Searching...
No Matches
juce::PopupMenu Class Reference

## Detailed Description

Creates and displays a popup-menu.

To show a popup-menu, you create one of these, add some items to it, then call its show() method, which returns the id of the item the user selects.

E.g.

void MyWidget::mouseDown (const MouseEvent& e)
{
PopupMenu m;
m.addItem (1, "item 1");
m.addItem (2, "item 2");
m.showMenuAsync (PopupMenu::Options(),
[] (int result)
{
if (result == 0)
{
// user dismissed the menu without picking anything
}
else if (result == 1)
{
// user picked item 1
}
else if (result == 2)
{
// user picked item 2
}
});
}
juce::MouseEvent
Contains position and status information about a mouse event.
Definition juce_MouseEvent.h:48

Submenus are easy too:

void MyWidget::mouseDown (const MouseEvent& e)
{
PopupMenu subMenu;
subMenu.addItem (1, "item 1");
subMenu.addItem (2, "item 2");
PopupMenu mainMenu;
mainMenu.addItem (3, "item 3");
mainMenu.addSubMenu ("other choices", subMenu);
m.showMenuAsync (...);
}

The documentation for this class was generated from the following file:

- juce_gui_basics/menus/juce_PopupMenu.h

## Classes

struct | Item
| Describes a popup menu item. More...
class | Options
| Class used to create a set of options to pass to the show() method. More...
class | MenuItemIterator
| Allows you to iterate through the items in a pop-up menu, and examine their properties. More...
class | CustomComponent
| A user-defined component that can be used as an item in a popup menu. More...
class | CustomCallback
| A user-defined callback that can be used for specific items in a popup menu. More...
struct | LookAndFeelMethods
| This abstract base class is implemented by LookAndFeel classes to provide menu drawing functionality. More...

## Public Types

enum | ColourIds { backgroundColourId = 0x1000700 , textColourId = 0x1000600 , headerTextColourId = 0x1000601 , highlightedBackgroundColourId = 0x1000900 , highlightedTextColourId = 0x1000800 }
| A set of colour IDs to use to change the colour of various aspects of the menu. More...

## Public Member Functions

| PopupMenu ()=default
| Creates an empty popup menu.
| PopupMenu (const PopupMenu &)
| Creates a copy of another menu.
| ~PopupMenu ()
| Destructor.
PopupMenu & | operator= (const PopupMenu &)
| Copies this menu from another one.
| PopupMenu (PopupMenu &&) noexcept
| Move constructor.
PopupMenu & | operator= (PopupMenu &&) noexcept
| Move assignment operator.
void | clear ()
| Resets the menu, removing all its items.
void | addItem (Item newItem)
| Adds an item to the menu.
void | addItem (String itemText, std::function< void()> action)
| Adds an item to the menu with an action callback.
void | addItem (String itemText, bool isEnabled, bool isTicked, std::function< void()> action)
| Adds an item to the menu with an action callback.
void | addItem (int itemResultID, String itemText, bool isEnabled=true, bool isTicked=false)
| Appends a new text item for this menu to show.
void | addItem (int itemResultID, String itemText, bool isEnabled, bool isTicked, const Image &iconToUse)
| Appends a new item with an icon.
void | addItem (int itemResultID, String itemText, bool isEnabled, bool isTicked, std::unique_ptr< Drawable > iconToUse)
| Appends a new item with an icon.
void | addCommandItem (ApplicationCommandManager *commandManager, CommandID commandID, String displayName={}, std::unique_ptr< Drawable > iconToUse={})
| Adds an item that represents one of the commands in a command manager object.
void | addColouredItem (int itemResultID, String itemText, Colour itemTextColour, bool isEnabled=true, bool isTicked=false, const Image &iconToUse={})
| Appends a text item with a special colour.
void | addColouredItem (int itemResultID, String itemText, Colour itemTextColour, bool isEnabled, bool isTicked, std::unique_ptr< Drawable > iconToUse)
| Appends a text item with a special colour.
void | addCustomItem (int itemResultID, std::unique_ptr< CustomComponent > customComponent, std::unique_ptr< const PopupMenu > optionalSubMenu=nullptr, const String &itemTitle={})
| Appends a custom menu item.
void | addCustomItem (int itemResultID, Component &customComponent, int idealWidth, int idealHeight, bool triggerMenuItemAutomaticallyWhenClicked, std::unique_ptr< const PopupMenu > optionalSubMenu=nullptr, const String &itemTitle={})
| Appends a custom menu item that can't be used to trigger a result.
void | addSubMenu (String subMenuName, PopupMenu subMenu, bool isEnabled=true)
| Appends a sub-menu.
void | addSubMenu (String subMenuName, PopupMenu subMenu, bool isEnabled, const Image &iconToUse, bool isTicked=false, int itemResultID=0)
| Appends a sub-menu with an icon.
void | addSubMenu (String subMenuName, PopupMenu subMenu, bool isEnabled, std::unique_ptr< Drawable > iconToUse, bool isTicked=false, int itemResultID=0)
| Appends a sub-menu with an icon.
void | addSeparator ()
| Appends a separator to the menu, to help break it up into sections.
void | addSectionHeader (String title)
| Adds a non-clickable text item to the menu.
void | addColumnBreak ()
| Adds a column break to the menu, to help break it up into sections.
int | getNumItems () const noexcept
| Returns the number of items that the menu currently contains.
bool | containsCommandItem (int commandID) const
| Returns true if the menu contains a command item that triggers the given command.
bool | containsAnyActiveItems () const noexcept
| Returns true if the menu contains any items that can be used.
int | show (int itemIDThatMustBeVisible=0, int minimumWidth=0, int maximumNumColumns=0, int standardItemHeight=0, ModalComponentManager::Callback *callback=nullptr)
| Displays the menu and waits for the user to pick something.
int | showAt (Rectangle< int > screenAreaToAttachTo, int itemIDThatMustBeVisible=0, int minimumWidth=0, int maximumNumColumns=0, int standardItemHeight=0, ModalComponentManager::Callback *callback=nullptr)
| Displays the menu at a specific location.
int | showAt (Component *componentToAttachTo, int itemIDThatMustBeVisible=0, int minimumWidth=0, int maximumNumColumns=0, int standardItemHeight=0, ModalComponentManager::Callback *callback=nullptr)
| Displays the menu as if it's attached to a component such as a button.
int | showMenu (const Options &options)
| Displays and runs the menu modally, with a set of options.
void | showMenuAsync (const Options &options)
| Runs the menu asynchronously.
void | showMenuAsync (const Options &options, ModalComponentManager::Callback *callback)
| Runs the menu asynchronously, with a user-provided callback that will receive the result.
void | showMenuAsync (const Options &options, std::function< void(int)> callback)
| Runs the menu asynchronously, with a user-provided callback that will receive the result.
void | setLookAndFeel (LookAndFeel *newLookAndFeel)
| Specifies a look-and-feel for the menu and any sub-menus that it has.

## Static Public Member Functions

static bool JUCE_CALLTYPE | dismissAllActiveMenus ()
| Closes any menus that are currently open.

## Member Enums

## ColourIds

enum juce::PopupMenu::ColourIds

A set of colour IDs to use to change the colour of various aspects of the menu.

These constants can be used either via the LookAndFeel::setColour() method for the look and feel that is set for this menu with setLookAndFeel()

See also
  setLookAndFeel, LookAndFeel::setColour, LookAndFeel::findColour

Enumerator
backgroundColourId | The colour to fill the menu's background with.
textColourId | The colour for normal menu item text, (unless the colour is specified when the item is added).
headerTextColourId | The colour for section header item text (see the addSectionHeader() method).
highlightedBackgroundColourId | The colour to fill the background of the currently highlighted menu item.
highlightedTextColourId | The colour to use for the text of the currently highlighted item.

## Constructors and Destructors

## PopupMenu() [1/3]

juce::PopupMenu::PopupMenu | ( |  | ) |

default

Creates an empty popup menu.

Referenced by addSubMenu(), addSubMenu(), addSubMenu(), MenuBarComponent, juce::PopupMenu::MenuItemIterator::MenuItemIterator(), operator=(), operator=(), PopupMenu(), and PopupMenu().

## PopupMenu() [2/3]

juce::PopupMenu::PopupMenu | ( | const PopupMenu & |  | ) |

Creates a copy of another menu.

References PopupMenu().

## ~PopupMenu()

juce::PopupMenu::~PopupMenu | ( |  | ) |

Destructor.

## PopupMenu() [3/3]

juce::PopupMenu::PopupMenu | ( | PopupMenu && |  | ) |

noexcept

Move constructor.

References PopupMenu().

## Member Functions

## operator=() [1/2]

PopupMenu & juce::PopupMenu::operator= | ( | const PopupMenu & |  | ) |

Copies this menu from another one.

References PopupMenu().

## operator=() [2/2]

PopupMenu & juce::PopupMenu::operator= | ( | PopupMenu && |  | ) |

noexcept

Move assignment operator.

References PopupMenu().

## clear()

void juce::PopupMenu::clear | ( |  | ) |

Resets the menu, removing all its items.

References clear().

Referenced by clear().

## addItem() [1/6]

void juce::PopupMenu::addItem | ( | Item | newItem | ) |

Adds an item to the menu.

You can call this method for full control over the item that is added, or use the other addItem helper methods if you want to pass arguments rather than creating an Item object.

## addItem() [2/6]

void juce::PopupMenu::addItem | ( | String | itemText,
|  | std::function< void()> | action )

Adds an item to the menu with an action callback.

## addItem() [3/6]

void juce::PopupMenu::addItem | ( | String | itemText,
|  | bool | isEnabled,
|  | bool | isTicked,
|  | std::function< void()> | action )

Adds an item to the menu with an action callback.

## addItem() [4/6]

void juce::PopupMenu::addItem | ( | int | itemResultID,
|  | String | itemText,
|  | bool | isEnabled = true,
|  | bool | isTicked = false )

Appends a new text item for this menu to show.

Parameters

  itemResultID | the number that will be returned from the show() method if the user picks this item. The value should never be zero, because that's used to indicate that the user didn't select anything.
  itemText | the text to show.
  isEnabled | if false, the item will be shown 'greyed-out' and can't be picked
  isTicked | if true, the item will be shown with a tick next to it

See also
  addSeparator, addColouredItem, addCustomItem, addSubMenu

## addItem() [5/6]

void juce::PopupMenu::addItem | ( | int | itemResultID,
|  | String | itemText,
|  | bool | isEnabled,
|  | bool | isTicked,
|  | const Image & | iconToUse )

Appends a new item with an icon.

Parameters

  itemResultID | the number that will be returned from the show() method if the user picks this item. The value should never be zero, because that's used to indicate that the user didn't select anything.
  itemText | the text to show.
  isEnabled | if false, the item will be shown 'greyed-out' and can't be picked
  isTicked | if true, the item will be shown with a tick next to it
  iconToUse | if this is a valid image, it will be displayed to the left of the item.

See also
  addSeparator, addColouredItem, addCustomItem, addSubMenu

## addItem() [6/6]

void juce::PopupMenu::addItem | ( | int | itemResultID,
|  | String | itemText,
|  | bool | isEnabled,
|  | bool | isTicked,
|  | std::unique_ptr< Drawable > | iconToUse )

Appends a new item with an icon.

Parameters

  itemResultID | the number that will be returned from the show() method if the user picks this item. The value should never be zero, because that's used to indicate that the user didn't select anything.
  itemText | the text to show.
  isEnabled | if false, the item will be shown 'greyed-out' and can't be picked
  isTicked | if true, the item will be shown with a tick next to it
  iconToUse | a Drawable object to use as the icon to the left of the item. The menu will take ownership of this drawable object and will delete it later when no longer needed

See also
  addSeparator, addColouredItem, addCustomItem, addSubMenu

## addCommandItem()

void juce::PopupMenu::addCommandItem | ( | ApplicationCommandManager * | commandManager,
|  | CommandID | commandID,
|  | String | displayName = {},
|  | std::unique_ptr< Drawable > | iconToUse = {} )

Adds an item that represents one of the commands in a command manager object.

Parameters

  commandManager | the manager to use to trigger the command and get information about it
  commandID | the ID of the command
  displayName | if this is non-empty, then this string will be used instead of the command's registered name
  iconToUse | an optional Drawable object to use as the icon to the left of the item. The menu will take ownership of this drawable object and will delete it later when no longer needed

## addColouredItem() [1/2]

void juce::PopupMenu::addColouredItem | ( | int | itemResultID,
|  | String | itemText,
|  | Colour | itemTextColour,
|  | bool | isEnabled = true,
|  | bool | isTicked = false,
|  | const Image & | iconToUse = {} )

Appends a text item with a special colour.

This is the same as addItem(), but specifies a colour to use for the text, which will override the default colours that are used by the current look-and-feel. See addItem() for a description of the parameters.

## addColouredItem() [2/2]

void juce::PopupMenu::addColouredItem | ( | int | itemResultID,
|  | String | itemText,
|  | Colour | itemTextColour,
|  | bool | isEnabled,
|  | bool | isTicked,
|  | std::unique_ptr< Drawable > | iconToUse )

Appends a text item with a special colour.

This is the same as addItem(), but specifies a colour to use for the text, which will override the default colours that are used by the current look-and-feel. See addItem() for a description of the parameters.

## addCustomItem() [1/2]

void juce::PopupMenu::addCustomItem | ( | int | itemResultID,
|  | std::unique_ptr< CustomComponent > | customComponent,
|  | std::unique_ptr< const PopupMenu > | optionalSubMenu = nullptr,
|  | const String & | itemTitle = {} )

Appends a custom menu item.

This will add a user-defined component to use as a menu item.

Note that native macOS menus do not support custom components.

itemTitle will be used as the fallback text for this item, and will be exposed to screen reader clients.

See also
  CustomComponent

## addCustomItem() [2/2]

void juce::PopupMenu::addCustomItem | ( | int | itemResultID,
|  | Component & | customComponent,
|  | int | idealWidth,
|  | int | idealHeight,
|  | bool | triggerMenuItemAutomaticallyWhenClicked,
|  | std::unique_ptr< const PopupMenu > | optionalSubMenu = nullptr,
|  | const String & | itemTitle = {} )

Appends a custom menu item that can't be used to trigger a result.

This will add a user-defined component to use as a menu item. The caller must ensure that the passed-in component stays alive until after the menu has been hidden.

If triggerMenuItemAutomaticallyWhenClicked is true, the menu itself will handle detection of a mouse-click on your component, and use that to trigger the menu ID specified in itemResultID. If this is false, the menu item can't be triggered, so itemResultID is not used.

itemTitle will be used as the fallback text for this item, and will be exposed to screen reader clients.

Note that native macOS menus do not support custom components.

## addSubMenu() [1/3]

void juce::PopupMenu::addSubMenu | ( | String | subMenuName,
|  | PopupMenu | subMenu,
|  | bool | isEnabled = true )

Appends a sub-menu.

If the menu that's passed in is empty, it will appear as an inactive item. If the itemResultID argument is non-zero, then the sub-menu item itself can be clicked to trigger it as a command.

References PopupMenu().

## addSubMenu() [2/3]

void juce::PopupMenu::addSubMenu | ( | String | subMenuName,
|  | PopupMenu | subMenu,
|  | bool | isEnabled,
|  | const Image & | iconToUse,
|  | bool | isTicked = false,
|  | int | itemResultID = 0 )

Appends a sub-menu with an icon.

If the menu that's passed in is empty, it will appear as an inactive item. If the itemResultID argument is non-zero, then the sub-menu item itself can be clicked to trigger it as a command.

References PopupMenu().

## addSubMenu() [3/3]

void juce::PopupMenu::addSubMenu | ( | String | subMenuName,
|  | PopupMenu | subMenu,
|  | bool | isEnabled,
|  | std::unique_ptr< Drawable > | iconToUse,
|  | bool | isTicked = false,
|  | int | itemResultID = 0 )

Appends a sub-menu with an icon.

If the menu that's passed in is empty, it will appear as an inactive item. If the itemResultID argument is non-zero, then the sub-menu item itself can be clicked to trigger it as a command.

The iconToUse parameter is a Drawable object to use as the icon to the left of the item. The menu will take ownership of this drawable object and will delete it later when no longer needed

References PopupMenu().

## addSeparator()

void juce::PopupMenu::addSeparator | ( |  | ) |

Appends a separator to the menu, to help break it up into sections.

The menu class is smart enough not to display separators at the top or bottom of the menu, and it will replace multiple adjacent separators with a single one, so your code can be quite free and easy about adding these, and it'll always look ok.

## addSectionHeader()

void juce::PopupMenu::addSectionHeader | ( | String | title | ) |

Adds a non-clickable text item to the menu.

This is a bold-font items which can be used as a header to separate the items into named groups.

## addColumnBreak()

void juce::PopupMenu::addColumnBreak | ( |  | ) |

Adds a column break to the menu, to help break it up into sections.

Subsequent items will be placed in a new column, rather than being appended to the current column.

If a menu contains explicit column breaks, the menu will never add additional breaks.

## getNumItems()

int juce::PopupMenu::getNumItems | ( |  | ) | const

noexcept

Returns the number of items that the menu currently contains.

(This doesn't count separators).

## containsCommandItem()

bool juce::PopupMenu::containsCommandItem | ( | int | commandID | ) | const

Returns true if the menu contains a command item that triggers the given command.

References containsCommandItem().

Referenced by containsCommandItem().

## containsAnyActiveItems()

bool juce::PopupMenu::containsAnyActiveItems | ( |  | ) | const

noexcept

Returns true if the menu contains any items that can be used.

References containsAnyActiveItems().

Referenced by containsAnyActiveItems().

## show()

int juce::PopupMenu::show | ( | int | itemIDThatMustBeVisible = 0,
|  | int | minimumWidth = 0,
|  | int | maximumNumColumns = 0,
|  | int | standardItemHeight = 0,
|  | ModalComponentManager::Callback * | callback = nullptr )

Displays the menu and waits for the user to pick something.

This will display the menu modally, and return the ID of the item that the user picks. If they click somewhere off the menu to get rid of it without choosing anything, this will return 0.

The current location of the mouse will be used as the position to show the menu - to explicitly set the menu's position, use showAt() instead. Depending on where this point is on the screen, the menu will appear above, below or to the side of the point.

Parameters

  itemIDThatMustBeVisible | if you set this to the ID of one of the menu items, then when the menu first appears, it will make sure that this item is visible. So if the menu has too many items to fit on the screen, it will be scrolled to a position where this item is visible.
  minimumWidth | a minimum width for the menu, in pixels. It may be wider than this if some items are too long to fit.
  maximumNumColumns | if there are too many items to fit on-screen in a single vertical column, the menu may be laid out as a series of columns - this is the maximum number allowed. To use the default value for this (probably about 7), you can pass in zero.
  standardItemHeight | if this is non-zero, it will be used as the standard height for menu items (apart from custom items)
  callback | if this is not a nullptr, the menu will be launched asynchronously, returning immediately, and the callback will receive a call when the menu is either dismissed or has an item selected. This object will be owned and deleted by the system, so make sure that it works safely and that any pointers that it uses are safely within scope.

See also
  showAt

## showAt() [1/2]

int juce::PopupMenu::showAt | ( | Rectangle< int > | screenAreaToAttachTo,
|  | int | itemIDThatMustBeVisible = 0,
|  | int | minimumWidth = 0,
|  | int | maximumNumColumns = 0,
|  | int | standardItemHeight = 0,
|  | ModalComponentManager::Callback * | callback = nullptr )

Displays the menu at a specific location.

This is the same as show(), but uses a specific location (in global screen coordinates) rather than the current mouse position.

The screenAreaToAttachTo parameter indicates a screen area to which the menu will be adjacent. Depending on where this is, the menu will decide which edge to attach itself to, in order to fit itself fully on-screen. If you just want to trigger a menu at a specific point, you can pass in a rectangle of size (0, 0) with the position that you want.

See also
  show()

## showAt() [2/2]

int juce::PopupMenu::showAt | ( | Component * | componentToAttachTo,
|  | int | itemIDThatMustBeVisible = 0,
|  | int | minimumWidth = 0,
|  | int | maximumNumColumns = 0,
|  | int | standardItemHeight = 0,
|  | ModalComponentManager::Callback * | callback = nullptr )

Displays the menu as if it's attached to a component such as a button.

This is similar to showAt(), but will position it next to the given component, e.g. so that the menu's edge is aligned with that of the component. This is intended for things like buttons that trigger a pop-up menu.

## showMenu()

int juce::PopupMenu::showMenu | ( | const Options & | options | ) |

Displays and runs the menu modally, with a set of options.

## showMenuAsync() [1/3]

void juce::PopupMenu::showMenuAsync | ( | const Options & | options | ) |

Runs the menu asynchronously.

## showMenuAsync() [2/3]

void juce::PopupMenu::showMenuAsync | ( | const Options & | options,
|  | ModalComponentManager::Callback * | callback )

Runs the menu asynchronously, with a user-provided callback that will receive the result.

## showMenuAsync() [3/3]

void juce::PopupMenu::showMenuAsync | ( | const Options & | options,
|  | std::function< void(int)> | callback )

Runs the menu asynchronously, with a user-provided callback that will receive the result.

## dismissAllActiveMenus()

bool JUCE_CALLTYPE juce::PopupMenu::dismissAllActiveMenus | ( |  | ) |

static

Closes any menus that are currently open.

This might be useful if you have a situation where your window is being closed by some means other than a user action, and you'd like to make sure that menus aren't left hanging around.

References JUCE_CALLTYPE.

## setLookAndFeel()

void juce::PopupMenu::setLookAndFeel | ( | LookAndFeel * | newLookAndFeel | ) |

Specifies a look-and-feel for the menu and any sub-menus that it has.

This can be called before show() if you need a customised menu. Be careful not to delete the LookAndFeel object before the menu has been deleted.

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited