org.cafesip.gwtcomp.client.ui
Class EditableList

java.lang.Object
  com.google.gwt.user.client.ui.UIObject
      com.google.gwt.user.client.ui.Widget
          com.google.gwt.user.client.ui.Composite
              org.cafesip.gwtcomp.client.ui.EditableList

All Implemented Interfaces:

ClickHandler, KeyUpHandler, EventHandler, HasHandlers, EventListener

public class EditableList
extends Composite
implements ClickHandler, KeyUpHandler

A panel for an editable list that allows the user to add elements to a list and remove elements from the list. This composite consists of the following widgets:

• a TextBox for entering a new element to be added to the list
• a Button that when clicked adds the TextBox contents to the list
• a ListBox containing the current list of elements
• a Button that when clicked removes the selected list element(s) from the list.

You may use your own widget(s) rather than the default widgets created by this component by calling the appropriate constructor. When list elements are added or removed by the user, the action taken by this widget can be configured as follows.

1. [DEFAULT] Perform no validation on the user input/action - this will cause elements to be added or removed as directed by the user without any validation checks.
2. Perform validation, as described below, on user input/action before modifying the list. After instantiating this object, you must call setMessageBar(MessageBar) to cause validation to happen. You may optionally call setErrorMessagePrefix() to override the default text that precedes the error message(s) output when validation fails.
3. Invoke your own logic when the user clicks the Add or Remove Buttons. After instantiating this object, you must call setAddButtonListener(ClickListener) or setRemoveButtonListener(ClickListener) or both. In this case, none of the logic contained in this widget will be executed when the button is clicked.

When validation is done by this widget, the default behavior is as follows.

• When the Add Button is clicked by the user, this widget disallows duplicate list elements.
• When the Remove Button is clicked by the user, this widget prevents the user from removing all of the elements from the list.

The default validation behavior can be changed by calling the following methods: allowDuplicates(true), allowEmptyList(true).

CSS Style Rules:

• .gwtcomp-EditableList { } - style for the panel itself
• .gwtcomp-EditableListNewElement { } - style for the new list element text box
• .gwtcomp-EditableListAddButton { } - style for the Add new list element button
• .gwtcomp-EditableListContents { } - style for the list widget
• .gwtcomp-EditableListRemoveButton { } - style for the Remove element(s) button

Screen-Shots:

In the above screen-shot, the top row contains the text box for the user to enter a new element to be added to the list and the Add button that when clicked adds the text box contents to the list. The second row contains the list of elements itself and the Remove button. The user may select one or more elements from the list and click the Remove button which causes the selected element(s) to be removed from the list.

Author:

Becky McElroy

Nested Class Summary

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

UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled

Field Summary

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

DEBUG_ID_PREFIX

Constructor Summary

EditableList()
An empty constructor for this class.

EditableList(TextBox newElement, Button addButton, ListBox list, Button removeButton)
A constructor for this class.

Method Summary

void	allowDuplicates(boolean allowDuplicates) Sets whether or not validation when done by this widget should allow duplicate entries in the list.
void	allowEmptyList(boolean allowEmptyList) Sets whether or not validation when done by this widget should allow the user to remove all of the elements from the list.
boolean	duplicatesAllowed() Returns whether or not validation when done by this widget would allow duplicate entries in the list.
boolean	emptyListAllowed() Returns whether or not validation when done by this widget would allow the user to remove all of the elements from the list.
String	getErrorMessagePrefix() Returns the error message prefix string that is output along with validation error(s).
ArrayList<String>	getList() Returns the contents of the ListBox.
MessageBar	getMessageBar() Returns the MessageBar as set by a previous call to setMessageBar() or null if setMessageBar() has not been called.
TextBox	getNewElement() Returns the TextBox widget where the user types in a new element to add to the list.
boolean	listContains(String element) Call this method to find out if the list contains the given element.
void	onClick(ClickEvent event)
void	onKeyDown(Widget sender, char keyCode, int modifiers)
void	onKeyPress(Widget sender, char keyCode, int modifiers)
void	onKeyUp(KeyUpEvent event)
void	onKeyUp(Widget sender, char keyCode, int modifiers)
void	setErrorMessagePrefix(String errorMessagePrefix) Sets the error message prefix string to be output along with validation error(s) when this widget performs Add/Remove button validation.
void	setList(ArrayList<String> elements) Set the contents of the ListBox.
void	setMessageBar(MessageBar messageBar) Sets the MessageBar for use by this widget's validation.

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

