objectivehtml.htmlwidget
Class HtmlControlWidget

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

Direct Known Subclasses:

HtmlInput, HtmlListBox, HtmlTextArea

public abstract class HtmlControlWidget

extends HtmlWidget

This is the base class of all control widgets. Control widgets are classes that can trigger action events and accept user inputs. Control widgets do not have any children.

All control widgets must have a unique name. The name is used to uniquely identify the widget in the html form and is required to correctly bind the submitted data to the object. The only exception is the HtmlRadioButton object. When HtmlRadioButton objects have the same control name they are grouped together.

If auto-escape is turned on (default) then all textual data will be escaped before being written by the printHtml(output) methods. Special html characters are escaped using the HtmlUtils.htmlSpecialChars(String) method.

If auto-update is turned on (default) then when updateData(request) is called the object will be updated with the submitted user data.

The destroy() method of a HtmlControlWidget object will also free up its control name to be used again by another object.

See Also:

setAutoUpdate(boolean), setAutoEscape(boolean), updateData(HttpServletRequest), HtmlElement.printHtml(JspWriter), HtmlElement.printHtml(PrintWriter), HtmlRadioButton, HtmlUtils.htmlSpecialChars(String)

Field Summary

protected boolean	m_bAutoEscape Indicates whether auto-escape is enabled or not
protected boolean	m_bAutoUpdate Indicates whether auto-update is enabled or not

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

HtmlControlWidget(HtmlContainerWidget objParent, java.lang.String sName, boolean bSkipNameValidation)
Constructs an instance of the HtmlControlWidget object with the specified control name.

Method Summary

Signal	dataSubmitted(java.lang.String sData) This signal is emitted when data is submitted by the user.
Signal	dataSubmitted(java.lang.String[] asData) This signal is emitted when data is submitted by the user.
void	destroy() Deletes itself and frees the control name be used again.
java.lang.String	getName() Returns the control name of for this control widget.
java.lang.String	getOnBlur() Returns the onblur event of this object.
java.lang.String	getOnChange() Returns the onchange event of this object.
java.lang.String	getOnFocus() Returns the onfocus event of this object.
java.lang.String	getOnSelect() Returns the onselect event of this object.
java.lang.String	getSubmittedData(javax.servlet.http.HttpServletRequest objRequest) Retrieves the client submitted data associated with this widget.
java.lang.String[]	getSubmittedDataSet(javax.servlet.http.HttpServletRequest objRequest) Retrieves the client submitted data-set associated with this widget.
java.lang.String	getTabIndex() Returns the tab index of this object.
int	getUpdateOrder() Returns the update order of this control widget
boolean	isAutoEscape() Returns whether the auto-escape feature is on or not.
boolean	isAutoUpdate() Returns whether the auto-update feature is on or not.
boolean	isDisabled() Returns whether this object is disabled or enabled.
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	setAttribute(java.lang.String sName, java.lang.String sValue) Sets an attribute of this object.
void	setAutoEscape(boolean bAutoEscape) Sets the auto-escape feature to be either on (default) or off.
void	setAutoUpdate(boolean bAutoUpdate) Sets the auto-update feature to be either on (default) or off.
void	setBooleanAttribute(java.lang.String sName, boolean bIsOn) Sets a boolean-attribute of this object.
void	setDisabled(boolean bDisabled) Sets the HtmlControlWidget object to be either disabled or enabled.
void	setOnBlur(java.lang.String sOnBlur) Sets the onblur event of this object.
void	setOnChange(java.lang.String sOnChange) Sets the onchange event of this object.
void	setOnFocus(java.lang.String sOnFocus) Sets the onfocus event of this object.
void	setOnSelect(java.lang.String sOnSelect) Sets the onselect event of this object.
void	setTabIndex(java.lang.String sTabIndex) Sets the tab index of this widget.
void	setUpdateOrder(int nUpdateOrder) Sets the update order of this control widget.
void	setVisible(boolean bVisible) Overrides the default protected method to be public.
abstract void	updateData(javax.servlet.http.HttpServletRequest objRequest) Updates the internal state of this control widget with the client submitted data.

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

