Package edu.cnu.mdi.component

Class OptionPanel

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
edu.cnu.mdi.component.OptionPanel
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class OptionPanel extends JPanel
A panel that arranges a set of boolean options (JCheckBoxes) in a multi-column layout suitable for use in MDI views.

Option Data Format

Options are specified as an array of three-element String arrays: 

 { { "Option 1", "true",  "false" },
   { "Option 2", "true",  "true"  },
   { "Option 3", "false", "false" } }

Each inner array must contain exactly three elements:

  1. label – the text shown beside the checkbox (index 0)
  2. enabled – "true" or "false" (index 1)
  3. selected– "true" or "false" (index 2)

Layout

Checkboxes are distributed across the requested number of columns in column-major order (filled top-to-bottom, then left-to-right). Three ordering modes are available via the layoutOption constructor parameter:

  • AS_ORDERED – options appear in the order supplied
  • ALPHABETICAL – options are sorted by label (case-insensitive)
  • MINSIZE – options are sorted so the widest labels are spread across columns, minimising overall panel width

Each column is only as wide as its widest checkbox. Columns are separated by HGAP pixels, and rows are spaced by font-height plus VGAP pixels.

Preferred-size and borders

Layout is performed once at construction time using a null layout (absolute positioning). The content size (the area required by the checkboxes themselves, excluding any border insets) is captured in _contentSize. getPreferredSize() then adds the panel's current insets to that content size each time it is called, so the result is always correct even when a border — such as a CommonBorder — is applied after construction (which would otherwise cause the border's title area to be clipped).

Thread safety

This class is not thread-safe. All interactions must occur on the Swing Event Dispatch Thread (EDT).

See Also:

  • Field Details

    • AS_ORDERED

      public static final int AS_ORDERED
      Layout option: display options in the order they were supplied to the constructor, with no reordering.
      See Also:

    • ALPHABETICAL

      public static final int ALPHABETICAL
      Layout option: sort options alphabetically by label (case-insensitive) before laying them out in columns.
      See Also:

    • MINSIZE

      public static final int MINSIZE
      Layout option: sort options by descending label pixel width before laying them out in columns. This tends to produce the narrowest overall panel width because the widest labels are distributed evenly across columns rather than all ending up in the same one.
      See Also:

    • HGAP

      public static final int HGAP
      Horizontal gap in pixels between adjacent columns of checkboxes. Callers who need a different gap should subclass or wrap the panel.
      See Also:

    • VGAP

      public static final int VGAP
      Additional vertical gap in pixels added to the font height to determine the height of each row.
      See Also:

  • Constructor Details

    • OptionPanel

      public OptionPanel(OptionPanel.OptionPanelListener listener, int columnCount, Font font, Color foreground, Color background, int layoutOption, String[][] optionData)
      Creates an OptionPanel with the specified configuration.

      Layout is performed immediately during construction. If a border will be added after construction (e.g. in a subclass), getPreferredSize() will still return the correct size because it adds the current insets dynamically rather than relying on a snapshot taken at construction time.

      Parameters:
      listener - callback notified when any checkbox changes state; null is permitted and means no notification
      columnCount - desired number of columns; must be ≥ 1
      font - font used for all checkbox labels; must not be null
      foreground - foreground (text) colour for labels; null uses the look-and-feel default
      background - background colour for the panel and all checkboxes; null uses the look-and-feel default and leaves the panel non-opaque
      layoutOption - ordering mode; one of AS_ORDERED, ALPHABETICAL, or MINSIZE
      optionData - option specifications; each element must be a three-element array {label, enabled, selected}
      Throws:
      IllegalArgumentException - if columnCount < 1, font is null, optionData is null, or any inner array has fewer than three elements

  • Method Details

    • getPreferredSize

      public Dimension getPreferredSize()
      Returns the preferred size of this panel, dynamically adding the panel's current border insets to the pre-computed content size.

      Because insets are read at call time rather than snapshotted at construction time, this method returns a correct value even when a border (e.g. a CommonBorder) is applied after the constructor returns — a pattern used by subclasses such as ChimeraOptionPanel.

      Overrides:
      getPreferredSize in class JComponent
      Returns:
      the preferred Dimension; never null

    • doLayout

      public void doLayout()
      Positions each checkbox using the panel's current insets as the content origin.

      Because this method is called by Swing every time the component is validated — including after a border is applied post-construction — the checkboxes are always placed below the titled border's title text and inside any other inset region, regardless of when Border was set.

      The column/row assignments and column widths computed by layoutEntries() are reused here; only the pixel coordinates are recalculated.

      Overrides:
      doLayout in class Container

    • isOptionSelected

      public boolean isOptionSelected(String label)
      Returns whether the option identified by label is currently selected.
      Parameters:
      label - the label of the option to query; must not be null
      Returns:
      true if the option exists and its checkbox is selected; false otherwise (including when the label is not found)

    • setOptionSelected

      public void setOptionSelected(String label, boolean selected)
      Programmatically sets the selected state of the checkbox identified by label.

      If the label is not found, this method does nothing. The call will fire any registered OptionPanel.OptionPanelListener (via the checkbox's own ItemListener) if the state actually changes.

      Parameters:
      label - the label of the option to update; must not be null
      selected - true to select, false to deselect

    • setOptionEnabled

      public void setOptionEnabled(String label, boolean enabled)
      Enables or disables the checkbox identified by label.

      A disabled checkbox is visible but cannot be interacted with by the user. If the label is not found, this method does nothing.

      Parameters:
      label - the label of the option to update; must not be null
      enabled - true to enable, false to disable

    • getSelectedOptionLabels

      public String[] getSelectedOptionLabels()
      Returns the labels of all currently selected options, in the order they were originally supplied to the constructor.
      Returns:
      a new array containing the labels of all selected options; never null, but may be empty

    • getCheckBox

      public JCheckBox getCheckBox(String label)
      Returns the underlying JCheckBox for the option identified by label, or null if no such option exists.

      This method is intended for advanced customisation (e.g. attaching additional listeners or tweaking renderer properties). Prefer the higher-level methods (isOptionSelected(java.lang.String), setOptionSelected(java.lang.String, boolean), etc.) for normal use.

      Parameters:
      label - the label of the option; must not be null
      Returns:
      the JCheckBox, or null if the label is not found