JUCE: PopupMenu::Options Class Reference

JUCE

Public Types | Public Member Functions | List of all members
PopupMenu::Options Class Reference
juce_gui_basics » menus

Class used to create a set of options to pass to the show() method. More...

`#include <juce_PopupMenu.h>`

## Public Types
enum class | PopupDirection { upwards , downwards }

## Public Member Functions
| Options ()
| By default, the target screen area will be the current mouse position. More...
| Options (const Options &)=default
Options & | operator= (const Options &)=default
JUCE_NODISCARD Options | withTargetComponent (Component *targetComponent) const
| Sets the target component to use when displaying the menu. More...
JUCE_NODISCARD Options | withTargetComponent (Component &targetComponent) const
JUCE_NODISCARD Options | withTargetScreenArea (Rectangle< int > targetArea) const
| Sets the region of the screen next to which the menu should be displayed. More...
JUCE_NODISCARD Options | withMousePosition () const
| Sets the target screen area to match the current mouse position. More...
JUCE_NODISCARD Options | withDeletionCheck (Component &componentToWatchForDeletion) const
| If the passed component has been deleted when the popup menu exits, the selected item's action will not be called. More...
JUCE_NODISCARD Options | withMinimumWidth (int minWidth) const
| Sets the minimum width of the popup window. More...
JUCE_NODISCARD Options | withMinimumNumColumns (int minNumColumns) const
| Sets the minimum number of columns in the popup window. More...
JUCE_NODISCARD Options | withMaximumNumColumns (int maxNumColumns) const
| Sets the maximum number of columns in the popup window. More...
JUCE_NODISCARD Options | withStandardItemHeight (int standardHeight) const
| Sets the default height of each item in the popup menu. More...
JUCE_NODISCARD Options | withItemThatMustBeVisible (int idOfItemToBeVisible) const
| Sets an item which must be visible when the menu is initially drawn. More...
JUCE_NODISCARD Options | withParentComponent (Component *parentComponent) const
| Sets a component that the popup menu will be drawn into. More...
JUCE_NODISCARD Options | withPreferredPopupDirection (PopupDirection direction) const
| Sets the direction of the popup menu relative to the target screen area. More...
JUCE_NODISCARD Options | withInitiallySelectedItem (int idOfItemToBeSelected) const
| Sets an item to select in the menu. More...
Component * | getParentComponent () const noexcept
| Gets the parent component. More...
Component * | getTargetComponent () const noexcept
| Gets the target component. More...
bool | hasWatchedComponentBeenDeleted () const noexcept
| Returns true if the menu was watching a component, and that component has been deleted, and false otherwise. More...
Rectangle< int > | getTargetScreenArea () const noexcept
| Gets the target screen area. More...
int | getMinimumWidth () const noexcept
| Gets the minimum width. More...
int | getMaximumNumColumns () const noexcept
| Gets the maximum number of columns. More...
int | getMinimumNumColumns () const noexcept
| Gets the minimum number of columns. More...
int | getStandardItemHeight () const noexcept
| Gets the default height of items in the menu. More...
int | getItemThatMustBeVisible () const noexcept
| Gets the ID of the item that must be visible when the menu is initially shown. More...
PopupDirection | getPreferredPopupDirection () const noexcept
| Gets the preferred popup menu direction. More...
int | getInitiallySelectedItemId () const noexcept
| Gets the ID of the item that must be selected when the menu is initially shown. More...

## Detailed Description

Class used to create a set of options to pass to the show() method.

You can chain together a series of calls to this class's methods to create a set of whatever options you want to specify. E.g.

PopupMenu menu;
...
menu.showMenu (PopupMenu::Options().withMinimumWidth (100)
.withMaximumNumColumns (3)
.withTargetComponent (myComp));
PopupMenu::Options
Class used to create a set of options to pass to the show() method.
Definition: juce_PopupMenu.h:458
PopupMenu::Options::withTargetComponent
JUCE_NODISCARD Options withTargetComponent(Component *targetComponent) const
Sets the target component to use when displaying the menu.
PopupMenu::Options::withMinimumWidth
JUCE_NODISCARD Options withMinimumWidth(int minWidth) const
Sets the minimum width of the popup window.
PopupMenu::Options::withMaximumNumColumns
JUCE_NODISCARD Options withMaximumNumColumns(int maxNumColumns) const
Sets the maximum number of columns in the popup window.
PopupMenu
Creates and displays a popup-menu.
Definition: juce_PopupMenu.h:81
PopupMenu::showMenu
int showMenu(const Options &options)
Displays and runs the menu modally, with a set of options.