Field Detail

m_bAutoUpdate

protected boolean m_bAutoUpdate

Indicates whether auto-update is enabled or not

m_bAutoEscape

protected boolean m_bAutoEscape

Indicates whether auto-escape is enabled or not

Constructor Detail

HtmlControlWidget

public HtmlControlWidget(HtmlContainerWidget objParent,
                         java.lang.String sName,
                         boolean bSkipNameValidation)
                  throws InvalidControlNameException,
                         InvalidParentWidgetException,
                         InvalidChildWidgetException

Constructs an instance of the HtmlControlWidget object with the specified control name.

Parameters:

objParent - the parent of this widget

sName - the unique control name

bSkipNameValidation - true if name validation can be skipped, only true for HtmlRadioButton

Throws:

InvalidControlNameException - if the control name is not valid or unique

InvalidParentWidgetException - if the specified parent widget is not valid

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

Method Detail

setVisible

public void setVisible(boolean bVisible)

Overrides the default protected method to be public.

Overrides:

setVisible in class HtmlWidget

Parameters:

bVisible - true to be visible, false to be invisible

See Also:

HtmlWidget.setVisible(boolean)

setAutoUpdate

public void setAutoUpdate(boolean bAutoUpdate)

Sets the auto-update feature to be either on (default) or off.

If auto-update is set as true then when the form is submitted from the client the value of the control widget will be automatically updated when updateData(HttpServletRequest) is called.

If auto-update is set as false then the value of the control widget needs to be manually updated by the programmer. Use this with getSubmittedData(HttpServletRequest) if you want auto-update off.

Parameters:

bAutoUpdate - true if you want auto-update on (default), false otherwise

See Also:

updateData(HttpServletRequest), getSubmittedData(HttpServletRequest), isAutoUpdate()

isAutoUpdate

public boolean isAutoUpdate()

Returns whether the auto-update feature is on or not.

Returns:

true if auto-update is on, false otherwise

See Also:

setAutoUpdate(boolean)

setAutoEscape

public void setAutoEscape(boolean bAutoEscape)

Sets the auto-escape feature to be either on (default) or off. If auto-escape is set as true then the text part of this control widget will have any html entity characters escaped with the HtmlUtils.htmlSpecialChars(String) method. See the documentation on each control widget for exact attribute or tag data that is escaped.

Parameters:

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

See Also:

HtmlUtils.htmlSpecialChars(String), isAutoEscape()

isAutoEscape

public boolean isAutoEscape()

Returns whether the auto-escape feature is on or not.

Returns:

true if auto-escape is on, false otherwise

See Also:

setAutoEscape(boolean)

setUpdateOrder

public void setUpdateOrder(int nUpdateOrder)

Sets the update order of this control widget. The update order is used by the HtmlForm object when it refreshes the state of the form objects with the updateData(HttpServletRequest) method. The order these objects are updated with the submitted data is done according to this order. The control widgets with lowest update order values are updated first (0 being the lowest). If 2 or more control widgets have the same update order then they are updated accordingly to their natural order. The natural order is simply starting from the top-left of the form, going right first, then downwards.

The default update order is 0 for all control widgets.

If a negative number is given the update order is modified to be 0.

Parameters:

nUpdateOrder - the update order

See Also:

getUpdateOrder(), HtmlForm.updateData(HttpServletRequest)

getUpdateOrder

public int getUpdateOrder()

Returns the update order of this control widget

Returns:

the udpate order

See Also:

setUpdateOrder(int)

updateData

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

Updates the internal state of this control widget with the client submitted data. The method is normally called by the HtmlForm object when it needs to update all the fields in the form with the submitted data from the client. This method only does something when the auto-update feature is turned on. The method is virtual and needs to implemented by all child widgets.

Parameters:

objRequest - the current request object with the client submitted data

getSubmittedData

public java.lang.String getSubmittedData(javax.servlet.http.HttpServletRequest objRequest)

Retrieves the client submitted data associated with this widget. Data from the client is bound to this object via its control name.

