org.tentackle.ui
Class FormComboBox

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JComboBox
                  org.tentackle.ui.FormComboBox

All Implemented Interfaces:

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

Direct Known Subclasses:

FormFieldComboBox, LocaleComboBox, PermissionComboBox

public class FormComboBox
extends JComboBox
implements FormComponent, FocusListener

A forms-aware combobox.
Notes:

1. If valueEnteredOnSelect is set to false the valueEntered event will only be fired on focus lost and not whenever the selection is changed.
2. the action event behave as expected, i.e. fired on each ENTER
3. due to the data binding there is a decent separation of the "selected item" and the "contents" of the editor field. To get the contents, i.e. the "real value", applications should use getFormValue. To get only the current selected object use getSelectedItem.
4. As opposed to JComboBox getSelectedItem is guaranteed to be null if getSelectedIndex is -1.
5. For editable comboboxes applications should use FormFieldComboBox.

Author:

harald

See Also:

Serialized Form

Nested Class Summary

class

FormComboBox.MultiKeySelectionManager The standard key selection manager selects the first item that starts with a given character. This MultiKeySelectionManager keeps an internal "lead-string" of possibly more than one char.

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

accessibleContext, 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

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

FormComboBox()
Creates a FormComboBox with a default data model.

FormComboBox(ComboBoxModel model)
Creates a FormComboBox that takes its items from an existing ComboBoxModel.

FormComboBox(Object[] items)
Creates a FormComboBox that contains the elements in the specified array.

Method Summary