## Member Enumeration Documentation

## ◆ PopupDirection

enum class PopupMenu::Options::PopupDirection
| strong

Enumerator
upwards |
downwards |

## Constructor & Destructor Documentation

## ◆ Options() [1/2]

PopupMenu::Options::Options | ( |  | ) |

By default, the target screen area will be the current mouse position.

## ◆ Options() [2/2]

PopupMenu::Options::Options | ( | const Options & |  | ) |
| default

## Member Function Documentation

## ◆ operator=()

Options & PopupMenu::Options::operator= | ( | const Options & |  | ) |
| default

## ◆ withTargetComponent() [1/2]

JUCE_NODISCARD Options PopupMenu::Options::withTargetComponent | ( | Component * | targetComponent | ) | const

Sets the target component to use when displaying the menu.

This is normally the button or other control that triggered the menu.

The target component is primarily used to control the scale of the menu, so it's important to supply a target component if you'll be using your program on hi-DPI displays.

This function will also set the target screen area, so that the menu displays next to the target component. If you need to display the menu at a specific location, you should call withTargetScreenArea() after withTargetComponent.

See also
  withTargetComponent, withTargetScreenArea

## ◆ withTargetComponent() [2/2]

JUCE_NODISCARD Options PopupMenu::Options::withTargetComponent | ( | Component & | targetComponent | ) | const

## ◆ withTargetScreenArea()

JUCE_NODISCARD Options PopupMenu::Options::withTargetScreenArea | ( | Rectangle< int > | targetArea | ) | const

Sets the region of the screen next to which the menu should be displayed.

To display the menu next to the mouse cursor use withMousePosition(), which is equivalent to passing the following to this function:

Rectangle<int>{}.withPosition (Desktop::getMousePosition())
Desktop::getMousePosition
static Point< int > getMousePosition()
Returns the mouse position.
Rectangle< int >
Rectangle::withPosition
JUCE_NODISCARD Rectangle withPosition(ValueType newX, ValueType newY) const noexcept
Returns a rectangle with the same size as this one, but a new position.
Definition: juce_Rectangle.h:233

withTargetComponent() will also set the target screen area. If you need a target component and a target screen area, make sure to call withTargetScreenArea() after withTargetComponent().

See also
  withMousePosition

## ◆ withMousePosition()

JUCE_NODISCARD Options PopupMenu::Options::withMousePosition | ( |  | ) | const

Sets the target screen area to match the current mouse position.

Make sure to call this after withTargetComponent().

See also
  withTargetScreenArea

## ◆ withDeletionCheck()

JUCE_NODISCARD Options PopupMenu::Options::withDeletionCheck | ( | Component & | componentToWatchForDeletion | ) | const

If the passed component has been deleted when the popup menu exits, the selected item's action will not be called.

This is useful for avoiding dangling references inside the action callback, in the case that the callback needs to access a component that may be deleted.

## ◆ withMinimumWidth()

JUCE_NODISCARD Options PopupMenu::Options::withMinimumWidth | ( | int | minWidth | ) | const

Sets the minimum width of the popup window.

## ◆ withMinimumNumColumns()

JUCE_NODISCARD Options PopupMenu::Options::withMinimumNumColumns | ( | int | minNumColumns | ) | const

Sets the minimum number of columns in the popup window.

## ◆ withMaximumNumColumns()

JUCE_NODISCARD Options PopupMenu::Options::withMaximumNumColumns | ( | int | maxNumColumns | ) | const

Sets the maximum number of columns in the popup window.

## ◆ withStandardItemHeight()

JUCE_NODISCARD Options PopupMenu::Options::withStandardItemHeight | ( | int | standardHeight | ) | const