Normally you will not have to explicity use this method unless you are not using the auto-update feature.

Parameters:

objRequest - the current request object with the client submitted data

Returns:

the submitted data associated with this control widget, null if no data was submitted for this control widget (null is different from an empty string)

See Also:

setAutoUpdate(boolean), getName(), getSubmittedDataSet(HttpServletRequest)

getSubmittedDataSet

public java.lang.String[] getSubmittedDataSet(javax.servlet.http.HttpServletRequest objRequest)

Retrieves the client submitted data-set associated with this widget. Data from the client is bound to this object via its control name.

Normally you will not have to explicity use this method unless you are not using the auto-update feature.

Parameters:

objRequest - the current request object with the client submitted data

Returns:

the submitted data-set associated with this control widget, null if no data was submitted for this control widget (null is different from an empty string)

See Also:

setAutoUpdate(boolean), getName(), getSubmittedData(HttpServletRequest)

getName

public java.lang.String getName()

Returns the control name of for this control widget. The value it returns is the value from "name" attribute.

Returns:

its unique control name

setDisabled

public void setDisabled(boolean bDisabled)

Sets the HtmlControlWidget object to be either disabled or enabled. When a HtmlControlWidget object is disabled, the user will not be able to interact with the object. This is normally useful when you wish to display some read-only data to the user. Note however, not all browsers correctly support this feature. Netscape 4.x does not support this feature, IE 4.x and higher and Netscape 6.x does support this feature.

When a control widget is disabled, its internal state will not be updated by the updateData(HttpServletRequest) method.

The html attribute that it sets is "disabled".

Parameters:

bDisabled - true indicates disabled, false indicates enabled

See Also:

updateData(HttpServletRequest), isDisabled()

isDisabled

public boolean isDisabled()

Returns whether this object is disabled or enabled.

Returns:

true if the object is not disabled, false otherwise

See Also:

setDisabled(boolean)

setTabIndex

public void setTabIndex(java.lang.String sTabIndex)

Sets the tab index of this widget. If this control widget is in focus, then pressing tab will move the focus to the control widget that has the lowest tax index but that is greater than the tax index of itself. Use this attribute to organise the tab sequence of your form.

The html attribute that it sets is "tabindex".

Parameters:

sTabIndex - the tab index for this html element if null is specified then this attribute will be cleared

See Also:

getTabIndex()

getTabIndex

public java.lang.String getTabIndex()

Returns the tab index of this object.

Returns:

the tab index for this html element, null is returned if the attribute is not set

See Also:

setTabIndex(String)

setOnFocus

public void setOnFocus(java.lang.String sOnFocus)

Sets the onfocus event of this object.

The html attribute it sets is "onfocus".

Parameters:

sOnFocus - the onfocus event for this html element, if null is specified then this attribute will be cleared

See Also:

getOnFocus()

getOnFocus

public java.lang.String getOnFocus()

Returns the onfocus event of this object.

Returns:

the onfocus event for this html element, null is returned if the attribute is not set

See Also:

setOnFocus(String)

setOnBlur

public void setOnBlur(java.lang.String sOnBlur)

Sets the onblur event of this object.

The html attribute it sets is "onblur".

Parameters:

sOnBlur - the onblur event for this html element if null is specified then this attribute will be cleared

See Also:

getOnBlur()

getOnBlur

public java.lang.String getOnBlur()

Returns the onblur event of this object.

The html attribute it gets is "onblur".

Returns:

the onblur event for this html element, null is returned the attribute is not set

See Also:

setOnBlur(String)

setOnSelect

public void setOnSelect(java.lang.String sOnSelect)

Sets the onselect event of this object.

The html attribute it sets is "onselect".

Parameters:

sOnSelect - the onselect event for this html element if null is specified then this attribute will be cleared

See Also:

getOnSelect()

getOnSelect

public java.lang.String getOnSelect()

Returns the onselect event of this object.

The html attribute it gets is "onselect".

Returns:

the onselect event for this html element, null is returned the attribute is not set

See Also:

setOnSelect(String)

setOnChange

