org.gwt.advanced.client.ui.widget

Class ComboBox<T extends ListDataModel>

java.lang.Object

com.google.gwt.user.client.ui.UIObject

com.google.gwt.user.client.ui.Widget

com.google.gwt.user.client.ui.Panel

com.google.gwt.user.client.ui.SimplePanel

org.gwt.advanced.client.ui.widget.TextButtonPanel<String>

org.gwt.advanced.client.ui.widget.ComboBox<T>

All Implemented Interfaces:

com.google.gwt.event.dom.client.HasAllFocusHandlers, com.google.gwt.event.dom.client.HasAllKeyHandlers, com.google.gwt.event.dom.client.HasBlurHandlers, com.google.gwt.event.dom.client.HasChangeHandlers, com.google.gwt.event.dom.client.HasClickHandlers, com.google.gwt.event.dom.client.HasFocusHandlers, com.google.gwt.event.dom.client.HasKeyDownHandlers, com.google.gwt.event.dom.client.HasKeyPressHandlers, com.google.gwt.event.dom.client.HasKeyUpHandlers, com.google.gwt.event.logical.shared.HasAttachHandlers, com.google.gwt.event.logical.shared.HasCloseHandlers<com.google.gwt.user.client.ui.PopupPanel>, com.google.gwt.event.logical.shared.HasValueChangeHandlers<String>, com.google.gwt.event.shared.HasHandlers, com.google.gwt.user.client.EventListener, com.google.gwt.user.client.TakesValue<String>, com.google.gwt.user.client.ui.AcceptsOneWidget, com.google.gwt.user.client.ui.HasOneWidget, com.google.gwt.user.client.ui.HasValue<String>, com.google.gwt.user.client.ui.HasVisibility, com.google.gwt.user.client.ui.HasWidgets, com.google.gwt.user.client.ui.HasWidgets.ForIsWidget, com.google.gwt.user.client.ui.IsWidget, Iterable<com.google.gwt.user.client.ui.Widget>, ListModelListener, AdvancedWidget

Direct Known Subclasses:

SuggestionBox

public class ComboBox<T extends ListDataModel>
extends TextButtonPanel<String>
implements com.google.gwt.event.dom.client.HasAllFocusHandlers, com.google.gwt.event.dom.client.HasAllKeyHandlers, com.google.gwt.event.dom.client.HasClickHandlers, ListModelListener, com.google.gwt.event.dom.client.HasChangeHandlers, com.google.gwt.event.logical.shared.HasCloseHandlers<com.google.gwt.user.client.ui.PopupPanel>

This is a combo box widget implementation.

Since:

1.2.0

Author:

Sergey Skladchikov

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	ComboBox.ComboBoxKeyboardManager This is a keyboard manager implementation developed for the widget.
protected class	ComboBox.DelegateHandler Universal handler that delegates all events handling to custom handlers.

Nested classes/interfaces inherited from class org.gwt.advanced.client.ui.widget.TextButtonPanel

TextButtonPanel.EnterAction

Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject

com.google.gwt.user.client.ui.UIObject.DebugIdImpl, com.google.gwt.user.client.ui.UIObject.DebugIdImplEnabled

Nested classes/interfaces inherited from interface com.google.gwt.user.client.ui.HasWidgets

com.google.gwt.user.client.ui.HasWidgets.ForIsWidget

Field Summary

Fields inherited from class com.google.gwt.user.client.ui.UIObject

DEBUG_ID_PREFIX

Constructor Summary

Constructors

Constructor and Description
ComboBox()

Method Summary

Methods

