Module javafx.controls
Package javafx.scene.control

# Class Menu

java.lang.Object
javafx.scene.control.MenuItem
javafx.scene.control.Menu

All Implemented Interfaces:
  `Styleable`, `EventTarget`

@DefaultProperty("items") public class Menu extends MenuItem

A popup menu of actionable items which is displayed to the user only upon request. When a menu is visible, in most use cases, the user can select one menu item before the menu goes back to its hidden state. This means the menu is a good place to put important functionality that does not necessarily need to be visible at all times to the user.

Menus are typically placed in a `MenuBar`, or as a submenu of another Menu. If the intention is to offer a context menu when the user right-clicks in a certain area of their user interface, then this is the wrong control to use. This is because when Menu is added to the scenegraph, it has a visual representation that will result in it appearing on screen. Instead, `ContextMenu` should be used in this circumstance.

Creating a Menu and inserting it into a MenuBar is easy, as shown below:

     final Menu menu1 = new Menu("File");
     MenuBar menuBar = new MenuBar();
     menuBar.getMenus().add(menu1);

A Menu is a subclass of `MenuItem` which means that it can be inserted into a Menu's `items` ObservableList, resulting in a submenu being created:

     MenuItem menu12 = new MenuItem("Open");
     menu1.getItems().add(menu12);

The items ObservableList allows for any `MenuItem` type to be inserted, including its subclasses `Menu`, `MenuItem`, `RadioMenuItem`, `CheckMenuItem`, `CustomMenuItem` and `SeparatorMenuItem`. In order to insert an arbitrary `Node` to a Menu, a CustomMenuItem can be used. One exception to this general rule is that `SeparatorMenuItem` could be used for inserting a separator.

Since:
  JavaFX 2.0
See Also:
  - `MenuBar`
  - `MenuItem`

## Property Summary

Properties
Type
Property
Description
`final ObjectProperty<EventHandler<Event>>`
`onHidden`
Called just after the `ContextMenu` has been hidden.
`final ObjectProperty<EventHandler<Event>>`
`onHiding`
Called just prior to the `ContextMenu` being hidden.
`final ObjectProperty<EventHandler<Event>>`
`onShowing`
Called just prior to the `ContextMenu` being shown, even if the menu has no items to show.
`final ObjectProperty<EventHandler<Event>>`
`onShown`
Called just after the `ContextMenu` is shown.
`final ReadOnlyBooleanProperty`
`showing`
Indicates whether the `ContextMenu` is currently visible.

### Properties inherited from class javafx.scene.control.MenuItem

`accelerator, disable, graphic, id, mnemonicParsing, onAction, onMenuValidation, parentMenu, parentPopup, style, text, visible`

## Field Summary

Fields
Modifier and Type
Field
Description
`static final EventType<Event>`
`ON_HIDDEN`
Called when the contextMenu for this menu is hidden.
`static final EventType<Event>`
`ON_HIDING`
Called when the contextMenu for this menu will be hidden.
`static final EventType<Event>`
`ON_SHOWING`
Called when the contextMenu for this menu will be shown.
`static final EventType<Event>`
`ON_SHOWN`
Called when the contextMenu for this menu shows.

### Fields inherited from class javafx.scene.control.MenuItem

`MENU_VALIDATION_EVENT`

## Constructor Summary

Constructors
Constructor
Description
`Menu()`
Constructs a Menu with an empty string for its display text.
`Menu(String text)`
Constructs a Menu and sets the display text with the specified text.
`Menu(String text, Node graphic)`
Constructs a Menu and sets the display text with the specified text and sets the graphic `Node` to the given node.
`Menu(String text, Node graphic, MenuItem... items)`
Constructs a Menu and sets the display text with the specified text, the graphic `Node` to the given node, and inserts the given items into the `items` list.

## Method Summary