public void setOnChange(java.lang.String sOnChange)

Sets the onchange event of this object.

The html attribute it sets is "onchange".

Parameters:

sOnChange - the onchange event for this html element if null is specified then this attribute will be cleared

See Also:

getOnChange()

getOnChange

public java.lang.String getOnChange()

Returns the onchange event of this object.

The html attribute it gets is "onchange".

Returns:

the onchange event for this html element, null is returned the attribute is not set

See Also:

setOnChange(String)

setAttribute

public void setAttribute(java.lang.String sName,
                         java.lang.String sValue)
                  throws InvalidAttributeException

Sets an attribute of this object.

This overrides the parent version of this method to block the "name" attribute being modified. If you attempt to modify the "name" attribute then the InvalidAttributeException is thrown.

Overrides:

setAttribute in class HtmlElement

Parameters:

sName - the name of the attribute

sValue - the value of the attribute, if null is specified then the attribute will be cleared

See Also:

HtmlElement.setAttribute(String, String), setBooleanAttribute(String, boolean)

setBooleanAttribute

public void setBooleanAttribute(java.lang.String sName,
                                boolean bIsOn)
                         throws InvalidAttributeException

Sets a boolean-attribute of this object.

This overrides the parent version of this method to block the "name" attribute being modified. If you attempt to modify the "name" attribute then the InvalidAttributeException is thrown.

Overrides:

setBooleanAttribute in class HtmlElement

Parameters:

sName - the name of the attribute

bIsOn - true if attribute should be set, if false is specified then the attribute is cleared

See Also:

HtmlElement.setBooleanAttribute(String, boolean), setAttribute(String, String)

destroy

public void destroy()

Deletes itself and frees the control name be used again.

Overrides:

destroy in class HtmlWidget

Following copied from class: objectivehtml.htmlwidget.HtmlWidget

See Also:

HtmlWidget.isDestroyed()

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 HtmlElement

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 HtmlElement

Parameters:

objWriter - the output stream for a Jsp page

nOutputType - the output type

Throws:

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

dataSubmitted

public Signal dataSubmitted(java.lang.String sData)

This signal is emitted when data is submitted by the user. The signal is emitted when the updateData(HttpServletRequest) method is called and is emitted just before the state of each control widget is updated with the new submitted data. The signal is only emitted when the control widget is visible, not disabled and not in read-only mode. The signal is emitted regardless of whether auto-update is on or off. If multiple-values are submitted for a control object then sData will be the first value.

Parameters:

sData - the new submitted data

Returns:

the signal

See Also:

HtmlWidget.isVisible(), isDisabled(), HtmlTextBox.isReadOnly(), HtmlTextArea.isReadOnly(), dataSubmitted(String[])

dataSubmitted

public Signal dataSubmitted(java.lang.String[] asData)

This signal is emitted when data is submitted by the user. The signal is emitted when the updateData(HttpServletRequest) method is called and is emitted just before the state of each control widget is updated with the new submitted data. The signal is only emitted when the control widget is visible, not disabled and not in read-only mode. The signal is emitted regardless of whether auto-update is on or off.

This overloaded version should be used when control widgets are expecting more than one submitted value (e.g. HtmlListBox). If there is only one submitted value then asData will be an array of length 1.

This method also provides a convenient way for data to be filtered or cleaned up before being used to update the state of a control widget. The array of String objects (asData) emitted by the signal is the same array that will be used by each control widget to update their internal state. For e.g. you may need to run an encode(String) method on all submitted data. This can be done like this:

	public void encode(String[] asData)
	{
		if (asData != null)
		{
			for (int i=0; i<asData.length; i++)
			{
				asData[i] = encode(asData[i]);
			}
		}
	}
 

Simply connect this slot method to the "dataSubmitted(String[])" signal of all the control widgets that you need to encode.

Parameters:

asData - the array of new submitted data

Returns:

the signal

See Also:

HtmlWidget.isVisible(), isDisabled(), HtmlTextBox.isReadOnly(), HtmlTextArea.isReadOnly(), dataSubmitted(String)