Modifier and Type	Method and Description
protected void	add(ListModelEvent event) Adds a new visual item into the drop down list every time when it's added into the data model.
com.google.gwt.event.shared.HandlerRegistration	addBlurHandler(com.google.gwt.event.dom.client.BlurHandler handler)
com.google.gwt.event.shared.HandlerRegistration	addChangeHandler(com.google.gwt.event.dom.client.ChangeHandler handler) Note that handlers added by this method will receive ComboBoxChangeEvents.
com.google.gwt.event.shared.HandlerRegistration	addClickHandler(com.google.gwt.event.dom.client.ClickHandler handler)
com.google.gwt.event.shared.HandlerRegistration	addCloseHandler(com.google.gwt.event.logical.shared.CloseHandler<com.google.gwt.user.client.ui.PopupPanel> handler) Adds a close handler to the popup list of items.
protected void	addComponentListeners() This method adds component listeners.
com.google.gwt.event.shared.HandlerRegistration	addFocusHandler(com.google.gwt.event.dom.client.FocusHandler handler)
com.google.gwt.event.shared.HandlerRegistration	addKeyDownHandler(com.google.gwt.event.dom.client.KeyDownHandler handler)
com.google.gwt.event.shared.HandlerRegistration	addKeyPressHandler(com.google.gwt.event.dom.client.KeyPressHandler handler)
com.google.gwt.event.shared.HandlerRegistration	addKeyUpHandler(com.google.gwt.event.dom.client.KeyUpHandler handler)
com.google.gwt.event.shared.HandlerRegistration	addValueChangeHandler(com.google.gwt.event.logical.shared.ValueChangeHandler<String> handler) Adds a value change handler to the component that will be invoked only if HasValue.setValue(Object, boolean) has the second parameter = true.
protected void	clean(ListModelEvent event) This method cleans the drop down list on each data clean.
void	cleanSelection() Cleans all the data displayed in the widget.
protected String	getDefaultImageName() This method should returns a default button image name.
protected ComboBox.DelegateHandler	getDelegateHandler() Getter for property 'delegateHandler'.
DropDownPosition	getDropDownPosition() Gets applied position of the drop down list.
int	getHighlightRow() Gets a highlight row number.
com.google.gwt.user.client.ui.Widget	getItem(int index) Gets an item by its index If index < 0 or index >= getItemCount() it throws an exception.
int	getItemCount() This method gets an actual number of items displayed in the drop down.
int	getItemIndex(com.google.gwt.user.client.ui.Widget item) Gets an item index if it's displayed in the drop down list.
protected ComboBox.ComboBoxKeyboardManager	getKeyboardManager() This method gets a keybord manager implementation for the component.
ListItemFactory	getListItemFactory() Getter for property 'listItemFactory'.
protected ListPopupPanel	getListPanel() Getter for property 'listPanel'.
ListDataModel	getModel() Getter for property 'model'.
Object	getSelected() This method returns a selected item.
String	getSelectedId() This method returns a selected item ID.
int	getSelectedIndex() This method returns a selected item index.
com.google.gwt.user.client.ui.Widget	getSelectedWidget() This method gets a widget that is currently selected in the drop down list.
int	getStartItemIndex()
String	getText() Deprecated. use getValue() instead.
String	getValue() Similar to getText()
int	getVisibleRows() Gets a number of visible rows.
void	hideList() Hides the drop down list.
protected boolean	isKeyPressed() Returns true if cursor is moved by a control key.
boolean	isLazyRenderingEnabled() Checks whether the lazy rendering option is enabled.
boolean	isListPanelOpened() This method check the list panel status.
void	moveCursor(int step) Moves the cursor up or down.
void	onModelEvent(ListModelEvent event) This method should implement actions which related widgets must do on events.
protected void	prepareSelectedValue() Prepares the selected value box for displaying.
protected void	remove(ListModelEvent event) Removes a visual item from the drop down list if the remove event is received.
void	select(int row) Selects the specified item in the model and in the drop down list.
protected void	select(ListModelEvent event) Highlights the visual item in the drop down list if it's selected in the model.
void	setDropDownPosition(DropDownPosition dropDownPosition) Sets applied position of the drop down list.
void	setFocus(boolean focus) This method sets focus on this widget.
void	setHighlightRow(int row) Sets a highlight row number and display the row as selected but not actually select it.
protected void	setKeyPressed(boolean keyPressed) Sets the value of the key pressed flag.
void	setLazyRenderingEnabled(boolean lazyRenderingEnabled) Enables or disables lazy rendering option.
void	setListItemFactory(ListItemFactory listItemFactory) Setter for property 'listItemFactory'.
void	setListPopupOpened(boolean opened) Opens / closes list popup panel by request.
void	setModel(T model) Setter for property 'model'.
void	setSelectedId(String id) This method sets the selected item ID.
void	setSelectedIndex(int index) This method sets the selected item index.
void	setStartItemIndex(int index) Sets an item index that must be displayed on top.
void	setText(String text) Deprecated. use setValue(String) instead.
void	setValue(String value) Similar to setText(String) and doesn't send any event
void	setValue(String value, boolean fireEvents) Similar to setText(String) and sends ValueChangeEvent if fireEvents = true
void	setVisibleRows(int visibleRows) Sets visible rows number.
void	showList(boolean prepareList) This method shows the drop down list.

