Package edu.cnu.mdi.graphics.toolbar

Class AToolBar

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JToolBar
edu.cnu.mdi.graphics.toolbar.AToolBar
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants
Direct Known Subclasses:
BaseToolBar
public abstract class AToolBar extends JToolBar
A convenience JToolBar for toolbars that contain a mutually exclusive set of JToggleButtons (i.e., a radio-button-like group), plus optional one-shot buttons.

This class manages:

  • a primary ButtonGroup that enforces mutual exclusivity
  • an optional default toggle button (selected when the active toggle is turned off)
  • a selection-change hook for subclasses
  • a registry of buttons by stable id for programmatic enable/disable

Button registry

Toolbars often need to enable/disable specific tools depending on application state (e.g., disable Delete when nothing is selected). Rather than forcing applications to keep references to every button instance, this class supports registering buttons under a stable string id and retrieving them later: 


 toolBar.setButtonEnabled("delete", hasSelection);
 toolBar.getButton("pointer", JToggleButton.class).setSelected(true);

For predefined buttons, you typically use ToolBits.getId(long) as the stable id. For application-defined buttons, choose your own ids.

Notes

Author:
heddle
See Also:

  • Field Details

    • CLIENTPROP_TOOL_ID

      public static final String CLIENTPROP_TOOL_ID
      Client property key used to store an id on a button.
      See Also:

    • toggleGroup

      protected final ButtonGroup toggleGroup
      Primary mutually-exclusive group for tool toggle buttons.

    • statusField

      protected JTextField statusField
      Status field to display messages (may be null).

  • Constructor Details

    • AToolBar

      public AToolBar()
      Create a toolbar with horizontal orientation.

    • AToolBar

      public AToolBar(int orientation)
      Create a toolbar with the given orientation.
      Parameters:
      orientation - SwingConstants.HORIZONTAL or SwingConstants.VERTICAL.

  • Method Details

    • registerButton

      protected <T extends AbstractButton> T registerButton(String id, T button)
      Register a toolbar button under a stable id.

      This is used by the id-aware add methods. It is also safe for subclasses to call directly if they add components via Container.add(Component).

      For debugging and tooling, this method also sets:

      Parameters:
      id - stable identifier (non-blank).
      button - the button to register.
      Returns:
      the same button (for chaining).
      Throws:
      NullPointerException - if id or button is null.
      IllegalArgumentException - if id is blank or already used by a different button.

    • removeButton

      public AbstractButton removeButton(String id)
      Remove a registered button from the registry by id.

      This does not remove the button from the Swing component hierarchy. If you dynamically remove tools, call this in addition to Container.remove(Component).

      Parameters:
      id - the id to remove (null/blank are ignored).
      Returns:
      the removed button, or null if none was registered.

    • getButton

      public AbstractButton getButton(String id)
      Look up a registered toolbar button by id.
      Parameters:
      id - the id used when adding/registering the button.
      Returns:
      the button, or null if not found.

    • getButton

      public <T extends AbstractButton> T getButton(String id, Class<T> type)
      Look up a registered toolbar button by id and expected type.
      Type Parameters:
      T - type parameter.
      Parameters:
      id - the id used when adding/registering the button.
      type - expected type.
      Returns:
      the typed button, or null if not found or wrong type.

    • requireButton

      public <T extends AbstractButton> T requireButton(String id, Class<T> type)
      Look up a registered toolbar button by id, throwing if missing.

      This is handy in application wiring code where missing tools should be a programming error rather than silently ignored.

      Type Parameters:
      T - type parameter.
      Parameters:
      id - registered id (non-blank).
      type - expected type.
      Returns:
      the typed button (never null).
      Throws:
      IllegalStateException - if no button exists under that id, or the type is wrong.

    • setButtonEnabled

      public boolean setButtonEnabled(String id, boolean enabled)
      Enable or disable a registered button by id.
      Parameters:
      id - button id.
      enabled - new enabled state.
      Returns:
      true if the button was found and updated, false if no button is registered under that id.

    • getToolId

      public static String getToolId(AbstractButton button)
      Try to read the registered tool id from a button.
      Parameters:
      button - a button that may have been registered.
      Returns:
      the id string, or null if not present.

    • registerExternalToggle

      public JToggleButton registerExternalToggle(String id, JToggleButton toggleButton)
      Registers an external toggle button with this toolbar's primary toggle group without adding the button to the toolbar component hierarchy.

      This is useful for palette buttons that should behave like tools and be mutually exclusive with toolbar toggles, while remaining visually located outside the toolbar.

      Parameters:
      id - stable identifier for the external tool
      toggleButton - external toggle button
      Returns:
      the same toggle button

    • getButtonRegistryView

      public Map<String,AbstractButton> getButtonRegistryView()
      Returns:
      an unmodifiable view of the current button registry.

    • addButton

      public JButton addButton(String id, JButton button)
      Add a button to the toolbar and register it under the given id.
      Parameters:
      id - stable identifier for later retrieval (non-blank).
      button - the button to add.
      Returns:
      the added button (for chaining).
      Throws:
      NullPointerException - if id or button is null.
      IllegalArgumentException - if id is blank or already used.

    • addToggle

      public JToggleButton addToggle(String id, JToggleButton toggleButton)
      Add a toggle to the toolbar and register it under the given id.
      Parameters:
      id - stable identifier for later retrieval (non-blank).
      toggleButton - the toggle to add.
      Returns:
      the added toggle (for chaining).

    • addToggle

      public JToggleButton addToggle(JToggleButton toggleButton, boolean toGroup)
      Add a toggle button to the toolbar, optionally adding it to the primary mutually-exclusive group.
      Parameters:
      toggleButton - the toggle to add.
      toGroup - if true, add to the primary mutually-exclusive group.
      Returns:
      the added toggle.

    • addToggle

      public JToggleButton addToggle(String id, JToggleButton toggleButton, boolean toGroup)
      Add a toggle button to the toolbar, optionally adding it to the primary mutually-exclusive group, and register it under the given id.
      Parameters:
      id - stable identifier for later retrieval (non-blank).
      toggleButton - the toggle to add.
      toGroup - if true, add to the primary mutually-exclusive group.
      Returns:
      the added toggle (for chaining).
      Throws:
      NullPointerException - if id or toggleButton is null.
      IllegalArgumentException - if id is blank or already used.

    • removeToggle

      public void removeToggle(JToggleButton toggleButton)
      Remove a toggle button from the toolbar and from the primary group.
      Parameters:
      toggleButton - the toggle to remove (ignored if null).

    • activeToggleButtonChanged

      protected abstract void activeToggleButtonChanged(JToggleButton newlyActive)
      Called when the active toggle button in the primary group changes.

      Subclasses override this to react to a tool selection change.

      Parameters:
      newlyActive - the button that just became selected (never null).

    • getDefaultToggleButton

      public JToggleButton getDefaultToggleButton()
      Get the default toggle button (if any).
      Returns:
      the default toggle button, or null.

    • setDefaultToggleButton

      public void setDefaultToggleButton(JToggleButton defaultToggleButton)
      Set the default toggle button.
      Parameters:
      defaultToggleButton - the default toggle (may be null).
      Throws:
      IllegalArgumentException - if the button is not null but not contained in this toolbar (it should be added first).

    • resetDefaultToggleButton

      public void resetDefaultToggleButton()
      Programmatically select the default toggle button.

      If another toggle is currently active, it will be deselected by the ButtonGroup. If no default is set, this method does nothing.

    • getActiveButton

      public JToggleButton getActiveButton()
      Return the currently selected toggle button from the primary group.
      Returns:
      the selected toggle, or null if none is selected.

    • updateStatusText

      public void updateStatusText(String text)
      Set the status text shown on the toolbar.
      Parameters:
      text - the status text to set.

    • hasStatusField

      public boolean hasStatusField()
      Check if this toolbar has a status field.
      Returns:
      true if this toolbar has a status field, false if not.

    • spacer

      public void spacer(int pixels)
      Add a spacer of the given size in pixels.
      Parameters:
      pixels - the size of the spacer in pixels.