org.eclipse.nebula.widgets.nattable.widget

Class NatCombo

java.lang.Object

org.eclipse.swt.widgets.Widget

org.eclipse.swt.widgets.Control

org.eclipse.swt.widgets.Scrollable

org.eclipse.swt.widgets.Composite

org.eclipse.nebula.widgets.nattable.widget.NatCombo

All Implemented Interfaces:

org.eclipse.swt.graphics.Drawable

Direct Known Subclasses:

FilterNatCombo

public class NatCombo
extends org.eclipse.swt.widgets.Composite

Customized combobox control that supports editing directly in the text field and selecting items from the dropdown.

This control supports the ability for multi select in the dropdown of the combo which is not available for the SWT Combo control. This feature was added with Nebula NatTable 1.0.0

The following style bits are supported by this control.

See Also:

(if a border should be added to the Text control), (default for Text control, if this is missing, the Text control can be edited), (if the items in the combo should be showed with checkboxes), (if multi selection is allowed)

Field Summary

Fields

Modifier and Type	Field and Description
protected IStyle	cellStyle The IStyle that is used for rendering the Text and the combo control.
static String	DEFAULT_MULTI_SELECT_PREFIX Default String that is used to prefix the generated String representation showed in the text control if multiselect is supported.
static String	DEFAULT_MULTI_SELECT_SUFFIX String that is used to suffix the generated String representation showed in the text control if multiselect is supported.
static String	DEFAULT_MULTI_SELECT_VALUE_SEPARATOR Default String that is used to separate values in the String representation showed in the text control if multiselect is supported.
static int	DEFAULT_NUM_OF_VISIBLE_ITEMS The default number of visible items on open the combo.
protected org.eclipse.swt.widgets.Shell	dropdownShell The Shell containing the dropdown of this NatCombo
protected org.eclipse.swt.widgets.Table	dropdownTable The Table control used for the combo component of this NatCombo
protected boolean	freeEdit Flag that indicates whether this ComboBoxCellEditor supports free editing in the text control of the NatCombo or not.
protected org.eclipse.swt.graphics.Image	iconImage The image that is shown at the right edge of the text control if the NatCombo is opened.
protected List<String>	itemList The items that are showed within the combo transformed to a java.util.List.
protected int	maxVisibleItems The maximum number of visible items of the combo.
protected boolean	multiselect Flag that indicates whether this NatCombo supports multiselect or not.
protected String	multiselectTextPrefix String that is used to prefix the generated String representation showed in the text control if multiselect is supported.
protected String	multiselectTextSuffix String that is used to suffix the generated String representation showed in the text control if multiselect is supported.
protected String	multiselectValueSeparator String that is used to separate values in the String representation showed in the text control if multiselect is supported.
protected int	style The style bits that where set on creation time.
protected org.eclipse.swt.widgets.Text	text The text control of this NatCombo, allowing to enter values directly.
protected boolean	useCheckbox Flag that indicates whether checkboxes should be shown for the items in the dropdown.

Fields inherited from class org.eclipse.swt.widgets.Control

handle

Constructor Summary

Constructors

Constructor and Description
NatCombo(org.eclipse.swt.widgets.Composite parent, IStyle cellStyle, int style) Creates a new NatCombo using the given IStyle for rendering, showing the default number of items at once in the dropdown.
NatCombo(org.eclipse.swt.widgets.Composite parent, IStyle cellStyle, int maxVisibleItems, int style) Creates a new NatCombo using the given IStyle for rendering, showing the given amount of items at once in the dropdown.
NatCombo(org.eclipse.swt.widgets.Composite parent, IStyle cellStyle, int maxVisibleItems, int style, org.eclipse.swt.graphics.Image iconImage) Creates a new NatCombo using the given IStyle for rendering, showing the given amount of items at once in the dropdown.

Method Summary

Methods