Methods inherited from class org.gwt.advanced.client.ui.widget.TextButtonPanel

display, getChoiceButton, getChoiceButtonImage, getEnterAction, getHeight, getLayout, getLockingPanel, getMaxLength, getSelectedValue, getWidth, isChoiceButtonVisible, isCustomTextAllowed, isEnabled, isLocked, lock, prepareChoiceButton, setChoiceButtonImage, setChoiceButtonVisible, setCustomTextAllowed, setEnabled, setEnterAction, setHeight, setLocked, setMaxLength, setTabIndex, setWidth, unlock

Methods inherited from class com.google.gwt.user.client.ui.SimplePanel

add, getContainerElement, getWidget, iterator, remove, setWidget, setWidget

Methods inherited from class com.google.gwt.user.client.ui.Panel

add, adopt, adopt, clear, disown, doAttachChildren, doDetachChildren, orphan, remove

Methods inherited from class com.google.gwt.user.client.ui.Widget

addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, fireEvent, getHandlerCount, getLayoutData, getParent, isAttached, isOrWasAttached, onAttach, onBrowserEvent, onDetach, onLoad, onUnload, removeFromParent, setLayoutData, sinkEvents

Methods inherited from class com.google.gwt.user.client.ui.UIObject

addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, onEnsureDebugId, removeStyleDependentName, removeStyleName, resolvePotentialElement, setElement, setElement, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, sinkBitlessEvent, toString, unsinkEvents

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.google.gwt.event.shared.HasHandlers

fireEvent

Constructor Detail

ComboBox

public ComboBox()

Method Detail

setModel

public void setModel(T model)

Setter for property 'model'.

Parameters:

model - Value to set for property 'model'.

setListItemFactory

public void setListItemFactory(ListItemFactory listItemFactory)

Setter for property 'listItemFactory'.

Parameters:

listItemFactory - Value to set for property 'listItemFactory'.

addBlurHandler

public com.google.gwt.event.shared.HandlerRegistration addBlurHandler(com.google.gwt.event.dom.client.BlurHandler handler)

Specified by:

addBlurHandler in interface com.google.gwt.event.dom.client.HasBlurHandlers

addFocusHandler

public com.google.gwt.event.shared.HandlerRegistration addFocusHandler(com.google.gwt.event.dom.client.FocusHandler handler)

Specified by:

addFocusHandler in interface com.google.gwt.event.dom.client.HasFocusHandlers

addKeyUpHandler

public com.google.gwt.event.shared.HandlerRegistration addKeyUpHandler(com.google.gwt.event.dom.client.KeyUpHandler handler)

Specified by:

addKeyUpHandler in interface com.google.gwt.event.dom.client.HasKeyUpHandlers

addKeyDownHandler

public com.google.gwt.event.shared.HandlerRegistration addKeyDownHandler(com.google.gwt.event.dom.client.KeyDownHandler handler)

Specified by:

addKeyDownHandler in interface com.google.gwt.event.dom.client.HasKeyDownHandlers

addKeyPressHandler

public com.google.gwt.event.shared.HandlerRegistration addKeyPressHandler(com.google.gwt.event.dom.client.KeyPressHandler handler)

Specified by:

addKeyPressHandler in interface com.google.gwt.event.dom.client.HasKeyPressHandlers

addChangeHandler

public com.google.gwt.event.shared.HandlerRegistration addChangeHandler(com.google.gwt.event.dom.client.ChangeHandler handler)

Note that handlers added by this method will receive ComboBoxChangeEvents.

Specified by:

addChangeHandler in interface com.google.gwt.event.dom.client.HasChangeHandlers

Parameters:

handler - the change handler

Returns:

a handler registration.

addClickHandler

public com.google.gwt.event.shared.HandlerRegistration addClickHandler(com.google.gwt.event.dom.client.ClickHandler handler)

Specified by:

addClickHandler in interface com.google.gwt.event.dom.client.HasClickHandlers

getModel

public ListDataModel getModel()

Getter for property 'model'.

Returns:

Value for property 'model'.

getListItemFactory

public ListItemFactory getListItemFactory()

Getter for property 'listItemFactory'.

Returns:

Value for property 'listItemFactory'.

setFocus

public void setFocus(boolean focus)

