objectivehtml.htmlwidget
Class HtmlListBox

java.lang.Object
  |
  +--objectivehtml.oms.OMSObject
        |
        +--objectivehtml.htmlwidget.HtmlElement
              |
              +--objectivehtml.htmlwidget.HtmlWidget
                    |
                    +--objectivehtml.htmlwidget.HtmlControlWidget
                          |
                          +--objectivehtml.htmlwidget.HtmlListBox

public class HtmlListBox

extends HtmlControlWidget

This class represents combobox or list box. i.e.

	<select>
		<option value="1">Apples</option>
		<option value="2">Bananas</option>
		<option value="3">Oranges</option>
	</select>
 

The widget allows users to select one or multiple options from a list of options. If the list box has a "size" of one then the widget will be rendered as a drop-down list and the user must click on the drop-down to see the list of available options. If the "size" is greater than one then the widget will be rendered as a list box and users can see a number of options at one time and can scroll through the options. If the "multiple" attribute is set then the user may select one or more options, otherwise they can only choose one.

This widget contains a list of HtmlOptionItem objects internally. These objects represent each option that is available in this list box. An option item has 2 components, its value and option text (description). The value is what is used internally by the form to identify the option item, where as the option text is what is displayed to the client. The value of each option item must be unique for the object to correctly identify the selected values of the list box.

The widget emits these signals:

• optionSelected(String) - if an option item is selected
• optionSelected(int) - if an option item is selected
• selectionChanged(String[],String[]) - if the selected option items have changed
• selectionChanged(int[],int[]) - if the selected option items have changed
• dataSubmitted(String) - if submitted data for this object is received
• dataSubmitted(String[]) - if submitted data for this object is received

See Also:

HtmlOptionItem

Fields inherited from class objectivehtml.htmlwidget.HtmlControlWidget

m_bAutoEscape, m_bAutoUpdate

Fields inherited from class objectivehtml.htmlwidget.HtmlWidget

m_bDestroyed, m_bVisible, m_objHtmlForm, m_objParentWidget

Fields inherited from class objectivehtml.htmlwidget.HtmlElement

m_hmAttributes, m_sEndTag, m_sQuoteType, m_sStartTag

Constructor Summary

HtmlListBox(HtmlContainerWidget objParent, java.lang.String sName)
Constructs an instance of the HtmlListBox with the parent objParent and control name sName.

Method Summary

void	addOption(java.lang.String sValue, java.lang.String sOptionText) Adds a (value, option) pair to the list box.
void	clearOptions() Clears all the options of the list box.
void	clearSelections() Clears all the selections of this list box.
int	getNumberOfOptions() Returns the number of options for this list box.
HtmlOptionItem	getOptionItem(int nIndex) Returns the HtmlOptionItem object representing the option at the specified index nIndex.
int	getOptionItemIndex(HtmlOptionItem objOptionItem) Returns the index of the given HtmlOptionItem object.
int	getSelectedIndex() Returns the index of the first selected item or -1 if no item is selected.
int[]	getSelectedIndicies() Returns an array of the indicies of the currently selected options
java.lang.String	getSelectedValue() Returns the value of the first selected item or null if no item is selected.
java.lang.String[]	getSelectedValues() Returns an array of the values of the currently selected options
java.lang.String	getSize() Returns the size of this list box.
boolean	isMultiple() Returns whether the list box allows multiple selections.
boolean	isSelected(int nIndex) Indicates if an option item has been selected.
Signal	optionSelected(int nOptionIndex) This signal is emitted when an option is selected.
Signal	optionSelected(java.lang.String sOptionValue) This signal is emitted when an option is selected.
void	printHtml(javax.servlet.jsp.JspWriter objWriter, int nOutputType) Prints the html that represents this object to the output stream.
void	printHtml(java.io.PrintWriter objWriter, int nOutputType) Prints the html that represents this object to the output stream.
void	removeOption(int nIndex) Removes an option from the list box at the specified index nIndex.
Signal	selectionUpdated(int[] anNewSelectedIndicies, int[] anOldSelectedIndicies) This signal is emitted when the updateData(HttpServletRequest) method is called on this object and selections have changed.
Signal	selectionUpdated(java.lang.String[] asNewValues, java.lang.String[] asOldValues) This signal is emitted when the updateData(HttpServletRequest) method is called on this object and selections have changed.
void	setAutoEscape(boolean bAutoEscape) Sets the auto-escape feature to be either on (default) or off.
void	setMultiple(boolean bMultiple) Sets the list box to either accept multiple selections or a single selection.
void	setSelected(int nIndex, boolean bChecked) Sets the specified option item to be checked or unchecked.
void	setSelected(java.lang.String sOptionValue, boolean bChecked) Sets the first option item with the value sOptionValue to be checked or unchecked.
void	setSize(java.lang.String sSize) Sets the size for this list box.
void	updateData(javax.servlet.http.HttpServletRequest objRequest) Updates this object with the data submitted from the client.