Modifier and Type	Method and Description
void	addKeyListener(org.eclipse.swt.events.KeyListener listener)
void	addMouseListener(org.eclipse.swt.events.MouseListener listener)
void	addSelectionListener(org.eclipse.swt.events.SelectionListener listener)
void	addShellListener(org.eclipse.swt.events.ShellListener listener)
void	addTraverseListener(org.eclipse.swt.events.TraverseListener listener)
protected void	calculateBounds() Calculates the size and location of the Shell that represents the dropdown control of this NatCombo.
protected void	createDropdownControl(int style) Create the dropdown control of this NatCombo, adding styles, look&feel and needed listeners for the control only.
protected void	createTextControl(int style) Creates the Text control of this NatCombo, adding styles, look&feel and needed listeners for the control only.
void	dispose()
String[]	getSelection() Returns an array of Strings that are currently selected in the receiver.
int	getSelectionCount() Returns the number of selected items contained in the receiver.
int	getSelectionIndex() Returns the zero-relative index of the item which is currently selected in the receiver, or -1 if no item is selected.
int[]	getSelectionIndices() Returns the zero-relative indices of the items which are currently selected in the receiver.
protected String[]	getTextAsArray() Will transform the text for the Text control of this NatCombo to an array of Strings.
protected String[]	getTransformedSelection() Transforms the selection in the Table control dropdown into a String[].
protected String	getTransformedText(String[] values) Transforms the given array of Strings to a text representation that can be added to the text control of this combo.
protected String	getTransformedTextForSelection() Transforms the selection of the dropdown to a text representation that can be added to the text control of this combo.
protected int	getVisibleItemCount() Calculates the number of items that should be showed in the dropdown at once.
void	hideDropdownControl() Hide the dropdown of this NatCombo.
void	notifyListeners(int eventType, org.eclipse.swt.widgets.Event event)
void	select(int index) Selects the item at the given zero-relative index in the receiver's list.
void	select(int[] indeces) Selects the items at the given zero-relative indices in the receiver.
protected void	setDropdownSelection(String[] selection) Transforms the given String array whose contents represents selected items to a selection that can be handled by the underlying Table control in the dropdown.
void	setItems(String[] items) Sets the given items to be the items shown in the dropdown of this NatCombo.
void	setMultiselectTextBracket(String multiselectTextPrefix, String multiselectTextSuffix) Set the prefix and suffix that will parenthesize the text that is created out of the selected values if this NatCombo supports multiselection.
void	setMultiselectValueSeparator(String multiselectValueSeparator)
void	setSelection(String[] items) Selects the items at the given zero-relative indices in the receiver.
void	showDropdownControl() Shows the dropdown of this NatCombo.
void	showDropdownControl(boolean focusOnText) Shows the dropdown of this NatCombo.
protected void	updateTextControl(boolean hideDropdown) This method will be called if an item of the dropdown control is selected via mouse click or pressing enter.

Methods inherited from class org.eclipse.swt.widgets.Composite

changed, checkSubclass, computeSize, getBackgroundMode, getChildren, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, setBackgroundMode, setFocus, setLayout, setLayoutDeferred, setTabList

Methods inherited from class org.eclipse.swt.widgets.Scrollable

computeTrim, getClientArea, getHorizontalBar, getVerticalBar

Methods inherited from class org.eclipse.swt.widgets.Control

addControlListener, addDragDetectListener, addFocusListener, addHelpListener, addMenuDetectListener, addMouseMoveListener, addMouseTrackListener, addMouseWheelListener, addPaintListener, computeSize, dragDetect, dragDetect, forceFocus, getAccessible, getBackground, getBackgroundImage, getBorderWidth, getBounds, getCursor, getDragDetect, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getMonitor, getParent, getRegion, getShell, getSize, getToolTipText, getVisible, internal_dispose_GC, internal_new_GC, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, print, redraw, redraw, removeControlListener, removeDragDetectListener, removeFocusListener, removeHelpListener, removeKeyListener, removeMenuDetectListener, removeMouseListener, removeMouseMoveListener, removeMouseTrackListener, removeMouseWheelListener, removePaintListener, removeTraverseListener, setBackground, setBackgroundImage, setBounds, setBounds, setCapture, setCursor, setDragDetect, setEnabled, setFont, setForeground, setLayoutData, setLocation, setLocation, setMenu, setParent, setRedraw, setRegion, setSize, setSize, setToolTipText, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, update

Methods inherited from class org.eclipse.swt.widgets.Widget

addDisposeListener, addListener, checkWidget, getData, getData, getDisplay, getListeners, getStyle, isDisposed, isListening, removeDisposeListener, removeListener, removeListener, setData, setData, toString

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MULTI_SELECT_VALUE_SEPARATOR