This method sets focus on this widget.

But note that the combo box is not a focus event sourcer. It siply delegtes this functionality to the text box.

Parameters:

focus - is a flag of focus.

isListPanelOpened

public boolean isListPanelOpened()

This method check the list panel status.

Returns:

true if it's opened.

getText

public String getText()

Deprecated. use getValue() instead.

This method returns a value currently displayed in the text box.

Returns:

a text value.

getVisibleRows

public int getVisibleRows()

Gets a number of visible rows.

Values <= 0 interpreted as undefined.

Returns:

a visible rows to be displayed without scrolling.

setVisibleRows

public void setVisibleRows(int visibleRows)

Sets visible rows number.

You can pass a value <= 0. It will mean that this parameter in undefined.

Parameters:

visibleRows - is a number of rows to be displayed without scrolling.

setStartItemIndex

public void setStartItemIndex(int index)

Sets an item index that must be displayed on top.

If the item is outside the currently visible area the list will be scrolled down to this item.

Parameters:

index - is an index of the item that must be displayed on top of the visible area.

getStartItemIndex

public int getStartItemIndex()

setText

public void setText(String text)

Deprecated. use setValue(String) instead.

Sets text to the selected value box but doesn't change anything in the list of items.

Parameters:

text - is a text to set.

getSelected

public Object getSelected()

This method returns a selected item.

Returns:

is a selected item.

getSelectedIndex

public int getSelectedIndex()

This method returns a selected item index.

Returns:

is a selected item index.

getSelectedId

public String getSelectedId()

This method returns a selected item ID.

Returns:

is a selected item ID.

setSelectedId

public void setSelectedId(String id)

This method sets the selected item ID.

Parameters:

id - is an item ID to select.

setSelectedIndex

public void setSelectedIndex(int index)

This method sets the selected item index.

Parameters:

index - a selected item index.

setListPopupOpened

public void setListPopupOpened(boolean opened)

Opens / closes list popup panel by request.

Parameters:

opened - true means "show".

getSelectedWidget

public com.google.gwt.user.client.ui.Widget getSelectedWidget()

This method gets a widget that is currently selected in the drop down list.

Returns:

null if the drop down list is collapsed.

cleanSelection

public void cleanSelection()

Cleans all the data displayed in the widget.

Overrides:

cleanSelection in class TextButtonPanel<String>

getHighlightRow

public int getHighlightRow()

Gets a highlight row number.

Note that sometimes this value is not equal to the selected row.

Returns:

a highlight row number or -1 if nothing is highlight.

setHighlightRow

public void setHighlightRow(int row)

Sets a highlight row number and display the row as selected but not actually select it.

Parameters:

row - is a row number to highlight. If it's out of range thus method does nothing.

getItemCount

public int getItemCount()

This method gets an actual number of items displayed in the drop down.

Returns:

an item count.

getItem

public com.google.gwt.user.client.ui.Widget getItem(int index)

Gets an item by its index

If index < 0 or index >= getItemCount() it throws an exception.

Parameters:

index - is an index of the item to get.

Returns:

a foudn item.

Throws:

IndexOutOfBoundsException - if index is invalid.

getItemIndex

public int getItemIndex(com.google.gwt.user.client.ui.Widget item)

Gets an item index if it's displayed in the drop down list.

Otherwise returns -1.

Parameters:

item - an item that is required to return.

Returns:

an item index value or -1.

showList

public void showList(boolean prepareList)

This method shows the drop down list.

Parameters:

prepareList - forces the list to be prepared (refreshed) before displaying.

moveCursor

public void moveCursor(int step)

Moves the cursor up or down.

Parameters:

step - is a number of items relative to the current cursor position.

hideList

public void hideList()

Hides the drop down list.

select

public void select(int row)

Selects the specified item in the model and in the drop down list.

Parameters:

row - is a row index to select

onModelEvent

public void onModelEvent(ListModelEvent event)

This method should implement actions which related widgets must do on events.

Specified by:

onModelEvent in interface ListModelListener

Parameters:

event - an event produced by the model.

isLazyRenderingEnabled

public boolean isLazyRenderingEnabled()

Checks whether the lazy rendering option is enabled.

Returns:

a result of check.

setLazyRenderingEnabled

public void setLazyRenderingEnabled(boolean lazyRenderingEnabled)

Enables or disables lazy rendering option.