Methods inherited from class objectivehtml.htmlwidget.HtmlControlWidget

dataSubmitted, dataSubmitted, destroy, getName, getOnBlur, getOnChange, getOnFocus, getOnSelect, getSubmittedData, getSubmittedDataSet, getTabIndex, getUpdateOrder, isAutoEscape, isAutoUpdate, isDisabled, setAttribute, setAutoUpdate, setBooleanAttribute, setDisabled, setOnBlur, setOnChange, setOnFocus, setOnSelect, setTabIndex, setUpdateOrder, setVisible

Methods inherited from class objectivehtml.htmlwidget.HtmlWidget

changeParent, changeParent, getClassAttribute, getHtmlForm, getID, getOnClick, getOnDblClick, getOnKeyDown, getOnKeyPress, getOnKeyUp, getOnMouseDown, getOnMouseMove, getOnMouseOut, getOnMouseOver, getOnMouseUp, getParent, getStyle, isDestroyed, isVisible, setClassAttribute, setID, setOnClick, setOnDblClick, setOnKeyDown, setOnKeyPress, setOnKeyUp, setOnMouseDown, setOnMouseMove, setOnMouseOut, setOnMouseOver, setOnMouseUp, setStyle

Methods inherited from class objectivehtml.htmlwidget.HtmlElement

genEndTag, genStartTag, genStartTag, getAttribute, getAttributes, getBooleanAttribute, getQuoteType, printHtml, printHtml, printHtml, printHtml, printHtml, printHtml, setQuoteType, toString, toString

Methods inherited from class objectivehtml.oms.OMSObject

compareClasses, connect, disconnect, emit, isAlive, setAlive, signal, slot, slot

Methods inherited from class java.lang.Object

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

Constructor Detail

HtmlListBox

public HtmlListBox(HtmlContainerWidget objParent,
                   java.lang.String sName)
            throws InvalidControlNameException,
                   InvalidParentWidgetException,
                   InvalidChildWidgetException

Constructs an instance of the HtmlListBox with the parent objParent and control name sName.

Parameters:

objParent - the parent of this widget

sName - the unique control name for the object

Throws:

InvalidControlNameException - if the control name is not valid

InvalidParentWidgetException - if the specified parent widget is not valid

InvalidChildWidgetException - if the parent widget does not accept this widget as a child

Method Detail

setAutoEscape

public void setAutoEscape(boolean bAutoEscape)

Sets the auto-escape feature to be either on (default) or off. If auto-escape is turned on then the "value" data and the text component of the HtmlOptionItem objects are escaped using the HtmlUtils.htmlSpecialChars(String) method before being written out.

Overrides:

setAutoEscape in class HtmlControlWidget

Parameters:

bAutoEscape - true if you want auto-escape on, false otherwise

See Also:

getOptionItem(int), HtmlUtils.htmlSpecialChars(String), HtmlOptionItem

addOption

public void addOption(java.lang.String sValue,
                      java.lang.String sOptionText)

Adds a (value, option) pair to the list box. This will create a new HtmlOptionItem object and is appended to its internal list of option item objects. sValue for each option should be unique, otherwise the list box will not be able to correctly identify which options have been selected by the client.