public static final String DEFAULT_MULTI_SELECT_VALUE_SEPARATOR

Default String that is used to separate values in the String representation showed in the text control if multiselect is supported.

See Also:

Constant Field Values

DEFAULT_MULTI_SELECT_PREFIX

public static final String DEFAULT_MULTI_SELECT_PREFIX

Default String that is used to prefix the generated String representation showed in the text control if multiselect is supported.

See Also:

Constant Field Values

DEFAULT_MULTI_SELECT_SUFFIX

public static final String DEFAULT_MULTI_SELECT_SUFFIX

String that is used to suffix the generated String representation showed in the text control if multiselect is supported.

See Also:

Constant Field Values

DEFAULT_NUM_OF_VISIBLE_ITEMS

public static final int DEFAULT_NUM_OF_VISIBLE_ITEMS

The default number of visible items on open the combo.

See Also:

Constant Field Values

cellStyle

protected final IStyle cellStyle

The IStyle that is used for rendering the Text and the combo control. The important configurations used are horizontal alignment, background and foreground color and font.

maxVisibleItems

protected int maxVisibleItems

The maximum number of visible items of the combo. Setting this value to -1 will result in always showing all items at once.

itemList

protected List<String> itemList

The items that are showed within the combo transformed to a java.util.List. Needed for indexed operations in the dropdown

text

protected org.eclipse.swt.widgets.Text text

The text control of this NatCombo, allowing to enter values directly.

dropdownShell

protected org.eclipse.swt.widgets.Shell dropdownShell

The Shell containing the dropdown of this NatCombo

dropdownTable

protected org.eclipse.swt.widgets.Table dropdownTable

The Table control used for the combo component of this NatCombo

iconImage

protected org.eclipse.swt.graphics.Image iconImage

The image that is shown at the right edge of the text control if the NatCombo is opened.

style

protected final int style

The style bits that where set on creation time. Needed in case the dropdown shell was disposed and needs to be created again.

freeEdit

protected boolean freeEdit

Flag that indicates whether this ComboBoxCellEditor supports free editing in the text control of the NatCombo or not. By default free editing is disabled.

multiselect

protected boolean multiselect

Flag that indicates whether this NatCombo supports multiselect or not. By default multiselect is disabled.

useCheckbox

protected boolean useCheckbox

Flag that indicates whether checkboxes should be shown for the items in the dropdown.

multiselectValueSeparator

protected String multiselectValueSeparator

String that is used to separate values in the String representation showed in the text control if multiselect is supported.

multiselectTextPrefix

protected String multiselectTextPrefix

String that is used to prefix the generated String representation showed in the text control if multiselect is supported. Needed to visualize the multiselection to the user.

multiselectTextSuffix

protected String multiselectTextSuffix

String that is used to suffix the generated String representation showed in the text control if multiselect is supported. Needed to visualize the multiselection to the user.

Constructor Detail

NatCombo

public NatCombo(org.eclipse.swt.widgets.Composite parent,
        IStyle cellStyle,
        int style)

Creates a new NatCombo using the given IStyle for rendering, showing the default number of items at once in the dropdown. Creating the NatCombo with this constructor, there is no free edit and no multiple selection enabled.

Parameters:

parent - A widget that will be the parent of this NatCombo

cellStyle - Style configuration containing horizontal alignment, font, foreground and background color information.

style - The style for the Text Control to construct. Uses this style adding internal styles via ConfigRegistry.

NatCombo

public NatCombo(org.eclipse.swt.widgets.Composite parent,
        IStyle cellStyle,
        int maxVisibleItems,
        int style)

Creates a new NatCombo using the given IStyle for rendering, showing the given amount of items at once in the dropdown. Creating the NatCombo with this constructor, there is no free edit and no multiple selection enabled.

Parameters:

parent - A widget that will be the parent of this NatCombo

cellStyle - Style configuration containing horizontal alignment, font, foreground and background color information.

maxVisibleItems - the max number of items the drop down will show before introducing a scroll bar.

style - The style for the Text Control to construct. Uses this style adding internal styles via ConfigRegistry.

NatCombo

