Package ca.corbett.extras.actionpanel

Class ActionPanel

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
ca.corbett.extras.actionpanel.ActionPanel
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class ActionPanel extends JPanel
A custom panel that can show groups of related actions, either as clickable JLabels or as JButtons. The styling of the panel and each action group is highly customizable. By default, the current Look and Feel defaults are applied, but you can modify fonts, colors, borders, and spacing to fit your application's design.

Adding actions - actions are grouped into action groups. Each action group will contain a header with the group name and a control button for expanding/collapsing the group. You can add actions one-by-one, or via addAll():

  • add(String groupName, EnhancedAction action) - adds a single action to the specified group.
  • addAll(String groupName, List<EnhancedAction> actions) - adds multiple actions to the specified group.

The same action can be added to more than one group if desired. If the named group does not yet exist, it will be created.

Group names are case-insensitive; adding an action to group "File" is the same as adding it to group "file" or "FILE". Group headers will be displayed using the name as first specified when adding an action. Groups can be renamed using setGroupName(String oldName, String newName), which does allow you to change the case of a group.

Customizing action groups - you can associate an icon with an action group, and you can optionally specify a Comparator to control how actions within each group are sorted. By default, action groups have no icons, and actions are listed in the order in which they were added. To customize this:

  • setGroupIcon(String groupName, Icon icon) - sets the icon for the specified group.
  • setGroupComparator(Comparator<String>>) - determines the order of action groups within the ActionPanel. By default, groups are presented in the order they were added.
  • setActionComparator(Comparator<EnhancedAction> comparator) - sets the comparator for sorting actions within groups.

Styling options - methods are provided to customize fonts, colors, borders, and spacing for the ActionPanel as a whole, as well as for individual action groups. By default, the current Look and Feel defaults are applied. You can modify:

  • Labels vs Buttons - use setUseLabels() or setUseButtons() to choose whether actions are presented as clickable JLabels or as JButtons. Default is JLabels.
  • Fonts - use setActionFont() and setGroupHeaderFont() to set fonts for actions and group headers, respectively.
  • Icons - if your actions have icons, they will be displayed next to the action name by default. You can disable this by calling setShowActionIcons(false). Group headers can also have icons, which can be set using setGroupIcon(). You can disable group icons with setShowGroupIcons(false).
  • Colors - all colors are highly customizable. These options are found in the ColorOptions class, which you can access with getColorOptions(). Refer to ColorOptions class for more details.
  • Borders - all borders are highly customizable. These options are found in the BorderOptions class, which you can access with getBorderOptions().Refer to BorderOptions class for more details.
  • Spacing - you can control the spacing both within and around action groups: use setInternalPadding() to control the space between actions and the edges of the ActionPanel, and also between the actions themselves. Use setExternalPadding() to control the space between action groups, and the space between action groups and the edge of the ActionPanel.
  • Expand/collapse state - the user can expand or collapse action groups by clicking the button in the group header. All action groups are expanded initially by default. Options related to group expansion and collapse are found in the ExpandCollapseOptions class, which you can access with getExpandCollapseOptions(). Refer to the ExpandCollapseOptions class for more details on how to customize expand/collapse behavior and animation. You can listen for expand/collapse events with addExpandListener(ExpandListener listener).
  • Expand/collapse button icons - by default, ActionPanel supplies built-in icons for use with the expand/collapse button in each group header. These look like a + and - sign. You can supply your own icons by calling setExpandIcon(Icon icon) and setCollapseIcon(Icon icon) on the ActionPanel.
  • Icon sizes - by default, all icons (header icons, action icons, and the icons for the expand/collapse button) are rendered at 16x16 pixels. You can customize this size using setHeaderIconSize(int size) and setActionIconSize(int size). The size applies to both width and height. Icons will be scaled as needed.

Toolbars - call setToolBarEnabled(true) to show a toolbar with each action group. The toolbar is highly configurable! There are built-in actions that allow you to support adding new actions to a group, renaming a group, reordering or removing items in a group, or removing groups. You can also supply custom actions to be displayed in the toolbar. Refer to ToolBarOptions for details on how to customize the toolbar and the actions it contains. Access the ToolBarOptions with getToolBarOptions().

Listening for events - there are a few notifications that callers can subscribe to:

  • Expand/collapse events - listen for when the user expands or collapses an action group with addExpandListener(ExpandListener listener). The listener will be notified of which group was expanded or collapsed, and whether it was an expand or a collapse event.
  • Group rename events - listen for when a group is renamed with addGroupRenamedListener(GroupRenamedListener listener). The listener will be notified of the old and new group names. This listener is invoked both when the user renames a group via the toolbar (when group renaming is enabled) and when a group is renamed programmatically using methods such as setGroupName(String, String) or renameGroup(String, String).
  • Group removal events - listen for when a group is removed with addGroupRemovedListener(GroupRemovedListener listener). The listener will be notified of the name of the group that was removed. This listener is invoked both when the user removes a group via the toolbar (when group removal is enabled) and when a group is removed programmatically using methods such as removeGroup(String).
  • Group reorder events - listen for when a group is reordered with addGroupReorderedListener(GroupReorderedListener listener). The listener will be notified of the name of the group that was reordered. This listener is invoked both when the user reorders items via the toolbar (when reordering is enabled) and when the order is changed programmatically using methods such as reorderActions(String, int, int).

For a complete working example of ActionPanel with all customization options, refer to the demo application included with swing-extras! For more documentation and code examples, refer to the swing-extras book.

Since:
swing-extras 2.8
Author:
scorbo2
See Also:

  • Field Details

  • Constructor Details

    • ActionPanel

      public ActionPanel()

  • Method Details

    • dispose

      public void dispose()
      Performs internal cleanup to ensure that this ActionPanel will become eligible for garbage collection when no longer needed.

    • add

      public ActionPanel add(String groupName, EnhancedAction action)
      Adds a single action to the specified group. If the group does not exist, it will be created. You can pass null for the action if you just want to create an empty group.
      Parameters:
      groupName - The name of the group to add the action to.
      action - The action to add. Can be null to just create the group if it does not exist.
      Returns:
      This ActionPanel, for method chaining.

    • addAll

      public ActionPanel addAll(String groupName, List<EnhancedAction> actions)
      Adds multiple actions to the specified group. If the group does not exist, it will be created. The given list can be null or empty, in which case no actions are added to the group if it exists. But, an empty group will be created in that case if it does not already exist.
      Parameters:
      groupName - The name of the group to add the actions to.
      actions - The list of actions to add. Can be null or empty to just create the group if it does not exist.
      Returns:
      This ActionPanel, for method chaining.

    • add

      public ActionPanel add(String groupName, String actionName, String cardId)
      A convenience method for adding a CardAction to this ActionPanel. You must have already invoked setCardContainer() to set a companion CardLayout container! Otherwise, you will get an IllegalStateException.

      This method is shorthand for add(groupName, new CardAction(actionName, cardId));

      Note: Due to the design of CardLayout, we can't validate the given cardId. If it doesn't match the name of a card that was given to your layout, then nothing will happen when the action is triggered. It's up to calling code to make sure the cardId given here matches the name of a card in the card container.

      If the given actionName or the given cardId are null or blank, then the named group will be created if it does not exist, but no CardAction will be added to the group.

      Parameters:
      groupName - The name of the group to which the new action should belong.
      actionName - The text for the action. Can be null to just create the named group.
      cardId - The id of the card to show when the action is triggered. Can be null to just create the group.
      Returns:
      This ActionPanel, for method chaining.

    • getActionsForGroup

      public List<EnhancedAction> getActionsForGroup(String groupName)
      Returns all actions that belong to the specified group. If the named group does not exist, or does not contain any actions, then an empty list is returned. The actions are returned in the order determined by the action comparator for this ActionPanel, or in the order they were added if no comparator is set.
      Parameters:
      groupName - The name of the group whose actions should be returned. Case-insensitive.
      Returns:
      A list of all actions that belong to the specified group.

    • createEmptyGroup

      public ActionPanel createEmptyGroup(String groupName)
      Creates an empty group with the given group name. If the named group already exists, this method does nothing (existing group contents are unchanged).
      Parameters:
      groupName - The name of the group to create.
      Returns:
      This ActionPanel, for method chaining.

    • setCardContainer

      public ActionPanel setCardContainer(Container container)
      Sets an optional companion CardLayout Container for this ActionPanel. If set, you can add CardActions to this ActionPanel, or you can use the convenience methods that accept a cardId parameter. When a CardAction is triggered, the specified card will be shown in the CardLayout container. You can pass null to disassociate any existing container, but note that if you have any CardActions in this ActionPanel, you must remove them first, or you will get an IllegalStateException.
      Parameters:
      container - Any Container with a CardLayout, or null to disassociate an existing container.
      Returns:
      This ActionPanel, for method chaining.

    • getCardContainer

      public Container getCardContainer()
      Returns the companion CardLayout Container instance, if one is set.
      Returns:
      The CardLayout Container instance that is associated with this ActionPanel, or null if none is set.

    • isHighlightedAction

      public boolean isHighlightedAction(EnhancedAction action)
      Returns true if the given action is currently highlighted.
      Parameters:
      action - The action to check.
      Returns:
      True if the action is highlighted, false otherwise.

    • setHighlightedAction

      public ActionPanel setHighlightedAction(String cardId)
      If a companion CardLayout is linked, this will set the highlighted action to be the one that triggers the given cardId. If no such action is found, this does nothing. If no companion CardLayout is linked, you will receive an IllegalStateException.
      Parameters:
      cardId - The id of the card whose triggering action should be highlighted.
      Returns:
      This ActionPanel, for method chaining.

    • setHighlightedAction

      public ActionPanel setHighlightedAction(EnhancedAction action)
      Sets the specified action as the currently highlighted action. Only one action can be highlighted at a time. Pass null to clear any highlighted action.
      Parameters:
      action - The action to highlight, or null to clear the highlighted action.
      Returns:
      This ActionPanel, for method chaining.

    • isHighlightLastActionEnabled

      public boolean isHighlightLastActionEnabled()
      Reports whether the last action to be executed in this ActionPanel should be visually highlighted. The default is false.
      Returns:
      True if the last action is highlighted, false otherwise.

    • setHighlightLastActionEnabled

      public ActionPanel setHighlightLastActionEnabled(boolean highlightLastAction)
      Enables or disables highlighting of the last action to be executed in this ActionPanel. The default is false.
      Parameters:
      highlightLastAction - True to enable highlighting of the last action, false to disable it.
      Returns:
      This ActionPanel, for method chaining.

    • hasAction

      public boolean hasAction(EnhancedAction action)
      Returns true if any action group contains the specified action.
      Parameters:
      action - The action to check for.
      Returns:
      True if the action exists in any group, false otherwise.

    • hasAction

      public boolean hasAction(String groupName, EnhancedAction action)
      Returns true if the specified group contains the specified action. Group names are case-insensitive. If the named group does not exist in this action panel, false is returned (the group is not created).
      Parameters:
      groupName - The name of the group to check. Case-insensitive.
      action - The action to check for.
      Returns:
      True if the action exists in the specified group, false otherwise.

    • hasAction

      public boolean hasAction(String actionName, boolean caseSensitive)
      Returns true if the named action exists within any action group.
      Parameters:
      actionName - The name of the action to check for.
      caseSensitive - Whether the name comparison should be case-sensitive.
      Returns:
      True if the action exists in any group, false otherwise.

    • hasAction

      public boolean hasAction(String groupName, String actionName, boolean actionNameCaseSensitive)
      Returns true if the specified group contains an action with the specified name. Group names are case-insensitive. If the named group does not exist in this action panel, false is returned (the group is not created).
      Parameters:
      groupName - The name of the group to check. Case-insensitive.
      actionName - The name of the action to check for.
      actionNameCaseSensitive - Whether the action name comparison should be case-sensitive.
      Returns:
      True if the action exists in the specified group, false otherwise.

    • removeAction

      public ActionPanel removeAction(EnhancedAction action)
      Removes all instances of the specified action from all action groups.
      Parameters:
      action - The action to remove.
      Returns:
      This ActionPanel, for method chaining.

    • removeAction

      public ActionPanel removeAction(String groupName, EnhancedAction action)
      Removes the specified action from the named action group. If the named group does not exist, no action is taken.
      Parameters:
      groupName - The name of the group to remove the action from.
      action - The action to remove.
      Returns:
      This ActionPanel, for method chaining.

    • removeAction

      public ActionPanel removeAction(String actionName, boolean caseSensitive)
      Removes all instances of the named action from all action groups.
      Parameters:
      actionName - The name of the action to remove.
      caseSensitive - Whether the name comparison should be case-sensitive.
      Returns:
      This ActionPanel, for method chaining.

    • removeAction

      public ActionPanel removeAction(String groupName, String actionName, boolean actionNameCaseSensitive)
      Removes all instances of the named action from the named action group. If the named group does not exist, no action is taken. Group names are case-insensitive, but you can decide whether the action name comparison should be case-sensitive.
      Parameters:
      groupName - The name of the group to remove the action from. Case-insensitive.
      actionName - The name of the action to remove.
      actionNameCaseSensitive - Whether the name comparison should be case-sensitive.
      Returns:
      This ActionPanel, for method chaining.

    • clear

      public ActionPanel clear(boolean pruneEmptyGroups)
      Removes all actions from all groups, and then optionally also removes all action groups that are empty.

    • getActionCount

      public int getActionCount()
      Returns a total count of all actions in all action groups.
      Returns:
      The total number of actions in this ActionPanel.

    • getActionCount

      public int getActionCount(String groupName)
      Returns the count of actions in the named group. Group names are case-insensitive.
      Parameters:
      groupName - The name of the group.
      Returns:
      The number of actions in the specified group, or 0 if the group does not exist.

    • getGroupCount

      public int getGroupCount()
      Returns the number of action groups in this ActionPanel.
      Returns:
      The number of action groups.

    • hasGroup

      public boolean hasGroup(String groupName)
      Reports whether a group with the given name exists in this ActionPanel. Group names are case-insensitive.
      Parameters:
      groupName - The name of the group to check.
      Returns:
      True if the group exists, false otherwise.

    • removeGroup

      public ActionPanel removeGroup(String groupName)
      Removes the specified action group entirely, along with all its actions. If the named group does not exist, no action is taken. Group names are case-insensitive.
      Parameters:
      groupName - The name of the group to remove.
      Returns:
      This ActionPanel, for method chaining.

    • renameGroup

      public boolean renameGroup(String oldName, String newName)
      Attempts to rename the given group to the new name. This may fail, if the old name does not reference any existing group. It may also fail if the given new name is already in use by another group. Group names are case-insensitive.
      Parameters:
      oldName - The current name of the group to rename. Case-insensitive.
      newName - The new name for the group. Case-insensitive. Cannot be null or empty.
      Returns:
      True if the rename was successful, false otherwise (e.g. if oldName does not exist, or newName is already in use).

    • getGroupNames

      public List<String> getGroupNames()
      Returns a list of all group names in this ActionPanel. The returned list will be sorted if we have a group comparator.
      Returns:
      A list of all group names in this ActionPanel. May be empty.

    • setGroupIcon

      public ActionPanel setGroupIcon(String groupName, Icon icon)
      Sets the icon for the specified group. If the named group does not exist, it is created.
      Parameters:
      groupName - The name of the group.
      icon - The icon to set.
      Returns:
      This ActionPanel, for method chaining.

    • setActionComparator

      public ActionPanel setActionComparator(Comparator<EnhancedAction> comparator)
      Sets the comparator for sorting actions within action groups. By default, actions will be sorted in the order in which they were added to the group. You can pass null as the comparator to revert to the default behavior.
      Parameters:
      comparator - The comparator to use for sorting actions, or null for default order.
      Returns:
      This ActionPanel, for method chaining.

    • getActionComparator

      public Comparator<EnhancedAction> getActionComparator()
      Returns the Comparator that is used to auto-sort the list of actions within each action group. If null, actions are presented in the order in which they were added to the group.
      Returns:
      The Comparator used for sorting actions, or null if actions are presented in add order.

    • setGroupComparator

      public ActionPanel setGroupComparator(Comparator<String> comparator)
      Sets the comparator for ordering action groups within the ActionPanel. By default, groups will be presented in the order in which they were added. You can pass null as the comparator to revert to the default behavior.
      Parameters:
      comparator - The comparator to use for sorting groups, or null for default order.
      Returns:
      This ActionPanel, for method chaining.

    • setUseLabels

      public ActionPanel setUseLabels()
      Sets whether actions should be rendered as JLabels (clickable labels). Shorthand for setActionComponentType(ActionComponentType.LABELS).
      Returns:
      This ActionPanel, for method chaining.

    • setUseButtons

      public ActionPanel setUseButtons()
      Sets whether actions should be rendered as JButtons. Shorthand for setActionComponentType(ActionComponentType.BUTTONS).
      Returns:
      This ActionPanel, for method chaining.

    • setActionComponentType

      public ActionPanel setActionComponentType(ActionComponentType type)
      Sets the component type that will be used to represent actions. You can use setUseButtons() or setUseLabels() as shorthand methods.
      Parameters:
      type - The ActionComponentType to use.
      Returns:
      This ActionPanel, for method chaining.

    • getActionComponentType

      public ActionComponentType getActionComponentType()
      Reports the component type that is used to represent actions.
      Returns:
      The ActionComponentType in use.

    • setActionFont

      public ActionPanel setActionFont(Font font)
      Sets the font for action items. This overrides the Look and Feel default font. You can pass null to revert to the L&F default.
      Parameters:
      font - The font to use for actions, or null to use the L&F default.
      Returns:
      This ActionPanel, for method chaining.

    • getActionFont

      public Font getActionFont()
      Returns the font for action items. May be null if Look and Feel defaults are in use.
      Returns:
      The action font, or null if L&F default is in use.

    • setGroupHeaderFont

      public ActionPanel setGroupHeaderFont(Font font)
      Sets the font for group headers. This overrides the Look and Feel default font. You can pass null to revert to the L&F default.
      Parameters:
      font - The font to use for group headers, or null to use the L&F default.
      Returns:
      This ActionPanel, for method chaining.

    • getGroupHeaderFont

      public Font getGroupHeaderFont()
      Returns the font for group headers. May be null if Look and Feel defaults are in use.
      Returns:
      The group header font, or null if L&F default is in use.

    • getColorOptions

      public ColorOptions getColorOptions()
      Options related to custom colors are accessed via the ColorOptions class. Developer note: yeah, they could all live here in this class, but this class is already unreasonably large, and there are many options related to color customization, so they were all moved over there. The only first-class color-related methods still in ActionPanel are setBackground() and getBackground(), which are overridden for internal reasons. All other color options are accessed via the ColorOptions instance returned by this method.
      Returns:
      The ColorOptions instance containing options related to color customization.

    • getExpandCollapseOptions

      public ExpandCollapseOptions getExpandCollapseOptions()
      Options related to group expansion/collapse are accessed via the ExpandCollapseOptions class. Developer note: yeah, they could all live here in this class, but this class is already unreasonably large, and there are many options related to expansion and collapse, so they were all moved over there.
      Returns:
      The ExpandCollapseOptions instance containing options related to expansion and collapse.

    • getBorderOptions

      public BorderOptions getBorderOptions()
      Options related to borders are accessed via the BorderOptions class. Developer note: yeah, they could all live here in this class, but this class is already unreasonably large, and there are many options related to borders, so they were all moved over there.
      Returns:
      The BorderOptions instance containing options related to border customization.

    • setBackground

      public void setBackground(Color bg)
      We have to override this because we use a wrapper panel internally to manage our BoxLayout, so we need to store the background color and apply it to the wrapper panel during rebuild(). This is not at all obvious to callers, who may reasonably expect to be able to do actionPanel.setBackground(). So, we intercept it and do the right thing behind the scenes. All of our other color options are stored in our ColorOptions instance.

      Setting null here will revert to the Look and Feel default background color.

      Overrides:
      setBackground in class JComponent
      Parameters:
      bg - the desired background Color

    • getBackground

      public Color getBackground()
      We override to return our own stored background color. If null was passed to setBackground(), this will return the Look and Feel default Panel background color.
      Overrides:
      getBackground in class Component
      Returns:
      the background Color of the ActionPanel itself.

    • getHeaderMargins

      public Margins getHeaderMargins()
      Returns the Margins instance for the header area of action groups. This controls the space between the header components (e.g. icon, label, expand/collapse button) and the edges of the header. The internalSpacing property controls the space between the header components themselves.

      Note: changing any of the properties of the returned Margins instance will trigger an immediate rebuild of the ActionPanel. If you have multiple changes you wish to make, it may make sense to disable auto-rebuild until after your changes are complete, to avoid unnecessary intermediate rebuilds. For example: 

           actionPanel.setAutoRebuild(false);
     try {
         Margins margins = actionPanel.getHeaderMargins();
         margins.setTop(10);
         margins.setBottom(10);
         margins.setLeft(5);
         margins.setRight(5);
     }
     finally {
         // Re-enabling auto-rebuild will trigger
         // an immediate rebuild:
         actionPanel.setAutoRebuild(true);
     }
      Returns:
      The Margins instance for the header area of action groups.

    • getActionTrayMargins

      public Margins getActionTrayMargins()
      Returns the Margins instance for the action tray area of action groups. This controls the space between the action components (e.g. buttons/labels) and the edges of the action tray. The internalSpacing property controls the space between the action components themselves.

      Note: changing any of the properties of the returned Margins instance will trigger an immediate rebuild of the ActionPanel. If you have multiple changes you wish to make, it may make sense to disable auto-rebuild until after your changes are complete, to avoid unnecessary intermediate rebuilds. For example: 

           actionPanel.setAutoRebuild(false);
     try {
         Margins margins = actionPanel.getActionTrayMargins();
         margins.setTop(10);
         margins.setBottom(10);
         margins.setLeft(5);
         margins.setRight(5);
     }
     finally {
         // Re-enabling auto-rebuild will trigger
         // an immediate rebuild:
         actionPanel.setAutoRebuild(true);
     }
      Returns:
      The Margins instance for the action tray area of action groups.

    • getToolBarMargins

      public Margins getToolBarMargins()
      Returns the Margins instance for the ToolBar. This controls the space between the ToolBar buttons and the edges of the ToolBar area. If the ToolBar is not in Stretch mode, then the internalSpacing property controls the space between the ToolBar buttons themselves. If the ToolBar is in Stretch mode, then there is no space between the buttons, regardless of the internalSpacing setting, because the buttons are stretched to fill all available space.

      Note: changing any of the properties of the returned Margins instance will trigger an immediate rebuild of the ActionPanel. If you have multiple changes you wish to make, it may make sense to disable auto-rebuild until after your changes are complete, to avoid unnecessary intermediate rebuilds. For example: 

           actionPanel.setAutoRebuild(false);
     try {
         Margins margins = actionPanel.getToolBarMargins();
         margins.setTop(10);
         margins.setBottom(10);
         margins.setLeft(5);
         margins.setRight(5);
     }
     finally {
         // Re-enabling auto-rebuild will trigger
         // an immediate rebuild:
         actionPanel.setAutoRebuild(true);
     }
      Returns:
      The Margins instance for the ToolBar.

    • getActionGroupMargins

      public Margins getActionGroupMargins()
      Returns the Margins instance for action groups. This controls the space between action groups and the edges of the ActionPanel. The internalSpacing property controls the gap between action groups themselves.

      Note: changing any of the properties of the returned Margins instance will trigger an immediate rebuild of the ActionPanel. If you have multiple changes you wish to make, it may make sense to disable auto-rebuild until after your changes are complete, to avoid unnecessary intermediate rebuilds. For example: 

           actionPanel.setAutoRebuild(false);
     try {
         Margins margins = actionPanel.getActionGroupMargins();
         margins.setTop(10);
         margins.setBottom(10);
         margins.setLeft(5);
         margins.setRight(5);
     }
     finally {
         // Re-enabling auto-rebuild will trigger
         // an immediate rebuild:
         actionPanel.setAutoRebuild(true);
     }
      Returns:
      The Margins instance for action groups.

    • getActionIconTextGap

      public int getActionIconTextGap()
      Returns the gap between the action icon and the action text. This is only relevant if showActionIcons is true and actions have icons. Note we don't use the action tray's internalSpacing for this, because it's nice to be able to control this text gap separately from the gap between the action components themselves.
      Returns:
      The gap in pixels between the action icon and the action text.

    • setActionIconTextGap

      public ActionPanel setActionIconTextGap(int gap)
      Sets the gap between action icons and their text labels. This is only relevant if showActionIcons is true and actions have icons. Note we don't use the action tray's internalSpacing for this, because it's nice to be able to control this text gap separately from the gap between the action components themselves.
      Parameters:
      gap - The gap in pixels between the action icon and the action text. Must be 0 or greater.
      Returns:
      This ActionPanel, for method chaining.

    • setButtonPadding

      public ActionPanel setButtonPadding(int padding)
      Sets optional padding to add between button text/icons and the edges of the button. This applies to actions, when rendered as buttons, and also applies to toolbar buttons, if the toolbar is enabled. The default value is 2.
      Parameters:
      padding - A pixel value to apply between button text/icons and the edges of the button. Must be 0 or greater.
      Returns:
      This ActionPanel, for method chaining.

    • getButtonPadding

      public int getButtonPadding()
      Returns padding to add between button text/icons and the edges of the button. This applies to actions, when rendered as buttons, and also applies to toolbar buttons, if the toolbar is enabled. The default value is 2.
      Returns:
      The pixel value of the padding between button text/icons and the edges of the button.

    • setHeaderIconSize

      public ActionPanel setHeaderIconSize(int size)
      Sets the size (width and height) at which header icons are rendered. The default is 16 pixels. Icons will be scaled as needed.
      Parameters:
      size - The icon size in pixels. Must be greater than 0.
      Returns:
      This ActionPanel, for method chaining.

    • getHeaderIconSize

      public int getHeaderIconSize()
      Returns the size (width and height) at which header icons are rendered.
      Returns:
      The header icon size in pixels.

    • setActionIconSize

      public ActionPanel setActionIconSize(int size)
      Sets the size (width and height) at which action icons are rendered. The default is 16 pixels. Icons will be scaled as needed.
      Parameters:
      size - The icon size in pixels. Must be greater than 0.
      Returns:
      This ActionPanel, for method chaining.

    • getActionIconSize

      public int getActionIconSize()
      Returns the size (width and height) at which action icons are rendered.
      Returns:
      The action icon size in pixels.

    • setExpandIcon

      public ActionPanel setExpandIcon(ImageIcon icon)
      Sets the icon to use for the expand button in action group headers.
      Parameters:
      icon - The expand icon. Cannot be null.
      Returns:
      This ActionPanel, for method chaining.

    • getExpandIcon

      public ImageIcon getExpandIcon()
      Returns the icon used for the expand button in action group headers.
      Returns:
      The expand icon.

    • setCollapseIcon

      public ActionPanel setCollapseIcon(ImageIcon icon)
      Sets the icon to use for the collapse button in action group headers.
      Parameters:
      icon - The collapse icon. Cannot be null.
      Returns:
      This ActionPanel, for method chaining.

    • getCollapseIcon

      public ImageIcon getCollapseIcon()
      Returns the icon used for the collapse button in action group headers.
      Returns:
      The collapse icon.

    • isShowActionIcons

      public boolean isShowActionIcons()
      Reports whether action icons are shown next to action names. By default, if an action has an icon set, it will be shown next to the action name. You can disable this by calling setShowActionIcons(false).

    • setShowActionIcons

      public ActionPanel setShowActionIcons(boolean showActionIcons)
      Controls whether action icons are shown next to action names. By default, if an action has an icon set, it will be shown next to the action name. You can disable this by calling setShowActionIcons(false).

    • isShowGroupIcons

      public boolean isShowGroupIcons()
      Reports whether group icons are shown next to group names. By default, if a group has an icon set, it will be shown next to the group name. You can disable this by calling setShowGroupIcons(false).

    • setShowGroupIcons

      public ActionPanel setShowGroupIcons(boolean showGroupIcons)
      Controls whether group icons are shown next to group names. By default, if a group has an icon set, it will be shown next to the group name. You can disable this by calling setShowGroupIcons(false).

    • isExpanded

      public boolean isExpanded(String groupName)
      Reports whether the named group is currently expanded. If the named group does not exist, returns false. Group names are case-insensitive.
      Parameters:
      groupName - The name of the action group.
      Returns:
      True if the group is expanded, false if it is collapsed.

    • setExpanded

      public ActionPanel setExpanded(String groupName, boolean expanded)
      Sets whether the named group is expanded or collapsed. If the named group does not exist, does nothing. Group names are case-insensitive.
      Parameters:
      groupName - The name of the action group.
      expanded - True to expand the group, false to collapse it.
      Returns:
      This ActionPanel, for method chaining.

    • toggleExpanded

      public ActionPanel toggleExpanded(String groupName)
      Toggles the expanded/collapsed state of the named group. If the named group does not exist, does nothing. Group names are case-insensitive.
      Parameters:
      groupName - The name of the action group.
      Returns:
      This ActionPanel, for method chaining.

    • isToolBarEnabled

      public boolean isToolBarEnabled()
      Reports whether the ToolBar is enabled. When enabled, the ToolBar is shown at the bottom of each ActionGroup. It contains buttons related to the actions in that group. To configure the ToolBar, use the ToolBarOptions object accessible via getToolBarOptions().
      Returns:
      True if the ToolBar is enabled, false otherwise.

    • setToolBarEnabled

      public ActionPanel setToolBarEnabled(boolean enabled)
      Enables or disables the ToolBar, which is shown at the bottom of each ActionGroup and contains buttons related to the actions in that group. To configure the ToolBar, use the ToolBarOptions object accessible via getToolBarOptions().
      Parameters:
      enabled - True to enable the ToolBar, false to disable it.
      Returns:
      This ActionPanel, for method chaining.

    • getToolBarOptions

      public ToolBarOptions getToolBarOptions()
      Options related to the ToolBar are accessed via the ToolBarOptions class. Developer note: yeah, they could all live here in this class, but this class is already unreasonably large, and the ToolBar has a somewhat complicated setup, so they were all moved over there. The only first-class ToolBar option still in ActionPanel is isToolBarEnabled(), which is the master switch that controls whether the ToolBar is shown at all.
      Returns:
      The ToolBarOptions instance containing options related to the ToolBar.

    • setAutoRebuildEnabled

      public ActionPanel setAutoRebuildEnabled(boolean enabled)
      Normally, ActionPanel will automatically rebuild itself whenever any option is modified. If you have multiple successive changes to make, and want to spare the thrashing of multiple rebuilds, you can disable auto-rebuild, make your changes, then re-enable auto-rebuild. Invoking setAutoRebuildEnabled(true) will immediately trigger a rebuild if auto-rebuild was previously disabled.
      Parameters:
      enabled - True to enable auto-rebuild, false to disable it.
      Returns:
      This ActionPanel, for method chaining.

    • isAutoRebuildEnabled

      public boolean isAutoRebuildEnabled()
      Reports whether auto-rebuild is enabled. When enabled, ActionPanel will automatically rebuild itself whenever any option is modified. When disabled, ActionPanel will not rebuild itself until setAutoRebuildEnabled(true) is invoked.
      Returns:
      True if auto-rebuild is enabled, false otherwise.

    • addExpandListener

      public ActionPanel addExpandListener(ExpandListener listener)
      You can listen for group expand/collapse events by adding an ExpandListener.

    • removeExpandListener

      public ActionPanel removeExpandListener(ExpandListener listener)
      You can stop listening for group expand/collapse events by removing an ExpandListener.

    • addGroupRenamedListener

      public ActionPanel addGroupRenamedListener(GroupRenamedListener listener)
      Subscribe to receive notification whenever a group is renamed within this ActionPanel.
      Parameters:
      listener - A GroupRenamedListener to be notified whenever a group is renamed within this ActionPanel.
      Returns:
      This ActionPanel, for method chaining.

    • removeGroupRenamedListener

      public ActionPanel removeGroupRenamedListener(GroupRenamedListener listener)
      Stop listening for notification whenever a group is renamed within this ActionPanel.
      Parameters:
      listener - A GroupRenamedListener that was previously registered to receive notification of group renames.
      Returns:
      This ActionPanel, for method chaining.

    • addGroupRemovedListener

      public ActionPanel addGroupRemovedListener(GroupRemovedListener listener)
      Subscribe to receive notification whenever a group is removed from this ActionPanel.
      Parameters:
      listener - A GroupRemovedListener to be notified whenever a group is removed from this ActionPanel.
      Returns:
      This ActionPanel, for method chaining.

    • removeGroupRemovedListener

      public ActionPanel removeGroupRemovedListener(GroupRemovedListener listener)
      Stop listening for notification whenever a group is removed from this ActionPanel.
      Parameters:
      listener - A GroupRemovedListener that was previously registered to receive notification of group removals.
      Returns:
      This ActionPanel, for method chaining.

    • addGroupReorderedListener

      public ActionPanel addGroupReorderedListener(GroupReorderedListener listener)
      Subscribe to receive notification whenever the items within a group are reordered. This happens from the built-in group edit dialog, where the user can drag-and-drop to manually reorder items, or use the sort options on the dialog. Callers will NOT receive notifications when action groups are sorted by a provided Comparator. This subscription event is only for manual user-driven reordering.

      Note that at any time, you can invoke getActionsForGroup() to get the ordered list of actions for a given group. So, if you have a Comparator set, you have an easy way of discovering the auto-sorted order.

      Parameters:
      listener - A GroupReorderedListener to be notified whenever the items within a group are reordered.
      Returns:
      This ActionPanel, for method chaining.

    • removeGroupReorderedListener

      public ActionPanel removeGroupReorderedListener(GroupReorderedListener listener)
      Stop listening for notification whenever a group is reordered within this ActionPanel.
      Parameters:
      listener - A GroupReorderedListener that was previously registered to receive notification of group reordering.
      Returns:
      This ActionPanel, for method chaining.