getWidget, initWidget, isAttached, onAttach, onBrowserEvent, onDetach, setWidget

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

addDomHandler, addHandler, delegateEvent, doAttachChildren, doDetachChildren, fireEvent, getHandlerCount, getLayoutData, getParent, isOrWasAttached, 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, setElement, setElement, setHeight, setPixelSize, setSize, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, toString, unsinkEvents

Methods inherited from class java.lang.Object

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

Constructor Detail

EditableList

public EditableList()

An empty constructor for this class. If you use this constructor, you will get the default widgets as created by this class. Please read the class-level javadoc for information on what additional methods to call, if any, after instantiating this object depending on the validation action or behavior you want.

EditableList

public EditableList(TextBox newElement,
                    Button addButton,
                    ListBox list,
                    Button removeButton)

A constructor for this class. This constructor allows you to define the characteristics or appearance of one or more of the widgets used by this composite widget. For example, by providing the addButton yourself, you can control the label text for the button, the image used on the button and the tooltip for the button. Please read the class-level javadoc for information on what additional methods to call, if any, after instantiating this object depending on the validation action or behavior you want.

Parameters:

newElement - the TextBox for entering a new element to be added to the list

addButton - the Button that when clicked adds the TextBox contents to the list

list - the ListBox containing the current list of elements

removeButton - the Button that when clicked removes the selected list element(s) from the list

Method Detail

onKeyDown

public void onKeyDown(Widget sender,
                      char keyCode,
                      int modifiers)

onKeyPress

public void onKeyPress(Widget sender,
                       char keyCode,
                       int modifiers)

onKeyUp

public void onKeyUp(Widget sender,
                    char keyCode,
                    int modifiers)

listContains

public boolean listContains(String element)

Call this method to find out if the list contains the given element.

Parameters:

element - the element of interest

Returns:

true if the element is in the list, false otherwise.

setList

public void setList(ArrayList<String> elements)

Set the contents of the ListBox.

Parameters:

elements - ArrayList of String to set the list contents to.

getList

public ArrayList<String> getList()

Returns the contents of the ListBox.

Returns:

a copy of the list contents in the form of ArrayList of String.

getNewElement

public TextBox getNewElement()

Returns the TextBox widget where the user types in a new element to add to the list.

Returns:

Returns the newElement TextBox.

getMessageBar

public MessageBar getMessageBar()

Returns the MessageBar as set by a previous call to setMessageBar() or null if setMessageBar() has not been called.

Returns:

Returns the messageBar.

setMessageBar

public void setMessageBar(MessageBar messageBar)

Sets the MessageBar for use by this widget's validation. Setting the MessageBar to a non-null value causes this widget to perform validation when the user hits the Add or Remove button.

Parameters:

messageBar - The messageBar to set.

getErrorMessagePrefix

public String getErrorMessagePrefix()

Returns the error message prefix string that is output along with validation error(s).

Returns:

Returns the errorMessagePrefix.

setErrorMessagePrefix

public void setErrorMessagePrefix(String errorMessagePrefix)

Sets the error message prefix string to be output along with validation error(s) when this widget performs Add/Remove button validation.

Parameters:

errorMessagePrefix - The errorMessagePrefix to set.

duplicatesAllowed

public boolean duplicatesAllowed()

Returns whether or not validation when done by this widget would allow duplicate entries in the list.

Returns:

true if setAllowDuplicates(true) has previously been called, false otherwise.

allowDuplicates

public void allowDuplicates(boolean allowDuplicates)

Sets whether or not validation when done by this widget should allow duplicate entries in the list.

Parameters:

allowDuplicates - true if duplicate elements in the list should be allowed, false otherwise.

emptyListAllowed

public boolean emptyListAllowed()

Returns whether or not validation when done by this widget would allow the user to remove all of the elements from the list.

Returns:

true if setAllowEmptyList(true) has previously been called, false otherwise.

allowEmptyList

public void allowEmptyList(boolean allowEmptyList)

Sets whether or not validation when done by this widget should allow the user to remove all of the elements from the list.

Parameters:

allowEmptyList - true if the user should be allowed to remove all of the elements from the list, false otherwise.

onClick

public void onClick(ClickEvent event)

Specified by:

onClick in interface ClickHandler

onKeyUp

public void onKeyUp(KeyUpEvent event)

Specified by:

onKeyUp in interface KeyUpHandler