PopupMenu Class Reference

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

Classes
class	MenuItemIterator
	Allows you to iterate through the items in a pop-up menu, and examine their properties. 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 ()
	Creates an empty popup menu.
	PopupMenu (const PopupMenu &other)
	Creates a copy of another menu.
	~PopupMenu ()
	Destructor.
PopupMenu &	operator= (const PopupMenu &other)
	Copies this menu from another one.
void	clear ()
	Resets the menu, removing all its items.
void	addItem (int itemResultId, const String &itemText, bool isActive=true, bool isTicked=false, const Image *iconToUse=0)
	Appends a new text item for this menu to show.
void	addCommandItem (ApplicationCommandManager *commandManager, int commandID, const String &displayName=String::empty)
	Adds an item that represents one of the commands in a command manager object.
void	addColouredItem (int itemResultId, const String &itemText, const Colour &itemTextColour, bool isActive=true, bool isTicked=false, const Image *iconToUse=0)
	Appends a text item with a special colour.
void	addCustomItem (int itemResultId, PopupMenuCustomComponent *customComponent)
	Appends a custom menu item.
void	addCustomItem (int itemResultId, Component *customComponent, int idealWidth, int idealHeight, bool triggerMenuItemAutomaticallyWhenClicked)
	Appends a custom menu item that can't be used to trigger a result.
void	addSubMenu (const String &subMenuName, const PopupMenu &subMenu, bool isActive=true, Image *iconToUse=0, bool isTicked=false)
	Appends a sub-menu.
void	addSeparator ()
	Appends a separator to the menu, to help break it up into sections.
void	addSectionHeader (const String &title)
	Adds a non-clickable text item to the menu.
int	getNumItems () const throw ()
	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 throw ()
	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)
	Displays the menu and waits for the user to pick something.
int	showAt (int screenX, int screenY, int itemIdThatMustBeVisible=0, int minimumWidth=0, int maximumNumColumns=0, int standardItemHeight=0)
	Displays the menu at a specific location.
int	showAt (Component *componentToAttachTo, int itemIdThatMustBeVisible=0, int minimumWidth=0, int maximumNumColumns=0, int standardItemHeight=0)
	Displays the menu as if it's attached to a component such as a button.
void	setLookAndFeel (LookAndFeel *newLookAndFeel)
	Specifies a look-and-feel for the menu and any sub-menus that it has.
Static Public Member Functions
static void JUCE_CALLTYPE	dismissAllActiveMenus ()
	Closes any menus that are currently open.

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

        const int result = m.show();

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

        const int result = m.show();

        ...etc
    }

Member Enumeration Documentation

enum 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.

Constructor & Destructor Documentation

PopupMenu::PopupMenu ( )

Creates an empty popup menu.

PopupMenu::PopupMenu ( const PopupMenu & other )

Creates a copy of another menu.

PopupMenu::~PopupMenu ( )

Destructor.

Member Function Documentation

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

Copies this menu from another one.

void PopupMenu::clear ( )

Resets the menu, removing all its items.

void PopupMenu::addItem	(	int	itemResultId,
		const String &	itemText,
		bool	isActive = `true`,
		bool	isTicked = `false`,
		const Image *	iconToUse = `0`
	)

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.
	isActive	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 non-zero, it should be an image that will be displayed to the left of the item. This method will take its own copy of the image passed-in, so there's no need to keep it hanging around.

See also:: addSeparator, addColouredItem, addCustomItem, addSubMenu

void PopupMenu::addCommandItem	(	ApplicationCommandManager *	commandManager,
		int	commandID,
		const String &	displayName = `String::empty`
	)

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

void PopupMenu::addColouredItem	(	int	itemResultId,
		const String &	itemText,
		const Colour &	itemTextColour,
		bool	isActive = `true`,
		bool	isTicked = `false`,
		const Image *	iconToUse = `0`
	)

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.

void PopupMenu::addCustomItem	(	int	itemResultId,
		PopupMenuCustomComponent *	customComponent
	)

Appends a custom menu item.

This will add a user-defined component to use as a menu item. The component passed in will be deleted by this menu when it's no longer needed.

See also:: PopupMenuCustomComponent

void PopupMenu::addCustomItem	(	int	itemResultId,
		Component *	customComponent,
		int	idealWidth,
		int	idealHeight,
		bool	triggerMenuItemAutomaticallyWhenClicked
	)

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. Unlike the addCustomItem() method that takes a PopupMenuCustomComponent, this version can't trigger a result from it, so doesn't take a menu ID. It also doesn't delete the component when it's finished, so it's the caller's responsibility to manage the component that is passed-in.

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.

See also:: PopupMenuCustomComponent

void PopupMenu::addSubMenu	(	const String &	subMenuName,
		const PopupMenu &	subMenu,
		bool	isActive = `true`,
		Image *	iconToUse = `0`,
		bool	isTicked = `false`
	)

Appends a sub-menu.

If the menu that's passed in is empty, it will appear as an inactive item.

void 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 mutliple adjacent separators with a single one, so your code can be quite free and easy about adding these, and it'll always look ok.

void PopupMenu::addSectionHeader ( const 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.

int PopupMenu::getNumItems ( ) const throw ()

Returns the number of items that the menu currently contains.

(This doesn't count separators).

bool PopupMenu::containsCommandItem ( int commandID ) const

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

bool PopupMenu::containsAnyActiveItems ( ) const throw ()

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

int PopupMenu::show	(	int	itemIdThatMustBeVisible = `0`,
		int	minimumWidth = `0`,
		int	maximumNumColumns = `0`,
		int	standardItemHeight = `0`
	)

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)

See also:: showAt

int PopupMenu::showAt	(	int	screenX,
		int	screenY,
		int	itemIdThatMustBeVisible = `0`,
		int	minimumWidth = `0`,
		int	maximumNumColumns = `0`,
		int	standardItemHeight = `0`
	)

Displays the menu at a specific location.

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

Note that the co-ordinates don't specify the top-left of the menu - they indicate a point of interest, and the menu will position itself nearby to this point, trying to keep it fully on-screen.

See also:: show()

int PopupMenu::showAt	(	Component *	componentToAttachTo,
		int	itemIdThatMustBeVisible = `0`,
		int	minimumWidth = `0`,
		int	maximumNumColumns = `0`,
		int	standardItemHeight = `0`
	)

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.

static void JUCE_CALLTYPE 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.

void 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.

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

juce_PopupMenu.h

PopupMenu Class Reference

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation