Package ca.corbett.extras.actionpanel

Class ToolBarOptions

java.lang.Object
ca.corbett.extras.actionpanel.ActionPanelOptions
ca.corbett.extras.actionpanel.ToolBarOptions
public final class ToolBarOptions extends ActionPanelOptions
This class only exists to relieve some clutter from the ActionPanel class, which is getting quite large. The idea is that you can use actionPanel.getToolBarOptions() to get an instance of this class, and then use the methods in this class to set options for the toolbar, rather than having all these options in the ActionPanel class itself. Note that toolbar enabled/disabled is still a first-class property in ActionPanel itself, as that's fairly fundamental. All other toolbar-related options are here.

Button positioning - use setButtonPosition() to control how the buttons are aligned within their container panel. The default is Stretch, which stretches the buttons evenly across the entire width of the container panel. If you choose any other option, then the buttons will be aligned FlowLayout-style, and you can control the spacing between them via ActionPanel's setInternalPadding() method. In Stretch mode, there is no spacing between buttons and the internal padding is ignored.

Built-in actions - there are several "built-in" actions that you can use in the ToolBar: "Add item", "Rename group", "Edit group", and "Remove group". These are all enabled by default, but can be selectively disabled via the setAllow...() methods. If enabled, they will appear in the toolbar for each ActionGroup. You can change the icons for these built-in actions via the appropriate setter methods in this class. The "Add item" action requires a ToolBarNewItemSupplier to be provided via setNewActionSupplier() in order to appear in the toolbar, but the other built-in actions do not require any suppliers.

Custom actions - you can also add your own custom actions to the toolbar for each ActionGroup by adding ToolBarActionSuppliers via the addCustomActionSupplier() method. Each supplier will be invoked for each ActionGroup when the toolbar is built, and can return a ToolBarAction to add to that group. You can add as many suppliers as you want, and they will be invoked in the order they were added. Your custom ToolBarActions must supply icons! Our buttons are icon-based and do not show text.

Excluding "special" groups - sometimes you have a group that contains actions that relate to the ActionPanel as a whole. For example, actions for adding new groups, or managing groups, or selecting the source of your groups. Such "special" groups probably shouldn't have a toolbar, as the toolbar actions wouldn't make sense for them. So, you can use the addExcludedGroup() method to exclude a group by name (case-insensitive) from having a toolbar.

Since:
swing-extras 2.8
Author:
scorbo2

  • Method Details

    • getButtonPosition

      public ToolBarOptions.ButtonPosition getButtonPosition()
      Returns the current ButtonPosition for this toolbar. This controls how the buttons are aligned within their container panel.
      Returns:
      The current ButtonPosition for this toolbar.

    • setButtonPosition

      public ToolBarOptions setButtonPosition(ToolBarOptions.ButtonPosition buttonPosition)
      Decides how buttons are to be presented in the ToolBar. The default is Stretch, which stretches the buttons evenly across the entire width of the container panel.
      Parameters:
      buttonPosition - The ButtonPosition to use for this toolbar. Cannot be null.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • getIconSize

      public int getIconSize()
      Returns the current icon size for this toolbar. This controls the size of all icons in the toolbar, including the built-in action icons and any custom action icons. The default is ActionPanel.DEFAULT_ICON_SIZE.
      Returns:
      The current icon size for this toolbar.

    • setIconSize

      public ToolBarOptions setIconSize(int iconSize)
      Sets the icon size for this toolbar. This controls the size of all icons in the toolbar, including the built-in action icons and any custom action icons. The default is ActionPanel.DEFAULT_ICON_SIZE.
      Parameters:
      iconSize - The icon size to use for this toolbar. Must be a positive integer.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • setNewActionSupplier

      public ToolBarOptions setNewActionSupplier(ToolBarNewItemSupplier newActionSupplier)
      If allowItemAdd is true and a Supplier is given here, then an "Add item" button will be shown in the toolbar. Clicking it will invoke the Supplier to get a new action to add. If allowItemAdd is false, then no "Add item" button will be shown, even if a Supplier is given here.

      If your supplier returns null, then it is assumed that the user canceled the add action, so no change will be made. Otherwise, the new action will either be added to the end of the current group, or will be sorted within the group, depending on the ActionPanel's sorting options.

      A built-in "add" icon will be provided by default, as our buttons never show text. You can change the icon via setAddItemIcon().

      Parameters:
      newActionSupplier - A ToolBarNewItemSupplier instance. The supplier can return null to cancel the add.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • getNewActionSupplier

      public ToolBarNewItemSupplier getNewActionSupplier()
      Returns the ToolBarNewItemSupplier responsible for supplying new ToolBarActions when the user clicks the "Add item" button in the toolbar. If no Supplier is given, then this will return null. If a supplier is present, and the isAllowItemAdd option is true, then an "Add item" button will be shown in the toolbar, and clicking it will invoke the Supplier to get a new action to add.
      Returns:
      a ToolBarNewItemSupplier instance, or null if one is not set.

    • addCustomActionSupplier

      public ToolBarOptions addCustomActionSupplier(ToolBarActionSupplier actionSupplier)
      You can add your own buttons to the ToolBar in addition to (or instead of, if you disable them) the built-in ones. The given ToolBarActionSupplier will be invoked for each ActionGroup when the toolbar is built, and should return ToolBarAction to add to that group. You can add as many suppliers as you want, and they will be invoked in the order they were added. If a supplier returns null for a given group, it is ignored.
      Parameters:
      actionSupplier - A ToolBarActionSupplier that will be invoked for each ActionGroup when the toolbar is built. Cannot be null.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • removeCustomActionSupplier

      public ToolBarOptions removeCustomActionSupplier(ToolBarActionSupplier actionSupplier)
      Removes a custom action supplier that was previously added via addCustomActionSupplier(). If the given supplier was not previously added, then this method does nothing. If the given supplier is null, then an IllegalArgumentException is thrown.
      Parameters:
      actionSupplier - The ToolBarActionSupplier to remove. Cannot be null.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • clearCustomActionSuppliers

      public ToolBarOptions clearCustomActionSuppliers()
      Removes all custom action suppliers that were previously added via addCustomActionSupplier().
      Returns:
      this ToolBarOptions instance, for method chaining.

    • setAllowItemAdd

      public ToolBarOptions setAllowItemAdd(boolean allowItemAdd)
      If true, and if a Supplier is given via setNewActionSupplier(), then an "Add item" button will be shown in the toolbar. Setting this to false does not remove the Supplier, so you can later toggle it back to true without having to set the Supplier again. If false, then no "Add item" button will be shown, even if a Supplier is given.
      Parameters:
      allowItemAdd - Whether to allow adding items to the toolbar. Must also call setNewActionSupplier()!
      Returns:
      this ToolBarOptions instance, for method chaining.

    • setAllowItemReorder

      public ToolBarOptions setAllowItemReorder(boolean allowItemReorder)
      If true, then an "Edit group" button will be shown in the toolbar for each ActionGroup, which allows the user to reorder items from that group.
      Parameters:
      allowItemReorder - Whether to show the "edit group" button in the toolbar.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • setAllowGroupRename

      public ToolBarOptions setAllowGroupRename(boolean allowGroupRename)
      If true, then a "Rename group" button will be shown in the toolbar for each ActionGroup, which allows the user to rename the group.
      Parameters:
      allowGroupRename - Whether to allow renaming groups in the toolbar.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • setAllowItemRemoval

      public ToolBarOptions setAllowItemRemoval(boolean allowItemRemoval)
      If true, then an "Edit group" button will be shown in the toolbar for each ActionGroup, which allows the user to remove items from that group.
      Parameters:
      allowItemRemoval - Whether to allow removing items in the toolbar.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • setAllowGroupRemoval

      public ToolBarOptions setAllowGroupRemoval(boolean allowGroupRemoval)
      If true, then a "Remove group" button will be shown in the toolbar for each ActionGroup, which allows the user to remove that group.
      Parameters:
      allowGroupRemoval - Whether to allow removing groups in the toolbar.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • setAddItemIcon

      public ToolBarOptions setAddItemIcon(ImageIcon addItemIcon)
      Overrides the default "add" icon for the "Add item" button. This only has an effect if allowItemAdd is true and a Supplier is given via setNewActionSupplier().
      Parameters:
      addItemIcon - The icon to use for the "Add item" button. Cannot be null.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • setRenameIcon

      public ToolBarOptions setRenameIcon(ImageIcon renameIcon)
      Overrides the default "rename" icon for the "Rename group" button. This only has an effect if allowGroupRename is true.
      Parameters:
      renameIcon - The icon to use for the "Rename group" button. Cannot be null.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • setEditIcon

      public ToolBarOptions setEditIcon(ImageIcon editIcon)
      Overrides the default "edit" icon for the "Edit item" button. This only has an effect if allowItemReorder is true.
      Parameters:
      editIcon - The icon to use for the "Edit item" button. Cannot be null.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • setRemoveIcon

      public ToolBarOptions setRemoveIcon(ImageIcon removeIcon)
      Overrides the default "remove" icon for the "Remove item" and "Remove group" buttons. This only has an effect if allowItemRemoval or allowGroupRemoval is true.
      Parameters:
      removeIcon - The icon to use for the "Remove item" and "Remove group" buttons. Cannot be null.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • isAllowItemAdd

      public boolean isAllowItemAdd()
      Indicates whether the toolbar should show an "Add item" button for each ActionGroup. If true, then an "Add item" button will be shown for each ActionGroup. You must also supply a ToolBarNewItemSupplier via setNewActionSupplier()! Otherwise, the "add item" button will not appear.
      Returns:
      Whether the toolbar should show an "Add item" button for each ActionGroup.

    • isAllowGroupRename

      public boolean isAllowGroupRename()
      Indicates whether the built-in "Rename group" action is enabled. If true, then a "Rename group" button will be shown for each ActionGroup.
      Returns:
      Whether the built-in "Rename group" action is enabled.

    • isAllowItemReorder

      public boolean isAllowItemReorder()
      Indicates whether the built-in "Edit group" action for reordering and removing items is enabled. If true, then an "Edit group" button will be shown for each ActionGroup, which allows the user to reorder and remove items from that group.
      Returns:
      Whether the built-in "Edit group" action for reordering and removing items is enabled.

    • isAllowItemRemoval

      public boolean isAllowItemRemoval()
      Indicates whether item removal is enabled in the built-in "Edit group" action. If true, then the "Edit group" button will allow the user to remove items from that group.
      Returns:
      Whether item removal is enabled in the built-in "Edit group" action.

    • isAllowGroupRemoval

      public boolean isAllowGroupRemoval()
      Indicates whether the built-in "Remove group" action is enabled. If true, then a "Remove group" button will be shown for each ActionGroup, which allows the user to remove that group entirely.
      Returns:
      Whether the built-in "Remove group" action is enabled.

    • addExcludedGroup

      public ToolBarOptions addExcludedGroup(String groupName)
      All ActionGroups get a ToolBar by default, if the ToolBar is enabled for the ActionPanel. But, sometimes you have a "special" group that should not get a toolbar. An example of when you would do this is if you have a group that contains actions that relate to the ActionPanel itself instead of to a particular group. For example, an action that adds a new group, or an action that allows you to select the source of your groups. Such "special" groups probably shouldn't have the same toolbar as all other groups. So, you can use this method to exclude a group by name (case-insensitive). The named group will not receive a toolbar, even if the toolbar is enabled for the ActionPanel, and even if you have supplied custom toolbar actions.

      Renaming groups - if a group is renamed, this list of excluded groups may fall out of sync with what's in ActionPanel. We don't actually check for group renames here, because the only way (currently) to rename a group is to go through the "rename group" action on the toolbar. If a group has no toolbar, then there's no way to rename it. But if your application offers some other way to rename groups, you have to be diligent about keeping this excluded group list in sync with what's in the ActionPanel.

      Parameters:
      groupName - The name of the group to exclude from having a toolbar (case-insensitive). Cannot be null.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • removeExcludedGroup

      public ToolBarOptions removeExcludedGroup(String groupName)
      Removes a group from the "toolbar excluded" list, if it was previously added via the addExcludedGroup() method. If the given group name was not previously added, then this method does nothing.
      Parameters:
      groupName - The name of the group to remove from the "toolbar excluded" list (case-insensitive). Cannot be null.
      Returns:
      this ToolBarOptions instance, for method chaining.

    • isGroupExcluded

      public boolean isGroupExcluded(String groupName)
      Reports whether the named group (case-insensitive) is on the "toolbar excluded" list, meaning that it should not receive a toolbar even if the toolbar is enabled for the ActionPanel.
      Parameters:
      groupName - The name of the group to check (case-insensitive). Cannot be null.
      Returns:
      true if the named group is on the "toolbar excluded" list, meaning that it should not receive a toolbar; false otherwise.

    • createItemAddAction

      public ToolBarAction createItemAddAction(ActionPanel actionPanel, String groupName)
      If allowItemAdd is true and a Supplier is given via setNewActionSupplier(), then this method will return a ToolBarAction for adding a new item to the given ActionGroup. Otherwise, it returns null.
      Parameters:
      actionPanel - The ActionPanel that will be supplied to the Supplier when it is invoked.
      groupName - The case-insensitive group name that will be supplied to the Supplier when it is invoked.
      Returns:
      A ToolBarAction for adding a new item to the given ActionGroup. Might be null.

    • createRenameGroupAction

      public ToolBarAction createRenameGroupAction(ActionPanel actionPanel, String groupName)
      If allowGroupRename is true, then this method will return a ToolBarAction for renaming the given ActionGroup. Otherwise, it returns null. The built-in rename action handles name conflicts automatically, and won't allow the rename if the new name (case-insensitive) is already in use by some other group. You can change the icon for the rename action via setRenameIcon(), and you can disable the rename action entirely via setAllowGroupRename(false).
      Parameters:
      actionPanel - The ActionPanel that will be supplied to the ToolBarGroupRenameAction when it is invoked.
      groupName - The case-insensitive group name that will be supplied to the ToolBarGroupRenameAction when it is invoked.
      Returns:
      A ToolBarAction for renaming the given ActionGroup. Might be null.

    • createEditGroupAction

      public ToolBarAction createEditGroupAction(ActionPanel actionPanel, String groupName)
      If allowItemReorder or allowItemRemoval is true, then this method will return a ToolBarAction for editing the items in the given ActionGroup.
      Parameters:
      actionPanel - The ActionPanel that will be supplied to the ToolBarGroupEditAction when it is invoked.
      groupName - The case-insensitive group name that will be supplied to the ToolBarGroupEditAction when it is invoked.
      Returns:
      A ToolBarAction for editing the items in the given ActionGroup. Might be null.

    • createRemoveGroupAction

      public ToolBarAction createRemoveGroupAction(ActionPanel actionPanel, String groupName)
      If allowGroupRemoval is true, then this method will return a ToolBarAction for removing the given ActionGroup. Otherwise, it returns null.
      Parameters:
      actionPanel - The ActionPanel that will be supplied to the ToolBarGroupRemoveAction when it is invoked.
      groupName - The case-insensitive group name that will be supplied to the ToolBarGroupRemoveAction when it is invoked.
      Returns:
      A ToolBarAction for removing the given ActionGroup. Might be null.

    • createCustomActions

      public List<ToolBarAction> createCustomActions(ActionPanel actionPanel, String groupName)
      Returns a list of custom ToolBarActions to add to the toolbar for the given ActionGroup. This is done by invoking each ToolBarActionSupplier that was added via addCustomActionSupplier() and collecting the non-null results. If no suppliers were added, or if all suppliers returned null for the given group, then this method returns an empty list.
      Parameters:
      actionPanel - The ActionPanel that will be supplied to each ToolBarActionSupplier when it is invoked.
      groupName - The case-insensitive group name that will be supplied to each ToolBarActionSupplier when it is invoked.
      Returns:
      A list of custom ToolBarActions to add to the toolbar for the given ActionGroup. Never null, but might be empty.