juce::PopupMenu Class Reference

Creates and displays a popup-menu. More...

#include "juce_PopupMenu.h"

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

Public Types
enum	ColourIds {   backgroundColourId , textColourId , headerTextColourId , highlightedBackgroundColourId ,   highlightedTextColourId }
	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	addCommandItem (ApplicationCommandManager *commandManager, CommandID commandID, String displayName={})
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.
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.

Friends
struct	HelperClasses
class	MenuBarComponent

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
                         }
                     });
}

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 (...);
}

@tags{GUI}

Definition at line 79 of file juce_PopupMenu.h.

Member Enumeration Documentation

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.

Definition at line 777 of file juce_PopupMenu.h.

Constructor & Destructor Documentation

PopupMenu() [1/2]

juce::PopupMenu::PopupMenu

(

const PopupMenu &

other

)

Creates a copy of another menu.

Definition at line 1603 of file juce_PopupMenu.cpp.

PopupMenu() [2/2]

juce::PopupMenu::PopupMenu ( PopupMenu &&  other )

noexcept

Move constructor.

Definition at line 1620 of file juce_PopupMenu.cpp.

Member Function Documentation

addColouredItem() [1/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.

Definition at line 1861 of file juce_PopupMenu.cpp.

addColouredItem() [2/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.

Definition at line 1873 of file juce_PopupMenu.cpp.

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.

Definition at line 1961 of file juce_PopupMenu.cpp.

addCommandItem() [1/2]

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

Definition at line 1838 of file juce_PopupMenu.cpp.

addCommandItem() [2/2]

void juce::PopupMenu::addCommandItem	(	ApplicationCommandManager *	commandManager,
		CommandID	commandID,
		String	displayName = {}
	)

Definition at line 1831 of file juce_PopupMenu.cpp.

addCustomItem() [1/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.

Definition at line 1907 of file juce_PopupMenu.cpp.

addCustomItem() [2/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

Definition at line 1885 of file juce_PopupMenu.cpp.

addItem() [1/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

Definition at line 1815 of file juce_PopupMenu.cpp.

addItem() [2/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

Definition at line 1820 of file juce_PopupMenu.cpp.

addItem() [3/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

Definition at line 1794 of file juce_PopupMenu.cpp.

addItem() [4/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.

Definition at line 1769 of file juce_PopupMenu.cpp.

addItem() [5/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.

Definition at line 1785 of file juce_PopupMenu.cpp.

addItem() [6/6]

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

Adds an item to the menu with an action callback.

Definition at line 1780 of file juce_PopupMenu.cpp.

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.

Definition at line 1953 of file juce_PopupMenu.cpp.

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.

Definition at line 1943 of file juce_PopupMenu.cpp.

addSubMenu() [1/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.

Definition at line 1924 of file juce_PopupMenu.cpp.

addSubMenu() [2/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

Definition at line 1931 of file juce_PopupMenu.cpp.

addSubMenu() [3/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.

Definition at line 1919 of file juce_PopupMenu.cpp.

clear()

void juce::PopupMenu::clear

(

)

Resets the menu, removing all its items.

Definition at line 1635 of file juce_PopupMenu.cpp.

containsAnyActiveItems()

bool juce::PopupMenu::containsAnyActiveItems ( ) const

noexcept

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

Definition at line 2267 of file juce_PopupMenu.cpp.

containsCommandItem()

bool juce::PopupMenu::containsCommandItem

(

int

commandID

)

const

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

Definition at line 2257 of file juce_PopupMenu.cpp.

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.

Definition at line 2228 of file juce_PopupMenu.cpp.

getNumItems()

int juce::PopupMenu::getNumItems ( ) const

noexcept

Returns the number of items that the menu currently contains.

(This doesn't count separators).

Definition at line 2246 of file juce_PopupMenu.cpp.

operator=() [1/2]

PopupMenu & juce::PopupMenu::operator=

(

const PopupMenu &

other

)

Copies this menu from another one.

Definition at line 1609 of file juce_PopupMenu.cpp.

operator=() [2/2]

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

noexcept

Move assignment operator.

Definition at line 1626 of file juce_PopupMenu.cpp.

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.

Definition at line 2285 of file juce_PopupMenu.cpp.

showMenuAsync() [1/3]

void juce::PopupMenu::showMenuAsync

(

const Options &

options

)

Runs the menu asynchronously.

Definition at line 2166 of file juce_PopupMenu.cpp.

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.

Definition at line 2171 of file juce_PopupMenu.cpp.

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.

Definition at line 2180 of file juce_PopupMenu.cpp.

Friends And Related Symbol Documentation

HelperClasses

friend struct HelperClasses

friend

Definition at line 1051 of file juce_PopupMenu.h.

MenuBarComponent

friend class MenuBarComponent

friend

Definition at line 1052 of file juce_PopupMenu.h.

---

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

• juce_gui_basics/menus/juce_PopupMenu.h
• juce_gui_basics/menus/juce_PopupMenu.cpp