public NatCombo(org.eclipse.swt.widgets.Composite parent,
        IStyle cellStyle,
        int maxVisibleItems,
        int style,
        org.eclipse.swt.graphics.Image iconImage)

Creates a new NatCombo using the given IStyle for rendering, showing the given amount of items at once in the dropdown.

Parameters:

parent - A widget that will be the parent of this NatCombo

cellStyle - Style configuration containing horizontal alignment, font, foreground and background color information.

maxVisibleItems - the max number of items the drop down will show before introducing a scroll bar.

style - The style for the Text Control to construct. Uses this style adding internal styles via ConfigRegistry.

iconImage - The image to use as overlay to the Text Control if the dropdown is visible. Using this image will indicate that the control is an open combo to the user.

Method Detail

dispose

public void dispose()

Overrides:

dispose in class org.eclipse.swt.widgets.Widget

setItems

public void setItems(String[] items)

Sets the given items to be the items shown in the dropdown of this NatCombo.

Parameters:

items - The array of items to set.

createTextControl

protected void createTextControl(int style)

Creates the Text control of this NatCombo, adding styles, look&feel and needed listeners for the control only.

Parameters:

style - The style for the Text Control to construct. Uses this style adding internal styles via ConfigRegistry.

createDropdownControl

protected void createDropdownControl(int style)

Create the dropdown control of this NatCombo, adding styles, look&feel and needed listeners for the control only.

Parameters:

style - The style for the Table Control to construct. Uses this style adding internal styles via ConfigRegistry.

updateTextControl

protected void updateTextControl(boolean hideDropdown)

This method will be called if an item of the dropdown control is selected via mouse click or pressing enter. It will populate the text control with the information gathered out of the selection in the dropdown control and hide the dropdown if necessary.

Parameters:

hideDropdown - true if the dropdown should be hidden after updating the text control

showDropdownControl

public void showDropdownControl()

Shows the dropdown of this NatCombo. Will always calculate the size of the dropdown regarding the current size of the Text control.

showDropdownControl

public void showDropdownControl(boolean focusOnText)

Shows the dropdown of this NatCombo. Will always calculate the size of the dropdown regarding the current size of the Text control.

Parameters:

focusOnText - true if the focus should be set to the text control instead of the dropdown after opening the dropdown.

hideDropdownControl

public void hideDropdownControl()

Hide the dropdown of this NatCombo.

getVisibleItemCount

protected int getVisibleItemCount()

Calculates the number of items that should be showed in the dropdown at once. It is needed to calculate the height of the dropdown. If maxVisibleItems is configured -1, this method always returns the number of items in the list. Otherwise if will return the configured maximum number of items to be visible at once or less if there are less than the configured maximum.

Returns:

the number of items that should be showed in the dropdown at once.

calculateBounds

protected void calculateBounds()

Calculates the size and location of the Shell that represents the dropdown control of this NatCombo. Size and location will be calculated dependent the position and size of the corresponding Text control and the information showed in the dropdown.

getSelectionIndex

public int getSelectionIndex()

Returns the zero-relative index of the item which is currently selected in the receiver, or -1 if no item is selected.

Note that this only returns useful results if this NatCombo supports single selection or only one item is selected.

Returns:

the index of the selected item or -1

getSelectionIndices

public int[] getSelectionIndices()

Returns the zero-relative indices of the items which are currently selected in the receiver. The order of the indices is unspecified. The array is empty if no items are selected.

Note: This is not the actual structure used by the receiver to maintain its selection, so modifying the array will not affect the receiver.

Returns:

the array of indices of the selected items

getSelectionCount

public int getSelectionCount()

Returns the number of selected items contained in the receiver.

Returns:

the number of selected items

getSelection

public String[] getSelection()

Returns an array of Strings that are currently selected in the receiver. The order of the items is unspecified. An empty array indicates that no items are selected.

Note: This is not the actual structure used by the receiver to maintain its selection, so modifying the array will not affect the receiver.

Returns:

an array representing the selection

setSelection

public void setSelection(String[] items)

Selects the items at the given zero-relative indices in the receiver. The current selection is cleared before the new items are selected.

Indices that are out of range and duplicate indices are ignored. If the receiver is single-select and multiple indices are specified, then all indices are ignored.

The text control of this NatCombo will also be updated with the new selected values.