Modifier and Type
Method
Description
`<E extends Event>
void`
`addEventHandler(EventType<E> eventType, EventHandler<E> eventHandler)`
Registers an event handler to this MenuItem.
`EventDispatchChain`
`buildEventDispatchChain(EventDispatchChain tail)`
Construct an event dispatch chain for this target.
`final ObservableList<MenuItem>`
`getItems()`
The items to show within this menu.
`final EventHandler<Event>`
`getOnHidden()`
Gets the value of the `onHidden` property.
`final EventHandler<Event>`
`getOnHiding()`
Gets the value of the `onHiding` property.
`final EventHandler<Event>`
`getOnShowing()`
Gets the value of the `onShowing` property.
`final EventHandler<Event>`
`getOnShown()`
Gets the value of the `onShown` property.
`void`
`hide()`
Hides the `ContextMenu` if it was previously showing, and any showing submenus.
`final boolean`
`isShowing()`
Gets the value of the `showing` property.
`final ObjectProperty<EventHandler<Event>>`
`onHiddenProperty()`
Called just after the `ContextMenu` has been hidden.
`final ObjectProperty<EventHandler<Event>>`
`onHidingProperty()`
Called just prior to the `ContextMenu` being hidden.
`final ObjectProperty<EventHandler<Event>>`
`onShowingProperty()`
Called just prior to the `ContextMenu` being shown, even if the menu has no items to show.
`final ObjectProperty<EventHandler<Event>>`
`onShownProperty()`
Called just after the `ContextMenu` is shown.
`<E extends Event>
void`
`removeEventHandler(EventType<E> eventType, EventHandler<E> eventHandler)`
Unregisters a previously registered event handler from this MenuItem.
`final void`
`setOnHidden(EventHandler<Event> value)`
Sets the value of the `onHidden` property.
`final void`
`setOnHiding(EventHandler<Event> value)`
Sets the value of the `onHiding` property.
`final void`
`setOnShowing(EventHandler<Event> value)`
Sets the value of the `onShowing` property.
`final void`
`setOnShown(EventHandler<Event> value)`
Sets the value of the `onShown` property.
`void`
`show()`
If the Menu is not disabled and the `ContextMenu` is not already showing, then this will cause the `ContextMenu` to be shown.
`final ReadOnlyBooleanProperty`
`showingProperty()`
Indicates whether the `ContextMenu` is currently visible.

### Methods inherited from class javafx.scene.control.MenuItem

`acceleratorProperty, disableProperty, fire, getAccelerator, getCssMetaData, getGraphic, getId, getOnAction, getOnMenuValidation, getParentMenu, getParentPopup, getProperties, getPseudoClassStates, getStyle, getStyleableNode, getStyleableParent, getStyleClass, getText, getTypeSelector, getUserData, graphicProperty, idProperty, isDisable, isMnemonicParsing, isVisible, mnemonicParsingProperty, onActionProperty, onMenuValidationProperty, parentMenuProperty, parentPopupProperty, setAccelerator, setDisable, setGraphic, setId, setMnemonicParsing, setOnAction, setOnMenuValidation, setParentMenu, setParentPopup, setStyle, setText, setUserData, setVisible, styleProperty, textProperty, toString, visibleProperty`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Property Details

### showing

public final ReadOnlyBooleanProperty showingProperty
Indicates whether the `ContextMenu` is currently visible.

Default value:
  false
See Also:
  - `isShowing()`
  - `showingProperty()`

### onShowing

public final ObjectProperty<EventHandler<Event>> onShowingProperty
Called just prior to the `ContextMenu` being shown, even if the menu has no items to show. Note however that this won't be called if the menu does not have a valid anchor node.

See Also:
  - `getOnShowing()`
  - `setOnShowing(EventHandler)`
  - `onShowingProperty()`

### onShown

public final ObjectProperty<EventHandler<Event>> onShownProperty
Called just after the `ContextMenu` is shown.

See Also:
  - `getOnShown()`
  - `setOnShown(EventHandler)`
  - `onShownProperty()`

### onHiding

public final ObjectProperty<EventHandler<Event>> onHidingProperty
Called just prior to the `ContextMenu` being hidden.

See Also:
  - `getOnHiding()`
  - `setOnHiding(EventHandler)`
  - `onHidingProperty()`

### onHidden

public final ObjectProperty<EventHandler<Event>> onHiddenProperty
Called just after the `ContextMenu` has been hidden.

