Package jmri.swing

Class NamedBeanComboBox<B extends NamedBean>

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

javax.swing.JComboBox<B>

jmri.swing.NamedBeanComboBox<B>

Type Parameters:

B - the supported type of NamedBean

All Implemented Interfaces:

ActionListener, ImageObserver, ItemSelectable, MenuContainer, Serializable, EventListener, Accessible, ListDataListener

Direct Known Subclasses:

NamedBeanBoxRenderer

public class NamedBeanComboBox<B extends NamedBean>
extends JComboBox<B>

A JComboBox for NamedBeans.

When editable, this will create a new NamedBean if backed by a ProvidingManager if getSelectedItem() is called and the current text is neither the system name nor user name of an existing NamedBean. This will also validate input when editable, showing an Information (blue I in circle) icon to indicate a name will be used to create a new Named Bean, an Error (red X in circle) icon to indicate a typed in name cannot be used (either because it would not be valid as a user name or system name or because the name of an existing NamedBean not usable in the current context has been entered, or no icon to indicate the name of an existing Named Bean has been entered.

When not editable, this will allow (but may not actively show) continual typing of a system name or a user name by a user to match a NamedBean even if only the system name or user name or both are displayed (e.g. if a list of turnouts is shown by user name only, a user may type in the system name of the turnout and the turnout will be selected correctly). If the typing speed is slower than the UIManager's ComboBox.timeFactor setting, keyboard input acts like a normal JComboBox, with only the first character displayed matching the user input.

Note: It is recommended that implementations that exclude some NamedBeans from the combo box call JComponent.setToolTipText(String) to provide a context specific reason for excluding those items. The default tool tip reads (example for Turnouts) "Turnouts not shown cannot be used in this context.", but a better tool tip (example for Signal Heads when creating a Signal Mast) may be "Signal Heads not shown are assigned to another Signal Mast."

To change the tool tip text shown when an existing bean is not selected, this class should be subclassed and the methods getBeanInUseMessage(java.lang.String, java.lang.String), getInvalidNameFormatMessage(java.lang.String, java.lang.String, java.lang.String), getNoMatchingBeanMessage(java.lang.String, java.lang.String), and getWillCreateBeanMessage(java.lang.String, java.lang.String) should be overridden.

See Also:

• Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JComboBox

JComboBox.AccessibleJComboBox, JComboBox.KeySelectionManager

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

JComponent.AccessibleJComponent

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

Container.AccessibleAWTContainer

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

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields inherited from class javax.swing.JComboBox

actionCommand, dataModel, editor, isEditable, keySelectionManager, lightWeightPopupEnabled, maximumRowCount, renderer, selectedItemReminder

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

Constructor Summary

Constructors

Constructor	Description
NamedBeanComboBox(Manager<B> manager)	Create a ComboBox without a selection using the NamedBean.DisplayOptions.DISPLAYNAME to sort NamedBeans.
NamedBeanComboBox(Manager<B> manager, B selection)	Create a ComboBox with an existing selection using the NamedBean.DisplayOptions.DISPLAYNAME to sort NamedBeans.
NamedBeanComboBox(Manager<B> manager, B selection, NamedBean.DisplayOptions displayOrder)	Create a ComboBox with an existing selection using the specified display order to sort NamedBeans.
NamedBeanComboBox(Manager<B> manager, B selection, NamedBean.DisplayOptions displayOrder, Predicate<B> filter)	Create a ComboBox with an existing selection using the specified display order to sort NamedBeans.

Method Summary

Modifier and Type	Method	Description
void	dispose()
String	getBeanInUseMessage(String beanType, String displayName)	Get the localized message to display in a tooltip when a typed in bean name matches a named bean has been included in a call to setExcludedItems(java.util.Set) and isValidatingInput() is true.
NamedBean.DisplayOptions	getDisplayOrder()
Set<B>	getExcludedItems()
String	getInvalidNameFormatMessage(String beanType, String text, String exception)	Get the localized message to display in a tooltip when a typed in bean name is not a valid name format for creating a bean.
Manager<B>	getManager()
String	getNoMatchingBeanMessage(String beanType, String text)	Get the localized message to display when a typed in bean name does not match a named bean, isValidatingInput() is true and isProviding() is false.
B	getSelectedItem()
String	getSelectedItemDisplayName()	Get the display name of the selected item.
String	getSelectedItemSystemName()	Get the system name of the selected item.
String	getSelectedItemUserName()	Get the user name of the selected item.
String	getWillCreateBeanMessage(String beanType, String text)	Get the localized message to display when a typed in bean name does not match a named bean, isValidatingInput() is true and isProviding() is true.
boolean	isAllowNull()	Is this JComboBox allowing a null object to be selected?
boolean	isProviding()	Check if new NamedBeans can be provided by a ProvidingManager when JComboBox.isEditable returns true.
boolean	isValidatingInput()	Is this JComboBox validating typed input?
void	setAllowNull(boolean allowNull)	Set if this JComboBox allows a null object to be selected.
final void	setDisplayOrder(NamedBean.DisplayOptions displayOrder)
void	setEditable(boolean editable)
void	setExcludedItems(Set<B> excludedItems)	Collection of named beans managed by the manager for this combo box that should not be included in the combo box.
void	setProviding(boolean providing)	Set if new NamedBeans can be provided by a ProvidingManager when JComboBox.isEditable() returns true.
void	setSelectedItem(Object item)
void	setSelectedItemByName(String name)	Set the selected item by either its user name or system name.
void	setValidatingInput(boolean validatingInput)	Set if this JComboBox validates typed input.

Methods inherited from class javax.swing.JComboBox

actionPerformed, actionPropertyChanged, addActionListener, addItem, addItemListener, addPopupMenuListener, configureEditor, configurePropertiesFromAction, contentsChanged, createActionPropertyChangeListener, createDefaultKeySelectionManager, fireActionEvent, fireItemStateChanged, firePopupMenuCanceled, firePopupMenuWillBecomeInvisible, firePopupMenuWillBecomeVisible, getAccessibleContext, getAction, getActionCommand, getActionListeners, getEditor, getItemAt, getItemCount, getItemListeners, getKeySelectionManager, getMaximumRowCount, getModel, getPopupMenuListeners, getPrototypeDisplayValue, getRenderer, getSelectedIndex, getSelectedObjects, getUI, getUIClassID, hidePopup, insertItemAt, installAncestorListener, intervalAdded, intervalRemoved, isEditable, isLightWeightPopupEnabled, isPopupVisible, paramString, processKeyBinding, processKeyEvent, removeActionListener, removeAllItems, removeItem, removeItemAt, removeItemListener, removePopupMenuListener, selectedItemChanged, selectWithKeyChar, setAction, setActionCommand, setEditor, setEnabled, setKeySelectionManager, setLightWeightPopupEnabled, setMaximumRowCount, setModel, setPopupVisible, setPrototypeDisplayValue, setRenderer, setSelectedIndex, setUI, showPopup, updateUI

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, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, 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, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, 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, addImpl, 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, setLayout, 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, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, 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 Details

NamedBeanComboBox

public NamedBeanComboBox(Manager<B> manager)

Create a ComboBox without a selection using the NamedBean.DisplayOptions.DISPLAYNAME to sort NamedBeans.

Parameters:

manager - the Manager backing the ComboBox

NamedBeanComboBox

public NamedBeanComboBox(Manager<B> manager,
 B selection)

Create a ComboBox with an existing selection using the NamedBean.DisplayOptions.DISPLAYNAME to sort NamedBeans.

Parameters:

manager - the Manager backing the ComboBox

selection - the NamedBean that is selected or null to specify no selection

NamedBeanComboBox

public NamedBeanComboBox(Manager<B> manager,
 B selection,
 NamedBean.DisplayOptions displayOrder)

Create a ComboBox with an existing selection using the specified display order to sort NamedBeans.

Parameters:

manager - the Manager backing the ComboBox

selection - the NamedBean that is selected or null to specify no selection

displayOrder - the sorting scheme for NamedBeans

NamedBeanComboBox

public NamedBeanComboBox(Manager<B> manager,
 B selection,
 NamedBean.DisplayOptions displayOrder,
 Predicate<B> filter)

Create a ComboBox with an existing selection using the specified display order to sort NamedBeans.

Parameters:

manager - the Manager backing the ComboBox

selection - the NamedBean that is selected or null to specify no selection

displayOrder - the sorting scheme for NamedBeans

filter - the filter or null if no filter

Method Details

getManager

public Manager<B> getManager()

getDisplayOrder

public NamedBean.DisplayOptions getDisplayOrder()

setDisplayOrder

public final void setDisplayOrder(NamedBean.DisplayOptions displayOrder)

isValidatingInput

public boolean isValidatingInput()

Is this JComboBox validating typed input?

Returns:

true if validating input; false otherwise

setValidatingInput

public void setValidatingInput(boolean validatingInput)

Set if this JComboBox validates typed input.

Parameters:

validatingInput - true to validate; false to prevent validation

isAllowNull

public boolean isAllowNull()

Is this JComboBox allowing a null object to be selected?

Returns:

true if allowing a null selection; false otherwise

setAllowNull

public void setAllowNull(boolean allowNull)

Set if this JComboBox allows a null object to be selected. If so, the null object is placed first in the displayed list of NamedBeans.

Parameters:

allowNull - true if allowing a null selection; false otherwise

getSelectedItem

public B getSelectedItem()

To get the current selection without potentially creating a NamedBean call JComboBox.getItemAt(int) with JComboBox.getSelectedIndex() as the index instead (as in getItemAt(getSelectedIndex())).

Overrides:

getSelectedItem in class JComboBox<B extends NamedBean>

Returns:

the selected item as the supported type of NamedBean, creating a new NamedBean as needed if JComboBox.isEditable() and isProviding() are true, or null if there is no selection, or isAllowNull() is true and the null object is selected

isProviding

public boolean isProviding()

Check if new NamedBeans can be provided by a ProvidingManager when JComboBox.isEditable returns true.

Returns:

true is allowing new NamedBeans to be provided; false otherwise

setProviding

public void setProviding(boolean providing)

Set if new NamedBeans can be provided by a ProvidingManager when JComboBox.isEditable() returns true.

Parameters:

providing - true to allow new NamedBeans to be provided; false otherwise

setEditable

public void setEditable(boolean editable)

Overrides:

setEditable in class JComboBox<B extends NamedBean>

getSelectedItemDisplayName

public String getSelectedItemDisplayName()

Get the display name of the selected item.

Returns:

the display name of the selected item or null if the selected item is null or there is no selection

getSelectedItemSystemName

public String getSelectedItemSystemName()

Get the system name of the selected item.

Returns:

the system name of the selected item or null if the selected item is null or there is no selection

getSelectedItemUserName

public String getSelectedItemUserName()

Get the user name of the selected item.

Returns:

the user name of the selected item or null if the selected item is null or there is no selection

setSelectedItem

public void setSelectedItem(Object item)

Overrides:

setSelectedItem in class JComboBox<B extends NamedBean>

setSelectedItemByName

public void setSelectedItemByName(String name)

Set the selected item by either its user name or system name.

Parameters:

name - the name of the item to select

Throws:

IllegalArgumentException - if isAllowNull() is false and no bean exists by name or name is null

dispose

public void dispose()

getBeanInUseMessage

public String getBeanInUseMessage(String beanType,
 String displayName)

Get the localized message to display in a tooltip when a typed in bean name matches a named bean has been included in a call to setExcludedItems(java.util.Set) and isValidatingInput() is true.

Parameters:

beanType - the type of bean as provided by Manager.getBeanTypeHandled()

displayName - the bean name as provided by NamedBean.getDisplayName(jmri.NamedBean.DisplayOptions) with the options in getDisplayOrder()

Returns:

the localized message

getInvalidNameFormatMessage

public String getInvalidNameFormatMessage(String beanType,
 String text,
 String exception)

Get the localized message to display in a tooltip when a typed in bean name is not a valid name format for creating a bean.

Parameters:

beanType - the type of bean as provided by Manager.getBeanTypeHandled()

text - the typed in name

exception - the localized message text from the exception thrown by Manager.validateSystemNameFormat(java.lang.String, java.util.Locale)

Returns:

the localized message

getNoMatchingBeanMessage

public String getNoMatchingBeanMessage(String beanType,
 String text)

Get the localized message to display when a typed in bean name does not match a named bean, isValidatingInput() is true and isProviding() is false.

Parameters:

beanType - the type of bean as provided by Manager.getBeanTypeHandled()

text - the typed in name

Returns:

the localized message

getWillCreateBeanMessage

public String getWillCreateBeanMessage(String beanType,
 String text)

Get the localized message to display when a typed in bean name does not match a named bean, isValidatingInput() is true and isProviding() is true.

Parameters:

beanType - the type of bean as provided by Manager.getBeanTypeHandled()

text - the typed in name

Returns:

the localized message

getExcludedItems

public Set<B> getExcludedItems()

setExcludedItems

public void setExcludedItems(Set<B> excludedItems)

Collection of named beans managed by the manager for this combo box that should not be included in the combo box. This may be, for example, a list of SignalHeads already in use, and therefor not available to be added to a SignalMast.

Parameters:

excludedItems - items to be excluded from this combo box