If this option is enabled the widget displays only several items on lazily renders other ones on scroll down.

By default lazy rendering is disabled. Switch it on for really large (over 500 items) lists only.

Note that lazy rendering is not lazy data loading. The second one means that the data is loaded into the model on request where as the first option assumes that all necessary data has already been loaded and put into the model. If you need lazy loading please consider using SuggestionBox and SuggestionBoxDataModel.

Parameters:

lazyRenderingEnabled - is an option value.

getDropDownPosition

public DropDownPosition getDropDownPosition()

Gets applied position of the drop down list.

Returns:

a drop down list position value.

setDropDownPosition

public void setDropDownPosition(DropDownPosition dropDownPosition)

Sets applied position of the drop down list.

Being set the drop down is immediately applied if the list is opened.

Parameters:

dropDownPosition - is a drop down list position value.

addCloseHandler

public com.google.gwt.event.shared.HandlerRegistration addCloseHandler(com.google.gwt.event.logical.shared.CloseHandler<com.google.gwt.user.client.ui.PopupPanel> handler)

Adds a close handler to the popup list of items.

Specified by:

addCloseHandler in interface com.google.gwt.event.logical.shared.HasCloseHandlers<com.google.gwt.user.client.ui.PopupPanel>

Parameters:

handler - is a handler to add.

Returns:

a handler registration.

getValue

public String getValue()

Similar to getText()

Specified by:

getValue in interface com.google.gwt.user.client.TakesValue<String>

Specified by:

getValue in interface com.google.gwt.user.client.ui.HasValue<String>

setValue

public void setValue(String value)

Similar to setText(String) and doesn't send any event

Specified by:

setValue in interface com.google.gwt.user.client.TakesValue<String>

Specified by:

setValue in interface com.google.gwt.user.client.ui.HasValue<String>

setValue

public void setValue(String value,
            boolean fireEvents)

Similar to setText(String) and sends ValueChangeEvent if fireEvents = true

Specified by:

setValue in interface com.google.gwt.user.client.ui.HasValue<String>

addValueChangeHandler

public com.google.gwt.event.shared.HandlerRegistration addValueChangeHandler(com.google.gwt.event.logical.shared.ValueChangeHandler<String> handler)

Adds a value change handler to the component that will be invoked only if HasValue.setValue(Object, boolean) has the second parameter = true.

Note that the widget doesn't fire the event if you don't use the method specified above.

Specified by:

addValueChangeHandler in interface com.google.gwt.event.logical.shared.HasValueChangeHandlers<String>

add

protected void add(ListModelEvent event)

Adds a new visual item into the drop down list every time when it's added into the data model.

Parameters:

event - is an event containing data about the item.

clean

protected void clean(ListModelEvent event)

This method cleans the drop down list on each data clean.

Parameters:

event - is a clean event.

remove

protected void remove(ListModelEvent event)

Removes a visual item from the drop down list if the remove event is received.

Parameters:

event - is an event that contains data of the removed item.

select

protected void select(ListModelEvent event)

Highlights the visual item in the drop down list if it's selected in the model.

Parameters:

event - is an event that contains data about selected item.

getDefaultImageName

protected String getDefaultImageName()

This method should returns a default button image name.

Specified by:

getDefaultImageName in class TextButtonPanel<String>

Returns:

an image name.

isKeyPressed

protected boolean isKeyPressed()

Returns true if cursor is moved by a control key.

Returns:

a flag value.

setKeyPressed

protected void setKeyPressed(boolean keyPressed)

Sets the value of the key pressed flag.

Parameters:

keyPressed - is a key pressed flag value.

prepareSelectedValue

protected void prepareSelectedValue()

Prepares the selected value box for displaying.

Overrides:

prepareSelectedValue in class TextButtonPanel<String>

addComponentListeners

protected void addComponentListeners()

This method adds component listeners.

Specified by:

addComponentListeners in class TextButtonPanel<String>

getListPanel

protected ListPopupPanel getListPanel()

Getter for property 'listPanel'.

Returns:

Value for property 'listPanel'.

getDelegateHandler

protected ComboBox.DelegateHandler getDelegateHandler()

Getter for property 'delegateHandler'.

Returns:

Value for property 'delegateHandler'.

getKeyboardManager

protected ComboBox.ComboBoxKeyboardManager getKeyboardManager()

This method gets a keybord manager implementation for the component.

Returns:

an instance of the manager.