See Also:
  - `getOnHidden()`
  - `setOnHidden(EventHandler)`
  - `onHiddenProperty()`

## Field Details

### ON_SHOWING

public static final EventType<Event> ON_SHOWING

Called when the contextMenu for this menu will be shown. However if the contextMenu is empty then this will not be called.

### ON_SHOWN

public static final EventType<Event> ON_SHOWN

Called when the contextMenu for this menu shows. However if the contextMenu is empty then this will not be called.

### ON_HIDING

public static final EventType<Event> ON_HIDING

Called when the contextMenu for this menu will be hidden. However if the contextMenu is empty then this will not be called.

### ON_HIDDEN

public static final EventType<Event> ON_HIDDEN

Called when the contextMenu for this menu is hidden. However if the contextMenu is empty then this will not be called.

## Constructor Details

### Menu

public Menu()
Constructs a Menu with an empty string for its display text.

Since:
  JavaFX 2.2

### Menu

public Menu(String text)
Constructs a Menu and sets the display text with the specified text.

Parameters:
  `text` - the text to display on the menu button

### Menu

public Menu(String text, Node graphic)
Constructs a Menu and sets the display text with the specified text and sets the graphic `Node` to the given node.

Parameters:
  `text` - the text to display on the menu button
  `graphic` - the graphic to display on the menu button

### Menu

public Menu(String text, Node graphic, MenuItem... items)
Constructs a Menu and sets the display text with the specified text, the graphic `Node` to the given node, and inserts the given items into the `items` list.

Parameters:
  `text` - the text to display on the menu button
  `graphic` - the graphic to display on the menu button
  `items` - The items to display in the popup menu.
Since:
  JavaFX 8u40

## Method Details

### isShowing

public final boolean isShowing()
Gets the value of the `showing` property.

Property description:
  Indicates whether the `ContextMenu` is currently visible.
Default value:
  false
Returns:
  the value of the `showing` property
See Also:
  - `showingProperty()`

### showingProperty

public final ReadOnlyBooleanProperty showingProperty()
Indicates whether the `ContextMenu` is currently visible.

Default value:
  false
Returns:
  the `showing` property
See Also:
  - `isShowing()`

### onShowingProperty

public final ObjectProperty<EventHandler<Event>> onShowingProperty()
Called just prior to the `ContextMenu` being shown, even if the menu has no items to show. Note however that this won't be called if the menu does not have a valid anchor node.

Returns:
  the on showing property
See Also:
  - `getOnShowing()`
  - `setOnShowing(EventHandler)`

### setOnShowing

public final void setOnShowing(EventHandler<Event> value)
Sets the value of the `onShowing` property.

Property description:
  Called just prior to the `ContextMenu` being shown, even if the menu has no items to show. Note however that this won't be called if the menu does not have a valid anchor node.
Parameters:
  `value` - the value for the `onShowing` property
See Also:
  - `getOnShowing()`
  - `onShowingProperty()`

### getOnShowing

public final EventHandler<Event> getOnShowing()
Gets the value of the `onShowing` property.

Property description:
  Called just prior to the `ContextMenu` being shown, even if the menu has no items to show. Note however that this won't be called if the menu does not have a valid anchor node.
Returns:
  the value of the `onShowing` property
See Also:
  - `setOnShowing(EventHandler)`
  - `onShowingProperty()`

### onShownProperty

public final ObjectProperty<EventHandler<Event>> onShownProperty()
Called just after the `ContextMenu` is shown.

Returns:
  the on shown property
See Also:
  - `getOnShown()`
  - `setOnShown(EventHandler)`

### setOnShown

public final void setOnShown(EventHandler<Event> value)
Sets the value of the `onShown` property.

Property description:
  Called just after the `ContextMenu` is shown.
Parameters:
  `value` - the value for the `onShown` property
See Also:
  - `getOnShown()`
  - `onShownProperty()`

### getOnShown

public final EventHandler<Event> getOnShown()
Gets the value of the `onShown` property.

Property description:
  Called just after the `ContextMenu` is shown.
Returns:
  the value of the `onShown` property
