Package org.pushingpixels.flamingo.api.ribbon

# Class RibbonApplicationMenu

java.lang.Object
org.pushingpixels.flamingo.api.ribbon.RibbonApplicationMenu

public class RibbonApplicationMenu extends Object
Metadata description of the application menu of the `JRibbon` component. The ribbon application menu has three parts:

     +-------------------------------------+
     |           |                         |
     |           |                         |
     |  primary  |        secondary        |
     |   area    |           area          |
     |           |                         |
     |           |                         |
     |-------------------------------------|
     |            footer area              |
     +-------------------------------------+

The entries in the primary area are always visible. The secondary area entries are shown based on the currently active element in the primary area. There are three different types of primary entries:

- Associated `ActionListener` passed to the constructor of the `RibbonApplicationMenuEntryPrimary`. When this entry is armed (with mouse rollover or via keyboard navigation), the contents of the secondary area are cleared. The `Quit` menu item is an example of such a primary menu entry.
- Associated `RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback` set by the `RibbonApplicationMenuEntryPrimary.setRolloverCallback(PrimaryRolloverCallback)` . When this entry is armed (with mouse rollover or via keyboard navigation), the contents of the secondary area are populated by the application callback implementation of `RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback.menuEntryActivated(javax.swing.JPanel)`. The `Open` menu item is an example of such a primary menu entry, showing a list of recently opened files.
- Associated list of `RibbonApplicationMenuEntrySecondary`s added with the `RibbonApplicationMenuEntryPrimary.addSecondaryMenuGroup(String, RibbonApplicationMenuEntrySecondary...)` API. When this entry is armed (with mouse rollover or via keyboard navigation), the secondary area shows menu buttons for the registered secondary menu entries. The `Save As` menu item is an example of such a primary menu item, showing a list of default save formats.

At runtime, the application menu entries are implemented as `JCommandMenuButton`, but the application code does not operate on that level. Instead, the application code creates metadata-driven description of the ribbon application menu, and that description is used to create and populate the "real" controls of the application menu popup.

Note that once a `RibbonApplicationMenu` is set on the `JRibbon` with the `JRibbon.setApplicationMenu(RibbonApplicationMenu)`, its contents cannot be changed. An `IllegalStateException` will be thrown from `addMenuEntry(RibbonApplicationMenuEntryPrimary)` and `addFooterEntry(RibbonApplicationMenuEntryFooter)`.

## Constructor Summary

Constructors
Constructor
Description
`RibbonApplicationMenu()`
Creates an empty ribbon application menu.

## Method Summary

Modifier and Type
Method
Description
`void`
`addFooterEntry(RibbonApplicationMenuEntryFooter entry)`
Adds the specified footer menu entry.
`void`
`addMenuEntry(RibbonApplicationMenuEntryPrimary entry)`
Adds the specified primary menu entry.
`void`
`addMenuSeparator()`
`RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback`
`getDefaultCallback()`
Returns the default callback of this ribbon application menu.
`List<RibbonApplicationMenuEntryFooter>`
`getFooterEntries()`
Returns an unmodifiable list of all footer menu entries of this application menu.
`List<List<RibbonApplicationMenuEntryPrimary>>`
`getPrimaryEntries()`
Returns an unmodifiable list of all primary menu entries of this application menu.
`void`
`setDefaultCallback(RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback defaultCallback)`
Sets the default callback to be called when: The ribbon application menu is first shown. The currently active (rollover) primary application menu entry has no secondary menu entries and no associated rollover callback.

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

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

## Constructor Details

### RibbonApplicationMenu

public RibbonApplicationMenu()
Creates an empty ribbon application menu.

## Method Details

### addMenuEntry

public void addMenuEntry(RibbonApplicationMenuEntryPrimary entry)
Adds the specified primary menu entry.

Parameters:
  `entry` - Primary menu entry to add.
Throws:
  `IllegalStateException` - if this ribbon application menu has already been set on the `JRibbon` with the `JRibbon.setApplicationMenu(RibbonApplicationMenu)`.
See Also:
  - `getPrimaryEntries()`
  - `addFooterEntry(RibbonApplicationMenuEntryFooter)`

### addMenuSeparator

public void addMenuSeparator()

### getPrimaryEntries

public List<List<RibbonApplicationMenuEntryPrimary>> getPrimaryEntries()
Returns an unmodifiable list of all primary menu entries of this application menu. The result is guaranteed to be non-`null`.

Returns:
  An unmodifiable list of all primary menu entries of this application menu.
See Also:
  - `addMenuEntry(RibbonApplicationMenuEntryPrimary)`
  - `getFooterEntries()`

### addFooterEntry

public void addFooterEntry(RibbonApplicationMenuEntryFooter entry)
Adds the specified footer menu entry.

Parameters:
  `entry` - Footer menu entry to add.
Throws:
  `IllegalStateException` - if this ribbon application menu has already been set on the `JRibbon` with the `JRibbon.setApplicationMenu(RibbonApplicationMenu)`.
See Also:
  - `getFooterEntries()`
  - `addMenuEntry(RibbonApplicationMenuEntryPrimary)`

### getFooterEntries

public List<RibbonApplicationMenuEntryFooter> getFooterEntries()
Returns an unmodifiable list of all footer menu entries of this application menu. The result is guaranteed to be non-`null`.

Returns:
  An unmodifiable list of all footer menu entries of this application menu.
See Also:
  - `addFooterEntry(RibbonApplicationMenuEntryFooter)`
  - `getPrimaryEntries()`

### setDefaultCallback

public void setDefaultCallback(RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback defaultCallback)
Sets the default callback to be called when:

- The ribbon application menu is first shown.
- The currently active (rollover) primary application menu entry has no secondary menu entries and no associated rollover callback.

Parameters:
  `defaultCallback` - Default callback.

### getDefaultCallback

public RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback getDefaultCallback()
Returns the default callback of this ribbon application menu.

Returns:
  The default callback of this ribbon application menu.
See Also:
  - `setDefaultCallback(org.pushingpixels.flamingo.api.ribbon.RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback)`