Sets the default height of each item in the popup menu.

## ◆ withItemThatMustBeVisible()

JUCE_NODISCARD Options PopupMenu::Options::withItemThatMustBeVisible | ( | int | idOfItemToBeVisible | ) | const

Sets an item which must be visible when the menu is initially drawn.

This is useful to ensure that a particular item is shown when the menu contains too many items to display on a single screen.

## ◆ withParentComponent()

JUCE_NODISCARD Options PopupMenu::Options::withParentComponent | ( | Component * | parentComponent | ) | const

Sets a component that the popup menu will be drawn into.

Some plugin formats, such as AUv3, dislike it when the plugin editor spawns additional windows. Some AUv3 hosts display pink backgrounds underneath transparent popup windows, which is confusing and can appear as though the plugin is malfunctioning. Setting a parent component will avoid this unwanted behaviour, but with the downside that the menu size will be constrained by the size of the parent component.

## ◆ withPreferredPopupDirection()

JUCE_NODISCARD Options PopupMenu::Options::withPreferredPopupDirection | ( | PopupDirection | direction | ) | const

Sets the direction of the popup menu relative to the target screen area.

## ◆ withInitiallySelectedItem()

JUCE_NODISCARD Options PopupMenu::Options::withInitiallySelectedItem | ( | int | idOfItemToBeSelected | ) | const

Sets an item to select in the menu.

This is useful for controls such as combo boxes, where opening the combo box with the keyboard should ideally highlight the currently-selected item, allowing the next/previous item to be selected by pressing up/down on the keyboard, rather than needing to move the highlighted row down from the top of the menu each time it is opened.

## ◆ getParentComponent()

Component * PopupMenu::Options::getParentComponent | ( |  | ) | const
| noexcept

Gets the parent component.

This may be nullptr if the Component has been deleted.

See also
  withParentComponent

## ◆ getTargetComponent()

Component * PopupMenu::Options::getTargetComponent | ( |  | ) | const
| noexcept

Gets the target component.

This may be nullptr if the Component has been deleted.

See also
  withTargetComponent

## ◆ hasWatchedComponentBeenDeleted()

bool PopupMenu::Options::hasWatchedComponentBeenDeleted | ( |  | ) | const
| noexcept

Returns true if the menu was watching a component, and that component has been deleted, and false otherwise.

See also
  withDeletionCheck

## ◆ getTargetScreenArea()

Rectangle< int > PopupMenu::Options::getTargetScreenArea | ( |  | ) | const
| noexcept

Gets the target screen area.

See also
  withTargetScreenArea

## ◆ getMinimumWidth()

int PopupMenu::Options::getMinimumWidth | ( |  | ) | const
| noexcept

Gets the minimum width.

See also
  withMinimumWidth

## ◆ getMaximumNumColumns()

int PopupMenu::Options::getMaximumNumColumns | ( |  | ) | const
| noexcept

Gets the maximum number of columns.

See also
  withMaximumNumColumns

## ◆ getMinimumNumColumns()

int PopupMenu::Options::getMinimumNumColumns | ( |  | ) | const
| noexcept

Gets the minimum number of columns.

See also
  withMinimumNumColumns

## ◆ getStandardItemHeight()

int PopupMenu::Options::getStandardItemHeight | ( |  | ) | const
| noexcept

Gets the default height of items in the menu.

See also
  withStandardItemHeight

## ◆ getItemThatMustBeVisible()

int PopupMenu::Options::getItemThatMustBeVisible | ( |  | ) | const
| noexcept

Gets the ID of the item that must be visible when the menu is initially shown.

See also
  withItemThatMustBeVisible

## ◆ getPreferredPopupDirection()

PopupDirection PopupMenu::Options::getPreferredPopupDirection | ( |  | ) | const
| noexcept

Gets the preferred popup menu direction.

See also
  withPreferredPopupDirection

## ◆ getInitiallySelectedItemId()

int PopupMenu::Options::getInitiallySelectedItemId | ( |  | ) | const
| noexcept

Gets the ID of the item that must be selected when the menu is initially shown.

See also
  withItemThatMustBeVisible

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

- juce_PopupMenu.h