Package ca.cgjennings.ui

Class JCycleButton<M>

  • All Implemented Interfaces:
    SettingBackedControl, java.awt.image.ImageObserver, java.awt.ItemSelectable, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible, javax.swing.SwingConstants
    public class JCycleButton<M>
extends javax.swing.JButton
implements SettingBackedControl
    A user interface control that cycles through a fixed set of options. This is similar to a JSpinner, but the selected value cannot be edited with the keyboard and the control has a button-like appearance rather than a field-like appearance.

    The cycle control is appropriate when the user must select amongst a fixed, small number of options. Two options is an ideal number, and three is acceptable. More than that and it becomes awkward for the user to discover the possible values.

    The button uses a simple model consisting of an array of the possible choices. You can listen for changes in the selected item by adding an ActionListener as you would for other button types.

    Since:
    3.0
    Author:
    Chris Jennings
    See Also:
    Serialized Form

    • Nested Class Summary

      • Nested classes/interfaces inherited from class javax.swing.JButton

        javax.swing.JButton.AccessibleJButton

      • Nested classes/interfaces inherited from class javax.swing.AbstractButton

        javax.swing.AbstractButton.AccessibleAbstractButton, javax.swing.AbstractButton.ButtonChangeListener

      • Nested classes/interfaces inherited from class javax.swing.JComponent

        javax.swing.JComponent.AccessibleJComponent

      • Nested classes/interfaces inherited from class java.awt.Container

        java.awt.Container.AccessibleAWTContainer

      • Nested classes/interfaces inherited from class java.awt.Component

        java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

    • Field Summary

      • Fields inherited from class javax.swing.AbstractButton

        actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY

      • Fields inherited from class javax.swing.JComponent

        listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

      • Fields inherited from class java.awt.Component

        accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

      • Fields inherited from interface java.awt.image.ImageObserver

        ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

      • Fields inherited from interface javax.swing.SwingConstants

        BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST

    • Constructor Summary

      Constructors 
      Constructor Description
      JCycleButton()
      Creates a new cycle button with an empty model.
      JCycleButton​(M[] model)
      Creates a new cycle button with the specified model.
      JCycleButton​(M[] model, java.lang.String[] settingValues)
      Creates a new cycle button with the specified model and a matching array of string values that will be used as setting proxies.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void fireActionPerformed​(java.awt.event.ActionEvent event)  
      void fromSetting​(java.lang.String v)
      Selects the item that matches the specified setting value.
      java.lang.Object[] getCycleModel()
      Returns a copy of the current model.
      java.awt.Dimension getMinimumSize()  
      java.awt.Dimension getPreferredSize()  
      int getSelectedIndex()
      Returns the index of the selected item in the model.
      M getSelectedItem()
      Returns the currently selected item, as displayed on the face of the button.
      java.awt.Dimension getSize()  
      void setCycleModel​(M... model)
      Sets the model that the button cycles through.
      void setFont​(java.awt.Font font)  
      void setIcon​(javax.swing.Icon icon)  
      void setSelectedIndex​(int index)
      Sets the currently selected item.
      void setSelectedItem​(M selection)
      Sets the currently selected item.
      java.lang.String toSetting()
      Returns a setting value to represent the selected item.

      • Methods inherited from class javax.swing.JButton

        getAccessibleContext, getUIClassID, isDefaultButton, isDefaultCapable, paramString, removeNotify, setDefaultCapable, updateUI

      • Methods inherited from class javax.swing.AbstractButton

        actionPropertyChanged, addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, configurePropertiesFromAction, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, init, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setEnabled, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setModel, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition

      • Methods inherited from class javax.swing.JComponent

        addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

      • Methods inherited from class java.awt.Container

        add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusDownCycle, validate, validateTree

      • Methods inherited from class java.awt.Component

        action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • JCycleButton

        public JCycleButton()
        Creates a new cycle button with an empty model.

      • JCycleButton

        public JCycleButton​(M[] model)
        Creates a new cycle button with the specified model.
        Parameters:
        model - an array of the possible selections
        See Also:
        setCycleModel(M...)

      • JCycleButton

        public JCycleButton​(M[] model,
                    java.lang.String[] settingValues)
        Creates a new cycle button with the specified model and a matching array of string values that will be used as setting proxies. The proxy values are used when mapping the selected object to or from a setting value. For example, the model could be a string model with values "Female" and "Male", while the proxy setting values could be "F" and "M".

        Note: This constructor is only relevant if using the button as SettingBackedControl.

        Parameters:
        model - an array of the possible selections
        settingValues - an array of matching setting proxies, or null
        See Also:
        setCycleModel(M...), toSetting(), fromSetting(java.lang.String)

    • Method Detail

      • getSelectedIndex

        public int getSelectedIndex()
        Returns the index of the selected item in the model. Returns -1 if the model is null or empty.
        Returns:
        the index of the selected item

      • setSelectedIndex

        public void setSelectedIndex​(int index)
        Sets the currently selected item. If the index is beyond the last element in the model, or if it is less than zero, the first element is selected (if any).
        Parameters:
        index - the index of the element in the model to select

      • setSelectedItem

        public void setSelectedItem​(M selection)
        Sets the currently selected item. This has no effect if the supplied value is not in the model.
        Parameters:
        selection - the model member to select

      • getSelectedItem

        public M getSelectedItem()
        Returns the currently selected item, as displayed on the face of the button.
        Returns:
        the selected item, or null if there is no model set

      • setFont

        public void setFont​(java.awt.Font font)
        Overrides:
        setFont in class javax.swing.JComponent

      • setIcon

        public void setIcon​(javax.swing.Icon icon)
        Overrides:
        setIcon in class javax.swing.AbstractButton

      • setCycleModel

        @SafeVarargs
public final void setCycleModel​(M... model)
        Sets the model that the button cycles through. The button will make its own copy of the supplied model.
        Parameters:
        model - an array of the possible selections
        Throws:
        java.lang.IllegalArgumentException - if there are proxy setting values and the number of elements in the model does not match the number of proxy setting values

      • getCycleModel

        public java.lang.Object[] getCycleModel()
        Returns a copy of the current model.
        Returns:
        an array of the values that the button will cycle through; null if no model has been set

      • fireActionPerformed

        protected void fireActionPerformed​(java.awt.event.ActionEvent event)
        Overrides:
        fireActionPerformed in class javax.swing.AbstractButton

      • getPreferredSize

        public java.awt.Dimension getPreferredSize()
        Overrides:
        getPreferredSize in class javax.swing.JComponent

      • getMinimumSize

        public java.awt.Dimension getMinimumSize()
        Overrides:
        getMinimumSize in class javax.swing.JComponent

      • getSize

        public java.awt.Dimension getSize()
        Overrides:
        getSize in class java.awt.Component

      • fromSetting

        public void fromSetting​(java.lang.String v)
        Selects the item that matches the specified setting value. If this button was created with setting proxies, the index of the proxy that equals the specified value will become the selected index. Otherwise, the element in the model whose toString value matches the specified value is selected.
        Specified by:
        fromSetting in interface SettingBackedControl
        Parameters:
        v - the setting value that represents the value to select

      • toSetting

        public java.lang.String toSetting()
        Returns a setting value to represent the selected item. If this button was created with setting proxies, the proxy for the selected item is returned. Otherwise, the toString() value of the selected item is returned.
        Specified by:
        toSetting in interface SettingBackedControl
        Returns:
        a setting value for the selected item