Package org.pushingpixels.flamingo.api.ribbon

# Class RibbonApplicationMenuEntryPrimary

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

public class RibbonApplicationMenuEntryPrimary extends Object
Metadata description for the primary menu entries of the `RibbonApplicationMenu`. The primary menu entries at runtime are represented by command menu buttons placed in the left panel of the application menu.

There are three different types of primary entries:

- Associated `ActionListener` passed to the `RibbonApplicationMenuEntryPrimary(org.pushingpixels.flamingo.api.common.icon.ResizableIcon, String, java.awt.event.ActionListener, org.pushingpixels.flamingo.api.common.JCommandButton.CommandButtonKind)` . 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 `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 `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.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static interface`
`RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback`
Callback that allows application code to provide custom content on the secondary panel of the `RibbonApplicationMenu`.

## Field Summary

Fields
Modifier and Type
Field
Description
`protected String`
`actionKeyTip`
Optional key tip for the action area of the command button that represents this menu entry.
`protected RichTooltip`
`actionRichTooltip`
Optional tooltip for the action area of the command button that represents this menu entry.
`protected ResizableIcon`
`disabledIcon`
The menu icon for disabled state.
`protected JCommandButton.CommandButtonKind`
`entryKind`
The kind of the command button that represents this menu entry.
`protected List<List<RibbonApplicationMenuEntrySecondary>>`
`groupEntries`
List of all menu groups.
`protected List<String>`
`groupTitles`
List of titles for all menu groups.
`protected ResizableIcon`
`icon`
The menu icon.
`protected boolean`
`isEnabled`
Enabled state of this menu.
`protected ActionListener`
`mainActionListener`
The main action listener for this menu entry.
`protected String`
`popupKeyTip`
Optional key tip for the popup area of the command button that represents this menu entry.
`protected RichTooltip`
`popupRichTooltip`
Optional tooltip for the popup area of the command button that represents this menu entry.
`protected RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback`
`rolloverCallback`
An optional rollover callback.
`protected String`
`text`
The menu text.

## Constructor Summary

Constructors
Constructor
Description
`RibbonApplicationMenuEntryPrimary(ResizableIcon icon, String text, ActionListener mainActionListener, JCommandButton.CommandButtonKind entryKind)`
Creates the metadata description of a `RibbonApplicationMenu` primary menu entry.

## Method Summary

Modifier and Type
Method
Description
`int`
`addSecondaryMenuGroup(String groupTitle, RibbonApplicationMenuEntrySecondary... entries)`
Adds a titled group of secondary menu entries.
`String`
`getActionKeyTip()`
Returns the key tip for the action area of the command button that represents this menu entry.
`RichTooltip`
`getActionRichTooltip()`
Returns the rich tooltip for the action area of the command button that represents this menu entry.
`ResizableIcon`
`getDisabledIcon()`
Returns the disabled icon for the command button that represents this menu entry.
`JCommandButton.CommandButtonKind`
`getEntryKind()`
Returns the kind of the command button that represents this menu entry.
`ResizableIcon`
`getIcon()`
Returns the icon of this application menu entry.
`ActionListener`
`getMainActionListener()`
Returns the main action listener associated with this application menu entry.
`String`
`getPopupKeyTip()`
Returns the key tip for the popup area of the command button that represents this menu entry.
`RichTooltip`
`getPopupRichTooltip()`
Returns the rich tooltip for the popup area of the command button that represents this menu entry.
`RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback`
`getRolloverCallback()`
Returns the current application callback that allows placing custom content in the secondary panel of the `RibbonApplicationMenu` when this primary menu entry is activated.
`int`
`getSecondaryGroupCount()`
Returns the number of secondary menu groups of this primary menu entry.
`List<RibbonApplicationMenuEntrySecondary>`
`getSecondaryGroupEntries(int groupIndex)`
Returns an unmodifiable list of menu entries of the secondary menu group at the specified index.
`String`
`getSecondaryGroupTitleAt(int groupIndex)`
Returns the title of the secondary menu group at the specified index.
`String`
`getText()`
Returns the text of this application menu entry.
`boolean`
`isEnabled()`
Returns the enabled state of the command button that represents this menu entry.
`void`
`setActionKeyTip(String actionKeyTip)`
Sets the new value for the key tip for the action area of the command button that represents this menu entry.
`void`
`setActionRichTooltip(RichTooltip actionRichTooltip)`
Sets the rich tooltip for the action area of the command button that represents this menu entry.
`void`
`setDisabledIcon(ResizableIcon disabledIcon)`
Sets the disabled icon for the command button that represents this menu entry.
`void`
`setEnabled(boolean isEnabled)`
Sets the enabled state of the command button that represents this menu entry.
`void`
`setPopupKeyTip(String popupKeyTip)`
Sets the new value for the key tip for the popup area of the command button that represents this menu entry.
`void`
`setPopupRichTooltip(RichTooltip popupRichTooltip)`
Sets the rich tooltip for the popup area of the command button that represents this menu entry.
`void`
`setRolloverCallback(RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback rolloverCallback)`
Sets the rollover callback that allows the application to place custom content in the secondary panel of the `RibbonApplicationMenu` when this primary menu entry is activated.
`void`
`setSecondaryGroupTitle(int groupIndex, String newTitle)`
Changes the title of the specified group.
`void`
`setText(String text)`
Sets the new text for this application menu entry.

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

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

## Field Details

### rolloverCallback

protected RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback rolloverCallback
An optional rollover callback. It allows the application to place custom content in the secondary panel of the `RibbonApplicationMenu` when this primary menu entry is activated.

See Also:
  - `setRolloverCallback(PrimaryRolloverCallback)`
  - `getRolloverCallback()`

### groupTitles

protected List<String> groupTitles
List of titles for all menu groups.

### groupEntries

protected List<List<RibbonApplicationMenuEntrySecondary>> groupEntries
List of all menu groups.

### icon

protected ResizableIcon icon
The menu icon.

### disabledIcon

protected ResizableIcon disabledIcon
The menu icon for disabled state. Optional, can be `null`.

### text

protected String text
The menu text.

### mainActionListener

protected ActionListener mainActionListener
The main action listener for this menu entry.

### entryKind

protected JCommandButton.CommandButtonKind entryKind
The kind of the command button that represents this menu entry.

### isEnabled

protected boolean isEnabled
Enabled state of this menu.

### actionKeyTip

protected String actionKeyTip
Optional key tip for the action area of the command button that represents this menu entry.

### popupKeyTip

protected String popupKeyTip
Optional key tip for the popup area of the command button that represents this menu entry.

### actionRichTooltip

protected RichTooltip actionRichTooltip
Optional tooltip for the action area of the command button that represents this menu entry.

### popupRichTooltip

protected RichTooltip popupRichTooltip
Optional tooltip for the popup area of the command button that represents this menu entry.

## Constructor Details

### RibbonApplicationMenuEntryPrimary

public RibbonApplicationMenuEntryPrimary(ResizableIcon icon, String text, ActionListener mainActionListener, JCommandButton.CommandButtonKind entryKind)
Creates the metadata description of a `RibbonApplicationMenu` primary menu entry.

Parameters:
  `icon` - The icon of this menu entry. Must be non-`null`.
  `text` - The text of this menu entry. Must be non-`null`.
  `mainActionListener` - The main action listener for this menu entry. If the entry kind is `JCommandButton.CommandButtonKind.POPUP_ONLY`, this listener will be ignored.
  `entryKind` - The kind of the command button that will represent this menu entry. Must be non- `null`.

## Method Details

### addSecondaryMenuGroup

public int addSecondaryMenuGroup(String groupTitle, RibbonApplicationMenuEntrySecondary... entries)
Adds a titled group of secondary menu entries.

Parameters:
  `groupTitle` - The title of the group.
  `entries` - The secondary menu entries belonging to this group.
Returns:
  The index of the newly added menu group.
See Also:
  - `getSecondaryGroupCount()`
  - `getSecondaryGroupTitleAt(int)`
  - `getSecondaryGroupEntries(int)`

### getSecondaryGroupCount

public int getSecondaryGroupCount()
Returns the number of secondary menu groups of this primary menu entry.

Returns:
  The number of secondary menu groups of this primary menu entry.
See Also:
  - `addSecondaryMenuGroup(String, RibbonApplicationMenuEntrySecondary...)`
  - `getSecondaryGroupTitleAt(int)`
  - `getSecondaryGroupEntries(int)`

### getSecondaryGroupTitleAt

public String getSecondaryGroupTitleAt(int groupIndex)
Returns the title of the secondary menu group at the specified index.

Parameters:
  `groupIndex` - The index of a secondary menu group.
Returns:
  The title of the secondary menu group at the specified index.
See Also:
  - `addSecondaryMenuGroup(String, RibbonApplicationMenuEntrySecondary...)`
  - `getSecondaryGroupCount()`
  - `getSecondaryGroupEntries(int)`

### getSecondaryGroupEntries

public List<RibbonApplicationMenuEntrySecondary> getSecondaryGroupEntries(int groupIndex)
Returns an unmodifiable list of menu entries of the secondary menu group at the specified index.

Parameters:
  `groupIndex` - The index of a secondary menu group.
Returns:
  An unmodifiable list of menu entries of the secondary menu group at the specified index.
See Also:
  - `addSecondaryMenuGroup(String, RibbonApplicationMenuEntrySecondary...)`
  - `getSecondaryGroupCount()`
  - `getSecondaryGroupTitleAt(int)`

### setRolloverCallback

public void setRolloverCallback(RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback rolloverCallback)
Sets the rollover callback that allows the application to place custom content in the secondary panel of the `RibbonApplicationMenu` when this primary menu entry is activated.

Parameters:
  `rolloverCallback` - The new rollover callback for populating the secondary panel of the `RibbonApplicationMenu`.
See Also:
  - `getRolloverCallback()`

### getRolloverCallback

public RibbonApplicationMenuEntryPrimary.PrimaryRolloverCallback getRolloverCallback()
Returns the current application callback that allows placing custom content in the secondary panel of the `RibbonApplicationMenu` when this primary menu entry is activated.

Returns:
  The current rollover callback for populating the secondary panel of the `RibbonApplicationMenu`.
See Also:
  - `setRolloverCallback(PrimaryRolloverCallback)`

### setSecondaryGroupTitle

public void setSecondaryGroupTitle(int groupIndex, String newTitle)
Changes the title of the specified group.

Parameters:
  `groupIndex` - Group index.
  `newTitle` - New title for the specified group.

### getIcon

public ResizableIcon getIcon()
Returns the icon of this application menu entry.

Returns:
  The icon of this application menu entry.

### getText

public String getText()
Returns the text of this application menu entry.

Returns:
  The text of this application menu entry.
See Also:
  - `setText(String)`

### setText

public void setText(String text)
Sets the new text for this application menu entry.

Parameters:
  `text` - The new text for this application menu entry.
See Also:
  - `getText()`

### getMainActionListener

public ActionListener getMainActionListener()
Returns the main action listener associated with this application menu entry.

Returns:
  The main action listener associated with this application menu entry.

### getEntryKind

public JCommandButton.CommandButtonKind getEntryKind()
Returns the kind of the command button that represents this menu entry.

Returns:
  The kind of the command button that represents this menu entry.

### setEnabled

public void setEnabled(boolean isEnabled)
Sets the enabled state of the command button that represents this menu entry.

Parameters:
  `isEnabled` - If `true`, the command button that represents this menu entry will be enabled, if `false`, the command button will be disabled.
See Also:
  - `isEnabled`

### isEnabled

public boolean isEnabled()
Returns the enabled state of the command button that represents this menu entry.

Returns:
  `true` if the command button that represents this menu entry is enabled, `false` otherwise.

### getActionKeyTip

public String getActionKeyTip()
Returns the key tip for the action area of the command button that represents this menu entry.

Returns:
  The key tip for the action area of the command button that represents this menu entry.
See Also:
  - `setActionKeyTip(String)`
  - `getPopupKeyTip()`

### setActionKeyTip

public void setActionKeyTip(String actionKeyTip)
Sets the new value for the key tip for the action area of the command button that represents this menu entry.

Parameters:
  `actionKeyTip` - The new value for the key tip for the action area of the command button that represents this menu entry.
See Also:
  - `getActionKeyTip()`
  - `setPopupKeyTip(String)`

### getPopupKeyTip

public String getPopupKeyTip()
Returns the key tip for the popup area of the command button that represents this menu entry.

Returns:
  The key tip for the popup area of the command button that represents this menu entry.
See Also:
  - `setPopupKeyTip(String)`
  - `getActionKeyTip()`

### setPopupKeyTip

public void setPopupKeyTip(String popupKeyTip)
Sets the new value for the key tip for the popup area of the command button that represents this menu entry.

Parameters:
  `popupKeyTip` - The new value for the key tip for the popup area of the command button that represents this menu entry.
See Also:
  - `getPopupKeyTip()`
  - `setActionKeyTip(String)`

### getActionRichTooltip

public RichTooltip getActionRichTooltip()
Returns the rich tooltip for the action area of the command button that represents this menu entry.

Returns:
  The rich tooltip for the action area of the command button that represents this menu entry.
See Also:
  - invalid reference

        #setPopupTooltip(RichTooltip)

  - `getActionRichTooltip()`

### setActionRichTooltip

public void setActionRichTooltip(RichTooltip actionRichTooltip)
Sets the rich tooltip for the action area of the command button that represents this menu entry.

Parameters:
  `actionRichTooltip` - The rich tooltip for the action area of the command button that represents this menu entry.
See Also:
  - `getActionRichTooltip()`
  - invalid reference

        #setActionTooltip(RichTooltip)

### getPopupRichTooltip

public RichTooltip getPopupRichTooltip()
Returns the rich tooltip for the popup area of the command button that represents this menu entry.

Returns:
  The rich tooltip for the popup area of the command button that represents this menu entry.
See Also:
  - invalid reference

        #setPopupTooltip(RichTooltip)

  - `getActionRichTooltip()`

### setPopupRichTooltip

public void setPopupRichTooltip(RichTooltip popupRichTooltip)
Sets the rich tooltip for the popup area of the command button that represents this menu entry.

Parameters:
  `popupRichTooltip` - The rich tooltip for the popup area of the command button that represents this menu entry.
See Also:
  - `getPopupRichTooltip()`
  - invalid reference

        #setActionTooltip(RichTooltip)

### getDisabledIcon

public ResizableIcon getDisabledIcon()
Returns the disabled icon for the command button that represents this menu entry.

Returns:
  The disabled icon for the command button that represents this menu entry.
See Also:
  - `setDisabledIcon(ResizableIcon)`

### setDisabledIcon

public void setDisabledIcon(ResizableIcon disabledIcon)
Sets the disabled icon for the command button that represents this menu entry.

Parameters:
  `disabledIcon` - The disabled icon for the command button that represents this menu entry.
See Also:
  - `getDisabledIcon()`