void	actionPerformed(ActionEvent e) Overridden to do nothing!
void	addAllItems(Collection items) Adds a collection of items to the list of objects.
void	addAllItems(Object[] items) Adds an array of items to the list of objects.
void	addItem(Object anObject) Adds an item to the item list.
void	addValueListener(ValueListener listener) Adds a value listener that implements the binding between this component and the data.
protected void	fireActionEvent() Overridden for the reason of actionEvents not being triggered by setFormValue().
void	fireValueChanged() Fires all value listeners registered on this component invoking their valueChanged-handler. This method is invoked whenever the data has been changed and that change should be reflected in the view.
void	fireValueEntered() Fires all listeners registered on this component invoking their valueEntered-handler. This method is invoked whenever the user edited the view and that change should be reflected in the data.
void	focusGained(FocusEvent e) Invoked when a component gains the keyboard focus.
void	focusLost(FocusEvent e) Invoked when a component loses the keyboard focus.
Object[]	getAllItems() Gets the current array of items.
Object	getFormValue() Retrieves the value from this component. The method is used to update the data if the view has changed because the user edited it.
String	getFormValueText() Gets the text representation of the current selection.
String	getHelpURL() Gets the online-help URL.
int	getItemIndexWithLeadString(String lead, ComboBoxModel model) Returns the index of the first/best matching selection according to a string
long	getLeadKeyTimeout() Gets the timeout for multi key selections.
Window	getParentWindow() Gets the parent window of this component.
ListCellRenderer	getPopupRenderer() Gets the popup renderer.
String	getToolTipText() Returns the tooltip string that has been set with setToolTipText.
void	invalidateParentInfo() Invalidates all container-relevant (cached) information for the hierarchy of this component's parents. For optimization purposes.
boolean	isAllowDeselect() Returns the eselect feature for non-editable comboboxes
boolean	isCellEditorUsage() Returns whether this component is used as a cell editor.
boolean	isChangeable() Returns if this component is changeable.
boolean	isFireRunning() Checks whether a fire-method is running.
boolean	isFormTraversable() Returns whether this component is form traversable or not.
boolean	isHonourChangeable() Returns whether this component should honour the changeable-attribute or not.
boolean	isMultiKeySelectionManager() Returns whether multi-key selection is enabled.
boolean	isShortLongPopupEnabled() Returns whether short/long text popup renderer enabled.
boolean	isValueAdjusting() Returns whether currently adjusting the value.
boolean	isValueChanged() Checks whether the contents have been changed since the last savepoint.
boolean	isValueEnteredOnSelect() Returns whether valueEntered is fired on select or focus lost (default).
void	prepareFocusLost() Implemented to do nothing!
void	processKeyEvent(KeyEvent e) Handles KeyEvents, looking for the Tab key.
void	removeAllItems() Removes all items from the item list.
void	removeValueListener(ValueListener listener) Remove a value listener.
void	requestFocusLater() Requests the keyboard focus for this component by appending an event to the end of the event queue. Applications should not use requestFocus() or requestFocusInWindow() unless the order in which the events are processed is unimportant.
void	saveValue() Sets a savepoint for the data of this component. Allows to decide whether the user has changed the data associated with this component or not.
boolean	selectWithLeadString(String lead) Selects the list item that best corresponds to the specified String and returns true, if there is an item corresponding to that lead-string.
void	setAllItems(Collection items) Replaces all items by a collection of objects.
void	setAllItems(Object[] items) Replaces all items by an array of objects.
void	setAllowDeselect(boolean allowDeselect) Deselect feature for non-editable comboboxes
void	setCellEditorUsage(boolean flag) Sets a hint that this component is used as a cell editor. Some components behave differently in tables than in forms, for example.
void	setChangeable(boolean changeable) Set the component to be changeable. This is a unified abstraction and will be translated to setEditable or setEnabled, whatever is appropriate to this component.
void	setEditable(boolean editable) Determines whether the JComboBox field is editable.
void	setFireRunning(boolean running) Sets a component's flag that a fire-method is currently running. Used by the framework to minimize valueChanged/valueEntered processing.
void	setFormTraversable(boolean formTraversable) Sets whether this component is form traversable or not, i.e.
void	setFormValue(Object item) Sets a value in this component. The method is used to update the view if the data has changed.
void	setFormValueIndex(int index) Sets the formvalue by its index. Avoids triggering fireValueEntered if used from application (use instead of setSelectedIndex())
boolean	setFormValueText(String text) Sets the form value by matching a given text with the objects in the selection list Tries to find the value in the object list according to its String-representation and select it if found.
void	setFormWrapWindow(FormWindow parent) Sets the window that will fire a FormWrapEvent when this components loses the keyboard focus.
void	setHelpURL(String helpURL) Sets the online-help URL. If a help url is set for this component, a browser will be launched to show that url.
void	setHonourChangeable(boolean flag) Sets whether this component should honour the changeable-attribute or not. The default is true.
void	setLeadKeyTimeout(long leadKeyTimeout) Sets the timeout for multi key selections.
void	setMultiKeySelectionManager(boolean flag) Enables multi-key selection. The default implementation installs the FormComboBox.MultiKeySelectionManager.
void	setPopupRenderer(ListCellRenderer aRenderer) Set the popup renderer. By default, a JComboBox uses the same renderer for rendering the combobox itself (the selected item in the arrowButton).
void	setShortLongPopupEnabled(boolean flag) Enable the special ShortLongText popup renderer. A special popupRenderer is implemented in the tentackle-plaf that supports ShortLongText-objects for a two-column popup-List.
void	setValueAdjusting(boolean flag) sets a flag that we are currently adjusting a value and no fireValueEntered-Events should be triggered
void	setValueEnteredOnSelect(boolean flag) Enables firing a valueEntered-Event *instead* of an actionEvent (avoids registering value- and actionEvent) The default is to fire actionEvents for selection changes and valueEvents for leaving the field (i.e.
void	showHelp() Displays online help for this component. Usually triggered by KeyEvent.VK_F1 or VK_HELP or a button.
void	transferFocus() Transfers the focus to the next component, as though this Component were the focus owner.
void	transferFocusBackward() Transfers the focus to the previous component, as though this Component were the focus owner.
void	triggerValueChanged() Promotes the fact that value changed to all FormContainers this component is a child of.
boolean	wasFocusGainedFromTransfer() Returns whether the keyboard focus was gained due to FormComponent.transferFocus() in the opposite component.
boolean	wasFocusGainedFromTransferBackward() Returns whether the keyboard focus was gained due to FormComponent.transferFocusBackward() in the opposite component.
boolean	wasTransferFocus() Returns whether this component lost the keyboard focus due to FormComponent.transferFocus().
boolean	wasTransferFocusBackward() Returns whether this component lost the keyboard focus due to FormComponent.transferFocusBackward().
boolean	wasTransferFocusByEnter() Returns whether this component lost the keyboard focus due to KeyEvent.VK_ENTER.

Methods inherited from class javax.swing.JComboBox

actionPropertyChanged, addActionListener, addItemListener, addPopupMenuListener, configureEditor, configurePropertiesFromAction, contentsChanged, createActionPropertyChangeListener, createDefaultKeySelectionManager, fireItemStateChanged, firePopupMenuCanceled, firePopupMenuWillBecomeInvisible, firePopupMenuWillBecomeVisible, getAccessibleContext, getAction, getActionCommand, getActionListeners, getEditor, getItemAt, getItemCount, getItemListeners, getKeySelectionManager, getMaximumRowCount, getModel, getPopupMenuListeners, getPrototypeDisplayValue, getRenderer, getSelectedIndex, getSelectedItem, getSelectedObjects, getUI, getUIClassID, hidePopup, insertItemAt, installAncestorListener, intervalAdded, intervalRemoved, isEditable, isLightWeightPopupEnabled, isPopupVisible, paramString, removeActionListener, removeItem, removeItemAt, removeItemListener, removePopupMenuListener, selectedItemChanged, selectWithKeyChar, setAction, setActionCommand, setEditor, setEnabled, setKeySelectionManager, setLightWeightPopupEnabled, setMaximumRowCount, setModel, setPopupVisible, setPrototypeDisplayValue, setRenderer, setSelectedIndex, setSelectedItem, 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, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, 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, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, 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, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.tentackle.ui.FormComponent

hasFocus

Constructor Detail

FormComboBox

public FormComboBox(ComboBoxModel model)

Creates a FormComboBox that takes its items from an existing ComboBoxModel. Since the ComboBoxModel is provided, a combo box created using this constructor does not create a default combo box model and may impact how the insert, remove and add methods behave.

Parameters:

model - the ComboBoxModel that provides the displayed list of items

See Also:

JComboBox.JComboBox(javax.swing.ComboBoxModel)

FormComboBox

public FormComboBox(Object[] items)

Creates a FormComboBox that contains the elements in the specified array. By default the first item in the array (and therefore the data model) becomes selected.

Parameters:

items - an array of objects to insert into the combo box

See Also:

JComboBox.JComboBox(java.lang.Object[])

FormComboBox

public FormComboBox()

Creates a FormComboBox with a default data model. The default data model is an empty list of objects. Use addItem to add items.

See Also:

JComboBox.JComboBox()

Method Detail

processKeyEvent

public void processKeyEvent(KeyEvent e)

Handles KeyEvents, looking for the Tab key. If the Tab key is found, the popup window is closed.

Overridden for keyboard shortcuts.

Overrides:

processKeyEvent in class JComboBox

Parameters:

e - the KeyEvent containing the keyboard key that was pressed

See Also:

KeyEvent, KeyListener, KeyboardFocusManager, DefaultKeyboardFocusManager, Component.processEvent(java.awt.AWTEvent), Component.dispatchEvent(java.awt.AWTEvent), Component.addKeyListener(java.awt.event.KeyListener), Component.enableEvents(long), Component.isShowing()

actionPerformed

public void actionPerformed(ActionEvent e)

Overridden to do nothing!

Reason: pressing ENTER in editable comboboxes would store the "text" of the editorfield into the selectedItem. We don't need this nonsense because FormComboBoxes are able to distinguish between the text-value and the selected object due the data binding via valueListeners.

Specified by:

actionPerformed in interface ActionListener

Overrides:

actionPerformed in class JComboBox

Parameters:

e - the action event

See Also:

fireActionEvent()

fireActionEvent

protected void fireActionEvent()

Overridden for the reason of actionEvents not being triggered by setFormValue(). ActionEvents will *ONLY* be triggered due to a selection in the pulldown-menu!

Overrides:

fireActionEvent in class JComboBox

See Also:

actionPerformed(java.awt.event.ActionEvent)

setEditable

public void setEditable(boolean editable)

Determines whether the JComboBox field is editable. An editable JComboBox allows the user to type into the field or selected an item from the list to initialize the field, after which it can be edited. (The editing affects only the field, the list item remains intact.) A non editable JComboBox displays the selected item in the field, but the selection cannot be modified.

Overridden due to focus handling

Overrides:

setEditable in class JComboBox

Parameters:

editable - true if combobox is editable

setFormValueText

public boolean setFormValueText(String text)

Sets the form value by matching a given text with the objects in the selection list
Tries to find the value in the object list according to its String-representation and select it if found. if no match found: just clear selectedItem but don't change contents of editor!

Parameters:

text - the string to match

Returns:

true if some object selected, false if no such object

getFormValueText

public String getFormValueText()

Gets the text representation of the current selection.

Returns:

the String value of the selection, null = nothing selected

setFormValueIndex

public void setFormValueIndex(int index)

Sets the formvalue by its index.
Avoids triggering fireValueEntered if used from application (use instead of setSelectedIndex())

Parameters:

index - the object index, -1 to deselect

addAllItems

public void addAllItems(Object[] items)

Adds an array of items to the list of objects.

Parameters:

items - the array of items to add

addAllItems

public void addAllItems(Collection items)

Adds a collection of items to the list of objects.

Parameters:

items - the collection of items to add

setAllItems

public void setAllItems(Object[] items)

Replaces all items by an array of objects.

Parameters:

items - the array of items

setAllItems

public void setAllItems(Collection items)

Replaces all items by a collection of objects.

Parameters:

items - the collection of items

getAllItems

public Object[] getAllItems()

Gets the current array of items.

Returns:

the array of items (never null)

removeAllItems

public void removeAllItems()

Removes all items from the item list.

Overridden to turn off annoying actionEvents during updates

Overrides:

removeAllItems in class JComboBox

addItem

public void addItem(Object anObject)

Adds an item to the item list. This method works only if the JComboBox uses a mutable data model.

Warning: Focus and keyboard navigation problems may arise if you add duplicate String objects. A workaround is to add new objects instead of String objects and make sure that the toString() method is defined. For example:

   comboBox.addItem(makeObj("Item 1"));
   comboBox.addItem(makeObj("Item 1"));
   ...
   private Object makeObj(final String item)  {
     return new Object() { public String toString() { return item; } };
   }
 

Overridden to turn off annoying actionEvents during updates

Overrides:

addItem in class JComboBox

Parameters:

anObject - the Object to add to the list

See Also:

MutableComboBoxModel

setValueEnteredOnSelect

public void setValueEnteredOnSelect(boolean flag)

Enables firing a valueEntered-Event *instead* of an actionEvent (avoids registering value- and actionEvent) The default is to fire actionEvents for selection changes and valueEvents for leaving the field (i.e. as in FormFields)

Parameters:

flag - true to fire on select, false only on focus lost

isValueEnteredOnSelect

public boolean isValueEnteredOnSelect()

Returns whether valueEntered is fired on select or focus lost (default).

Returns:

true if on select, else focus lost

setValueAdjusting

public void setValueAdjusting(boolean flag)

sets a flag that we are currently adjusting a value and no fireValueEntered-Events should be triggered

Parameters:

flag - true if is adjusting

isValueAdjusting

public boolean isValueAdjusting()

Returns whether currently adjusting the value.

Returns:

true if adjusting

selectWithLeadString

public boolean selectWithLeadString(String lead)

Selects the list item that best corresponds to the specified String and returns true, if there is an item corresponding to that lead-string. Otherwise, returns false.

Parameters:

lead - the first chars types by user

Returns:

true if selected, false if no object matches

getItemIndexWithLeadString

public int getItemIndexWithLeadString(String lead,
                                      ComboBoxModel model)

Returns the index of the first/best matching selection according to a string

Parameters:

lead - the first chars types by user

model - the data model

Returns:

the index, -1 if no match

setMultiKeySelectionManager

public void setMultiKeySelectionManager(boolean flag)

Enables multi-key selection.
The default implementation installs the FormComboBox.MultiKeySelectionManager.

Parameters:

flag - true to enable multi key selection.

isMultiKeySelectionManager

public boolean isMultiKeySelectionManager()

Returns whether multi-key selection is enabled.

Returns:

true if enabled

getLeadKeyTimeout

public long getLeadKeyTimeout()

Gets the timeout for multi key selections.

Returns:

the timeout in ms (default is 1000).

setLeadKeyTimeout

public void setLeadKeyTimeout(long leadKeyTimeout)

Sets the timeout for multi key selections.

Parameters:

leadKeyTimeout - the timeout in ms

isAllowDeselect

public boolean isAllowDeselect()

Returns the eselect feature for non-editable comboboxes

Returns:

true if backspace/delete deselects (default), false = ignore keys

setAllowDeselect

public void setAllowDeselect(boolean allowDeselect)

Deselect feature for non-editable comboboxes

Parameters:

allowDeselect - true if backspace/delete deselects (default), false = ignore keys

setPopupRenderer

public void setPopupRenderer(ListCellRenderer aRenderer)

Set the popup renderer.
By default, a JComboBox uses the same renderer for rendering the combobox itself (the selected item in the arrowButton). However, if popupRenderer is set explicitly (null by default) the popup's JList uses the popupRenderer which may show some extra info to the user.

Notice that this attribute will only be honoured if one of the tentackle plafs are used.

Parameters:

aRenderer - the popup renderer, null to disable

getPopupRenderer

public ListCellRenderer getPopupRenderer()

Gets the popup renderer.

Returns:

the popup renderer, null if disabled

setShortLongPopupEnabled

public void setShortLongPopupEnabled(boolean flag)

Enable the special ShortLongText popup renderer.
A special popupRenderer is implemented in the tentackle-plaf that supports ShortLongText-objects for a two-column popup-List. This is a very common case, where the combobox-value corresponds to a short text and the popup contains the short text and a longer description in a second column.

Parameters:

flag - true if enable short/long text popup renderer

isShortLongPopupEnabled

public boolean isShortLongPopupEnabled()

Returns whether short/long text popup renderer enabled.

Returns:

true if enabled

focusGained

public void focusGained(FocusEvent e)

Description copied from interface: java.awt.event.FocusListener

Invoked when a component gains the keyboard focus.

Specified by:

focusGained in interface FocusListener

focusLost

public void focusLost(FocusEvent e)

Description copied from interface: java.awt.event.FocusListener

Invoked when a component loses the keyboard focus.

Specified by:

focusLost in interface FocusListener

requestFocusLater

public void requestFocusLater()

Description copied from interface: FormComponent

Requests the keyboard focus for this component by appending an event to the end of the event queue.
Applications should not use requestFocus() or requestFocusInWindow() unless the order in which the events are processed is unimportant. This method guarantees that this component gets the focus when all events queued so far have been processed.

Specified by:

requestFocusLater in interface FormComponent

addValueListener

public void addValueListener(ValueListener listener)

Description copied from interface: FormComponent

Adds a value listener that implements the binding between this component and the data.

Specified by:

addValueListener in interface FormComponent

Parameters:

listener - the value listener to add

removeValueListener

public void removeValueListener(ValueListener listener)

Description copied from interface: FormComponent

Remove a value listener.

Specified by:

removeValueListener in interface FormComponent

Parameters:

listener - the value listener to remove

fireValueChanged

public void fireValueChanged()

Description copied from interface: FormComponent

Fires all value listeners registered on this component invoking their valueChanged-handler.
This method is invoked whenever the data has been changed and that change should be reflected in the view.

Specified by:

fireValueChanged in interface FormComponent

fireValueEntered

public void fireValueEntered()

Fires all listeners registered on this component invoking their valueEntered-handler.
This method is invoked whenever the user edited the view and that change should be reflected in the data.

note: valueEntered will *ONLY* be fired if the last actionEvent did not fire for the same selectedItem (see fireActionEvent)

Specified by:

fireValueEntered in interface FormComponent

setFormValue

public void setFormValue(Object item)

Sets a value in this component.
The method is used to update the view if the data has changed.

Notice: this will compare the objects by "equals" as opposed to setSelectedItem()!

Specified by:

setFormValue in interface FormComponent

Parameters:

item - is the object to set, null means deselect

getFormValue

public Object getFormValue()

Retrieves the value from this component.
The method is used to update the data if the view has changed because the user edited it.

Notice: if the combobox is editable the value will be read from the editor field. Otherwise it's read from the selected item.

Specified by:

getFormValue in interface FormComponent

Returns:

the object from the form

saveValue

public void saveValue()

Description copied from interface: FormComponent

Sets a savepoint for the data of this component.
Allows to decide whether the user has changed the data associated with this component or not.

Specified by:

saveValue in interface FormComponent

See Also:

FormComponent.isValueChanged()

isValueChanged

public boolean isValueChanged()

Description copied from interface: FormComponent

Checks whether the contents have been changed since the last savepoint.

Specified by:

isValueChanged in interface FormComponent

Returns:

true if changed

See Also:

FormComponent.saveValue()

triggerValueChanged

public void triggerValueChanged()

Description copied from interface: FormComponent

Promotes the fact that value changed to all FormContainers this component is a child of.

Specified by:

triggerValueChanged in interface FormComponent

setChangeable

public void setChangeable(boolean changeable)

Set the component to be changeable.
This is a unified abstraction and will be translated to setEditable or setEnabled, whatever is appropriate to this component.

Translated to enabled.

Specified by:

setChangeable in interface FormComponent

Parameters:

changeable - true the user can edit the data, false if show only

isChangeable

public boolean isChangeable()

Description copied from interface: FormComponent

Returns if this component is changeable.

Specified by:

isChangeable in interface FormComponent

Returns:

true the user can edit the data, false if show only

setHonourChangeable

public void setHonourChangeable(boolean flag)

Description copied from interface: FormComponent

Sets whether this component should honour the changeable-attribute or not.
The default is true. Notice: if this component does not honour the changeable flag, isValueChanged() always returns false and it will not perform any saveValue().

Specified by:

setHonourChangeable in interface FormComponent

Parameters:

flag - true if honour the changeable attribute, false if not

isHonourChangeable

public boolean isHonourChangeable()

Description copied from interface: FormComponent

Returns whether this component should honour the changeable-attribute or not.

Specified by:

isHonourChangeable in interface FormComponent

Returns:

true if honour the changeable attribute, false if not

setFireRunning

public void setFireRunning(boolean running)

Description copied from interface: FormComponent

Sets a component's flag that a fire-method is currently running.
Used by the framework to minimize valueChanged/valueEntered processing.

Specified by:

setFireRunning in interface FormComponent

Parameters:

running - true if some fire-method is running

isFireRunning

public boolean isFireRunning()

Description copied from interface: FormComponent

Checks whether a fire-method is running.

Specified by:

isFireRunning in interface FormComponent

Returns:

true if some fire-method is running

setCellEditorUsage

public void setCellEditorUsage(boolean flag)

Description copied from interface: FormComponent

Sets a hint that this component is used as a cell editor.
Some components behave differently in tables than in forms, for example.

Specified by:

setCellEditorUsage in interface FormComponent

Parameters:

flag - true if component is a cell editor, false if not.

isCellEditorUsage

public boolean isCellEditorUsage()

Description copied from interface: FormComponent

Returns whether this component is used as a cell editor.

Specified by:

isCellEditorUsage in interface FormComponent

Returns:

true true if component is a cell editor, false if not.

prepareFocusLost

public void prepareFocusLost()

Implemented to do nothing!

Specified by:

prepareFocusLost in interface FormComponent

setFormWrapWindow

public void setFormWrapWindow(FormWindow parent)

Description copied from interface: FormComponent

Sets the window that will fire a FormWrapEvent when this components loses the keyboard focus. When fired the reference to the window is cleared.

Specified by:

setFormWrapWindow in interface FormComponent

Parameters:

parent - the window (usually the parent window of this component).

getHelpURL

public String getHelpURL()

Description copied from interface: FormComponent

Gets the online-help URL.

Specified by:

getHelpURL in interface FormComponent

Returns:

the help url, default is null

setHelpURL

public void setHelpURL(String helpURL)

Description copied from interface: FormComponent

Sets the online-help URL.
If a help url is set for this component, a browser will be launched to show that url. If there is no url the next higher level container will determine the url, and so forth.

Specified by:

setHelpURL in interface FormComponent

Parameters:

helpURL - the help url

See Also:

FormHelper.openHelpURL(Component)

showHelp

public void showHelp()

Description copied from interface: FormComponent

Displays online help for this component.
Usually triggered by KeyEvent.VK_F1 or VK_HELP or a button. If help is not configured for this component, the parent's help is used.

Specified by:

showHelp in interface FormComponent

getParentWindow

public Window getParentWindow()

Description copied from interface: FormComponent

Gets the parent window of this component.

Specified by:

getParentWindow in interface FormComponent

Returns:

the parent window, null if none

invalidateParentInfo

public void invalidateParentInfo()

Description copied from interface: FormComponent

Invalidates all container-relevant (cached) information for the hierarchy of this component's parents.
For optimization purposes.

Specified by:

invalidateParentInfo in interface FormComponent

getToolTipText

public String getToolTipText()

Description copied from class: javax.swing.JComponent

Returns the tooltip string that has been set with setToolTipText.

Overrides:

getToolTipText in class JComponent

Returns:

the text of the tool tip

See Also:

JComponent.TOOL_TIP_TEXT_KEY

transferFocus

public void transferFocus()

Description copied from class: java.awt.Component

Transfers the focus to the next component, as though this Component were the focus owner.

Specified by:

transferFocus in interface FormComponent

Overrides:

transferFocus in class Component

See Also:

Component.requestFocus()

transferFocusBackward

public void transferFocusBackward()

Description copied from class: java.awt.Component

Transfers the focus to the previous component, as though this Component were the focus owner.

Specified by:

transferFocusBackward in interface FormComponent

Overrides:

transferFocusBackward in class Container

See Also:

Component.requestFocus()

wasTransferFocus

public boolean wasTransferFocus()

Description copied from interface: FormComponent

Returns whether this component lost the keyboard focus due to FormComponent.transferFocus().

Specified by:

wasTransferFocus in interface FormComponent

Returns:

true if focus lost due to transferFocus

wasTransferFocusBackward

public boolean wasTransferFocusBackward()

Description copied from interface: FormComponent

Returns whether this component lost the keyboard focus due to FormComponent.transferFocusBackward().

Specified by:

wasTransferFocusBackward in interface FormComponent

Returns:

true if focus lost due to transferFocusBackward

wasFocusGainedFromTransfer

public boolean wasFocusGainedFromTransfer()

Description copied from interface: FormComponent

Returns whether the keyboard focus was gained due to FormComponent.transferFocus() in the opposite component.

Specified by:

wasFocusGainedFromTransfer in interface FormComponent

Returns:

true if this component gained the focus from the logically previous component

See Also:

FormFocusTraversalPolicy

wasFocusGainedFromTransferBackward

public boolean wasFocusGainedFromTransferBackward()

Description copied from interface: FormComponent

Returns whether the keyboard focus was gained due to FormComponent.transferFocusBackward() in the opposite component.

Specified by:

wasFocusGainedFromTransferBackward in interface FormComponent

Returns:

true if this component gained the focus from the logically next component

See Also:

FormFocusTraversalPolicy

wasTransferFocusByEnter

public boolean wasTransferFocusByEnter()

Description copied from interface: FormComponent

Returns whether this component lost the keyboard focus due to KeyEvent.VK_ENTER.

Specified by:

wasTransferFocusByEnter in interface FormComponent

Returns:

true if pressing the Enter/Return key caused a focus lost

setFormTraversable

public void setFormTraversable(boolean formTraversable)

Description copied from interface: FormComponent

Sets whether this component is form traversable or not, i.e. gets the focus or is skipped.

Specified by:

setFormTraversable in interface FormComponent

Parameters:

formTraversable - true if traversable, false if not

isFormTraversable

public boolean isFormTraversable()

Description copied from interface: FormComponent

Returns whether this component is form traversable or not.

Specified by:

isFormTraversable in interface FormComponent

Returns:

the focus traversable flag