See Also:
  - `setOnShown(EventHandler)`
  - `onShownProperty()`

### onHidingProperty

public final ObjectProperty<EventHandler<Event>> onHidingProperty()
Called just prior to the `ContextMenu` being hidden.

Returns:
  the on hiding property
See Also:
  - `getOnHiding()`
  - `setOnHiding(EventHandler)`

### setOnHiding

public final void setOnHiding(EventHandler<Event> value)
Sets the value of the `onHiding` property.

Property description:
  Called just prior to the `ContextMenu` being hidden.
Parameters:
  `value` - the value for the `onHiding` property
See Also:
  - `getOnHiding()`
  - `onHidingProperty()`

### getOnHiding

public final EventHandler<Event> getOnHiding()
Gets the value of the `onHiding` property.

Property description:
  Called just prior to the `ContextMenu` being hidden.
Returns:
  the value of the `onHiding` property
See Also:
  - `setOnHiding(EventHandler)`
  - `onHidingProperty()`

### onHiddenProperty

public final ObjectProperty<EventHandler<Event>> onHiddenProperty()
Called just after the `ContextMenu` has been hidden.

Returns:
  the on hidden property
See Also:
  - `getOnHidden()`
  - `setOnHidden(EventHandler)`

### setOnHidden

public final void setOnHidden(EventHandler<Event> value)
Sets the value of the `onHidden` property.

Property description:
  Called just after the `ContextMenu` has been hidden.
Parameters:
  `value` - the value for the `onHidden` property
See Also:
  - `getOnHidden()`
  - `onHiddenProperty()`

### getOnHidden

public final EventHandler<Event> getOnHidden()
Gets the value of the `onHidden` property.

Property description:
  Called just after the `ContextMenu` has been hidden.
Returns:
  the value of the `onHidden` property
See Also:
  - `setOnHidden(EventHandler)`
  - `onHiddenProperty()`

### getItems

public final ObservableList<MenuItem> getItems()
The items to show within this menu. If this ObservableList is modified at runtime, the Menu will update as expected.

Returns:
  the list of items

### show

public void show()
If the Menu is not disabled and the `ContextMenu` is not already showing, then this will cause the `ContextMenu` to be shown.

### hide

public void hide()
Hides the `ContextMenu` if it was previously showing, and any showing submenus. If this menu is not showing, then invoking this function has no effect.

### addEventHandler

public <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<E> eventHandler)
Registers an event handler to this MenuItem. The handler is called when the menu item receives an `Event` of the specified type during the bubbling phase of event delivery.

Overrides:
  `addEventHandler` in class `MenuItem`
Type Parameters:
  `E` - the specific event class of the handler
Parameters:
  `eventType` - the type of the events to receive by the handler
  `eventHandler` - the handler to register

### removeEventHandler

public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<E> eventHandler)
Unregisters a previously registered event handler from this MenuItem. One handler might have been registered for different event types, so the caller needs to specify the particular event type from which to unregister the handler.

Overrides:
  `removeEventHandler` in class `MenuItem`
Type Parameters:
  `E` - the specific event class of the handler
Parameters:
  `eventType` - the event type from which to unregister
  `eventHandler` - the handler to unregister

### buildEventDispatchChain

public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail)
Construct an event dispatch chain for this target. The event dispatch chain contains event dispatchers which might be interested in processing of events targeted at this `EventTarget`. This event target is not automatically added to the chain, so if it wants to process events, it needs to add an `EventDispatcher` for itself to the chain.

In the case the event target is part of some hierarchy, the chain for it is usually built from event dispatchers collected from the root of the hierarchy to the event target.

The event dispatch chain is constructed by modifications to the provided initial event dispatch chain. The returned chain should have the initial chain at its end so the dispatchers should be prepended to the initial chain.

The caller shouldn't assume that the initial chain remains unchanged nor that the returned value will reference a different chain.

Specified by:
  `buildEventDispatchChain` in interface `EventTarget`
Overrides:
  `buildEventDispatchChain` in class `MenuItem`
Parameters:
  `tail` - the initial chain to build from
Returns:
  the resulting event dispatch chain for this target