Parameters:

sValue - the value for the new option

sOptionText - the text part of the new option

See Also:

getOptionItem(int), removeOption(int), HtmlOptionItem

removeOption

public void removeOption(int nIndex)

Removes an option from the list box at the specified index nIndex. The first option item has the index 0.

Parameters:

nIndex - the index position of the option to be removed

See Also:

addOption(String, String), getOptionItem(int)

getNumberOfOptions

public int getNumberOfOptions()

Returns the number of options for this list box.

Returns:

the number of options

getOptionItem

public HtmlOptionItem getOptionItem(int nIndex)

Returns the HtmlOptionItem object representing the option at the specified index nIndex. The first option item has the index 0.

Parameters:

nIndex - the index position of the option

Returns:

the HtmlOptionItem representing the option at the specified index

See Also:

addOption(String, String), getNumberOfOptions(), HtmlOptionItem

getOptionItemIndex

public int getOptionItemIndex(HtmlOptionItem objOptionItem)

Returns the index of the given HtmlOptionItem object. It returns -1 if the object is not found.

Parameters:

objOptionItem - the option item

Returns:

the index of this option item

See Also:

HtmlOptionItem

setMultiple

public void setMultiple(boolean bMultiple)

Sets the list box to either accept multiple selections or a single selection. If true is specified then the list box will allow multiple selections, if false is specified then only one selection can be made.

The html attribute it sets is "multiple".

If false is specified the attribute is cleared.

Parameters:

bMultiple - true if you want multiple selections, false for only one

See Also:

HtmlControlWidget.setBooleanAttribute(String, boolean), isMultiple()

isMultiple

public boolean isMultiple()

Returns whether the list box allows multiple selections.

Returns:

true if multiple selections are allowed, false if only selection is allowed

See Also:

HtmlElement.getBooleanAttribute(String), setMultiple(boolean)

clearSelections

public void clearSelections()

Clears all the selections of this list box.

See Also:

setSelected(int, boolean), isSelected(int)

clearOptions

public void clearOptions()

Clears all the options of the list box.

See Also:

addOption(String, String)

getSelectedIndex

public int getSelectedIndex()

Returns the index of the first selected item or -1 if no item is selected. The first option item has the index 0.

Returns:

the index of the first selected item

See Also:

getSelectedValue(), getSelectedIndicies()

getSelectedValue

public java.lang.String getSelectedValue()

Returns the value of the first selected item or null if no item is selected.

Returns:

the value of the first selected item

See Also:

getSelectedIndex(), getSelectedValues()

setSelected

public void setSelected(int nIndex,
                        boolean bChecked)

Sets the specified option item to be checked or unchecked.

If the list box does not have multiple selections enabled then this method will clear all selections before selecting the new option.

Parameters:

nIndex - the index of the option to check/uncheck

bChecked - true if you want the option checked, false otherwse

See Also:

getOptionItem(int), HtmlOptionItem.setSelected(boolean), clearSelections(), isSelected(int), isMultiple(), setSelected(String,boolean)

setSelected

public void setSelected(java.lang.String sOptionValue,
                        boolean bChecked)

Sets the first option item with the value sOptionValue to be checked or unchecked.

If the list box does not have multiple selections enabled then this method will clear all selections before selecting the new option.

Parameters:

sOptionValue - the value of the option to check/uncheck

bChecked - true if you want the option checked, false otherwse

See Also:

getOptionItem(int), HtmlOptionItem.setSelected(boolean), clearSelections(), isSelected(int), isMultiple(), setSelected(int,boolean)

isSelected

public boolean isSelected(int nIndex)

Indicates if an option item has been selected.

Parameters:

nIndex - the index of the option item you want to query

Returns:

true if the option item at position nIndex is selected, false otherwise

See Also:

setSelected(int, boolean)

getSize

public java.lang.String getSize()

Returns the size of this list box.

Returns:

the size for this element, null is returned if the attribute is not set

See Also:

setSize(String), HtmlElement.getAttribute(String)