Parameters:

items - the items to select

select

public void select(int index)

Selects the item at the given zero-relative index in the receiver's list. If the item at the index was already selected, it remains selected. Indices that are out of range are ignored.

Parameters:

index - the index of the item to select

select

public void select(int[] indeces)

Selects the items at the given zero-relative indices in the receiver. The current selection is not cleared before the new items are selected.

If the item at a given index is not selected, it is selected. If the item at a given index was already selected, it remains selected. Indices that are out of range and duplicate indices are ignored. If the receiver is single-select and multiple indices are specified, then all indices are ignored.

Parameters:

indices - the array of indices for the items to select

addKeyListener

public void addKeyListener(org.eclipse.swt.events.KeyListener listener)

Overrides:

addKeyListener in class org.eclipse.swt.widgets.Control

addTraverseListener

public void addTraverseListener(org.eclipse.swt.events.TraverseListener listener)

Overrides:

addTraverseListener in class org.eclipse.swt.widgets.Control

addMouseListener

public void addMouseListener(org.eclipse.swt.events.MouseListener listener)

Overrides:

addMouseListener in class org.eclipse.swt.widgets.Control

notifyListeners

public void notifyListeners(int eventType,
                   org.eclipse.swt.widgets.Event event)

Overrides:

notifyListeners in class org.eclipse.swt.widgets.Widget

addSelectionListener

public void addSelectionListener(org.eclipse.swt.events.SelectionListener listener)

addShellListener

public void addShellListener(org.eclipse.swt.events.ShellListener listener)

getTransformedSelection

protected String[] getTransformedSelection()

Transforms the selection in the Table control dropdown into a String[]. Doing this is necessary to provide a SWT List like interface regarding selections for the NatCombo.

Returns:

Array containing all selected TableItem text attributes

setDropdownSelection

protected void setDropdownSelection(String[] selection)

Transforms the given String array whose contents represents selected items to a selection that can be handled by the underlying Table control in the dropdown.

Parameters:

selection - The Strings that represent the selected items

getTextAsArray

protected String[] getTextAsArray()

Will transform the text for the Text control of this NatCombo to an array of Strings. This is necessary for the multiselect feature.

Note that by default the multiselect String is specified to show with enclosing [] brackets and values separated by ", ". If you need to change this you need to set the corresponding values in this NatCombo.

Returns:

The text for the Text control of this NatCombo converted to an array of Strings.

getTransformedTextForSelection

protected String getTransformedTextForSelection()

Transforms the selection of the dropdown to a text representation that can be added to the text control of this combo.

Note that by default the multiselect String is specified to show with enclosing [] brackets and values separated by ", ". If you need to change this you need to set the corresponding values in this NatCombo.

Returns:

String representation for the selection within the combo.

getTransformedText

protected String getTransformedText(String[] values)

Transforms the given array of Strings to a text representation that can be added to the text control of this combo.

If this NatCombo is only configured to support single selection, than only the first value in the array will be processed. Otherwise the result will be processed by concatenating the values.

Note that by default the multiselect String is specified to show with enclosing [] brackets and values separated by ", ". If you need to change this you need to set the corresponding values in this NatCombo.

Parameters:

values - The values to build the text representation from.

Returns:

String representation for the selection within the combo.

setMultiselectValueSeparator

public void setMultiselectValueSeparator(String multiselectValueSeparator)

Parameters:

multiselectValueSeparator - String that should be used to separate values in the String representation showed in the text control if multiselect is supported. null to use the default value separator.

See Also:

DEFAULT_MULTI_SELECT_VALUE_SEPARATOR

setMultiselectTextBracket

public void setMultiselectTextBracket(String multiselectTextPrefix,
                             String multiselectTextSuffix)

Set the prefix and suffix that will parenthesize the text that is created out of the selected values if this NatCombo supports multiselection.

Parameters:

multiselectTextPrefix - String that should be used to prefix the generated String representation showed in the text control if multiselect is supported. null to use the default prefix.

multiselectTextSuffix - String that should be used to suffix the generated String representation showed in the text control if multiselect is supported. null to use the default suffix.

See Also:

DEFAULT_MULTI_SELECT_PREFIX, DEFAULT_MULTI_SELECT_SUFFIX