setSize

public void setSize(java.lang.String sSize)

Sets the size for this list box. If the size is not set (default) or is set to 1 then the object is rendered as a combo-box. If the size is greater than 1 then the object is rendered as a list box and shows "size" number of option items at any one time.

The html attribute it sets is "size".

If null is specified the attribute is cleared.

Parameters:

sSize - the size for this element

See Also:

HtmlControlWidget.setAttribute(String, String), getSize()

updateData

public void updateData(javax.servlet.http.HttpServletRequest objRequest)

Updates this object with the data submitted from the client. If the submitted data for this list box equals any of the values set in the HtmlOptionItem objects then these options will become checked. If the submitted data does not match the value set in a HtmlOptionItem object then it will become unchecked.

The object will only be updated if the auto-update is on and if the object is visible and not disabled.

Overrides:

updateData in class HtmlControlWidget

Parameters:

objRequest - the request object that contains the user submitted data

See Also:

HtmlOptionItem.getValue(), HtmlWidget.isVisible(), HtmlControlWidget.isDisabled(), HtmlControlWidget.isAutoUpdate(), HtmlControlWidget.getSubmittedDataSet(HttpServletRequest)

getSelectedIndicies

public int[] getSelectedIndicies()

Returns an array of the indicies of the currently selected options

Returns:

an array of the indicies of the selected options

See Also:

getSelectedIndex(), getSelectedValues()

getSelectedValues

public java.lang.String[] getSelectedValues()

Returns an array of the values of the currently selected options

Returns:

an array of the values of the selected options

See Also:

getSelectedValues()

printHtml

public void printHtml(java.io.PrintWriter objWriter,
                      int nOutputType)
               throws java.io.IOException

Prints the html that represents this object to the output stream.

Overrides:

printHtml in class HtmlControlWidget

Parameters:

objWriter - the output stream for a Servlet object

nOutputType - the output type

Throws:

java.io.IOException - if it cannot write the output

printHtml

public void printHtml(javax.servlet.jsp.JspWriter objWriter,
                      int nOutputType)
               throws java.io.IOException

Prints the html that represents this object to the output stream.

Overrides:

printHtml in class HtmlControlWidget

Parameters:

objWriter - the output stream for a Jsp page

nOutputType - the output type

Throws:

java.io.IOException - if it cannot write the output

optionSelected

public Signal optionSelected(java.lang.String sOptionValue)

This signal is emitted when an option is selected. The signal is only emitted if the option was previously unselected.

If the list box allows multiple selections then when updateData(HttpServletRequest) is called each option selection will fire off this signal.

Parameters:

sOptionValue - the value of the item selected

Returns:

the signal object representing this signal

See Also:

optionSelected(int), updateData(HttpServletRequest)

selectionUpdated

public Signal selectionUpdated(java.lang.String[] asNewValues,
                               java.lang.String[] asOldValues)

This signal is emitted when the updateData(HttpServletRequest) method is called on this object and selections have changed.

Parameters:

asNewValues - the values of the new selected items

asOldValues - the values of the old selected items (before update)

Returns:

the signal object representing this signal

See Also:

selectionUpdated(int[], int[])

optionSelected

public Signal optionSelected(int nOptionIndex)

This signal is emitted when an option is selected. The signal is only emitted if the option was previously unselected.

If the list box allows multiple selections then when updateData(HttpServletRequest) is called each option selection will fire off this signal.

Parameters:

nOptionIndex - the index of the item selected

Returns:

the signal object representing this signal

See Also:

optionSelected(String), updateData(HttpServletRequest)

selectionUpdated

public Signal selectionUpdated(int[] anNewSelectedIndicies,
                               int[] anOldSelectedIndicies)

This signal is emitted when the updateData(HttpServletRequest) method is called on this object and selections have changed.

Parameters:

anNewSelectedIndicies - the indicies of the new selected items

anOldSelectedIndicies - the indicies of the old selected items (before update)

Returns:

the signal object representing this signal

See Also:

selectionUpdated(String[], String[])