org.zkoss.zul.impl
Class InputElement

java.lang.Object
  org.zkoss.zk.ui.AbstractComponent
      org.zkoss.zk.ui.HtmlBasedComponent
          org.zkoss.zul.impl.XulElement
              org.zkoss.zul.impl.InputElement

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.sys.ComponentCtrl, Constrainted

Direct Known Subclasses:

FormatInputElement, Textbox

public abstract class InputElement
extends XulElement
implements Constrainted

A skeletal implementation of an input box.

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

protected class

InputElement.ExtraCtrl A utility class to implement AbstractComponent.getExtraCtrl().

Field Summary

Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

RS_NO_DISPLAY, RS_NO_HEIGHT, RS_NO_WIDTH

Fields inherited from interface org.zkoss.zk.ui.Component

APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

Constructor Summary

InputElement()

Method Summary

protected void	checkUserError() Checks whether user entered a wrong value (and not correct it yet).
void	clearErrorMessage() Clears the error message.
protected abstract java.lang.Object	coerceFromString(java.lang.String value) Coerces the value passed to setText(java.lang.String).
protected abstract java.lang.String	coerceToString(java.lang.Object value) Coerces the value passed to setText(java.lang.String).
java.lang.String	getAreaText() Returns the text for HTML AREA (Internal Use Only).
int	getCols() Returns the cols.
Constraint	getConstraint() Returns the constraint, or null if no constraint at all.
java.lang.String	getErrorMessage() Returns the error message that is caused when user entered invalid value, or null if no error at all.
java.lang.String	getInnerAttrs() Generates the Client-Side-Action attributes to the interior tag.
int	getMaxlength() Returns the maxlength.
java.lang.String	getName() Returns the name of this component.
java.lang.String	getOuterAttrs()
java.lang.String	getRawText() Returns the text directly without checking whether any error message not yet fixed.
java.lang.Object	getRawValue() Returns the raw value directly with checking whether any error message not yet fixed.
int	getTabindex() Returns the tab order of this component.
protected java.lang.Object	getTargetValue() Returns the value in the targeting type.
java.lang.String	getText() Returns the value in the String format.
java.lang.String	getType() Returns the type.
protected boolean	isAsapRequired(java.lang.String evtnm) Returns whether to send back the request of the specified event immediately -- non-deferable.
boolean	isChildable() Not childable.
boolean	isDisabled() Returns whether it is disabled.
boolean	isMultiline() Returns whether it is multiline.
boolean	isReadonly() Returns whether it is readonly.
boolean	isValid() Returns the current content of this input is correct.
protected java.lang.Object	newExtraCtrl()
org.zkoss.zk.ui.WrongValueException	onWrongValue(org.zkoss.zk.ui.WrongValueException ex)
void	select() Selects the whole text in this input.
void	setCols(int cols) Sets the cols.
void	setConstraint(Constraint constr) Sets the constraint.
void	setConstraint(java.lang.String constr)
void	setDisabled(boolean disabled) Sets whether it is disabled.
void	setMaxlength(int maxlength) Sets the maxlength.
void	setName(java.lang.String name) Sets the name of this component.
void	setRawValue(java.lang.Object value) Sets the raw value directly.
void	setReadonly(boolean readonly) Sets whether it is readonly.
void	setSelectedText(int start, int end, java.lang.String newtxt, boolean isHighLight) Sets the text of this InputElement to the specified text which is begining with the new start point and ending with the new end point.
void	setSelectionRange(int start, int end) Sets the selection end to the specified position and the selection start to the specified position.
void	setTabindex(int tabindex) Sets the tab order of this component.
void	setText(java.lang.String value) Sets the value in the String format.
protected org.zkoss.zk.ui.WrongValueException	showCustomError(org.zkoss.zk.ui.WrongValueException ex) Shows the error message in the custom way by calling (CustomConstraint.showCustomError(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.WrongValueException), if the contraint implements CustomConstraint.
protected void	validate(java.lang.Object value) Validates the value returned by coerceFromString(java.lang.String).

Methods inherited from class org.zkoss.zul.impl.XulElement

getAction, getAllOnClickAttrs, getContext, getPopup, getTooltip, setAction, setContext, setPopup, setTooltip

Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

addEventListener, appendAsapAttr, focus, getDraggable, getDroppable, getHeight, getLeft, getRealStyle, getRealStyleFlags, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZIndex, removeEventListener, setClass, setDraggable, setDroppable, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZIndex

Methods inherited from class org.zkoss.zk.ui.AbstractComponent

addAnnotation, addAnnotation, addEventHandler, addSharedAnnotationMap, addSharedEventHandlerMap, appendChild, applyProperties, clone, containsVariable, detach, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getEventHandler, getExtraCtrl, getFellow, getFellowIfAny, getId, getListenerIterator, getMold, getMoldURI, getNamespace, getPage, getParent, getPropagatee, getRoot, getSpaceOwner, getUuid, getVariable, insertBefore, invalidate, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onDrawNewChild, redraw, removeAttribute, removeAttribute, removeChild, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setMold, setPage, setParent, setVariable, setVisible, smartUpdate, smartUpdate, smartUpdate, toString, unsetVariable

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InputElement

public InputElement()

Method Detail

isDisabled

public boolean isDisabled()

Returns whether it is disabled.

Default: false.

setDisabled

public void setDisabled(boolean disabled)

Sets whether it is disabled.

isReadonly

public boolean isReadonly()

Returns whether it is readonly.

Default: false.

setReadonly

public void setReadonly(boolean readonly)

Sets whether it is readonly.

getName

public java.lang.String getName()

Returns the name of this component.

Default: null.

Don't use this method if your application is purely based on ZK's event-driven model.

The name is used only to work with "legacy" Web application that handles user's request by servlets. It works only with HTTP/HTML-based browsers. It doesn't work with other kind of clients.

setName

public void setName(java.lang.String name)

Sets the name of this component.

Don't use this method if your application is purely based on ZK's event-driven model.

The name is used only to work with "legacy" Web application that handles user's request by servlets. It works only with HTTP/HTML-based browsers. It doesn't work with other kind of clients.

Parameters:

name - the name of this component.

getErrorMessage

public java.lang.String getErrorMessage()

Returns the error message that is caused when user entered invalid value, or null if no error at all.

The error message is set when user has entered a wrong value, or setValue is called with a wrong value. It is cleared once a correct value is assigned.

If the error message is set, we say this input is in the error mode. Any following invocation to getText() or getValue will throw any exception. Example, Textbox.getValue() and Intbox.getValue().

clearErrorMessage

public void clearErrorMessage()

Clears the error message.

The error message is cleared automatically, so you rarely need to call this method. However, if a constraint depends on multiple input fields and the error can be corrected by changing one of these fields, then you may have to clear the error message manullay by invoking this method.

For example, assume you have two Intbox and want the value of the first one to be smaller than that of the second one. Then, you have to call this method for the second intbox once the validation of the first intbox succeeds, and vice versa. Otherwise, the error message for the seoncd intbox remains if the user fixed the error by lowering down the value of the first one Why? The second intbox got no idea to clear the error message (since its content doesn't change).

getText

public java.lang.String getText()
                         throws org.zkoss.zk.ui.WrongValueException

Returns the value in the String format. In most case, you shall use the setValue method instead, e.g., Textbox.getValue() and Intbox.getValue().

It invokes checkUserError() to ensure no user error.

It invokes coerceToString(java.lang.Object) to convert the stored value into a string.

Throws:

org.zkoss.zk.ui.WrongValueException - if user entered a wrong value

setText

public void setText(java.lang.String value)
             throws org.zkoss.zk.ui.WrongValueException

Sets the value in the String format. In most case, you shall use the setValue method instead, e.g., Textbox.setValue(java.lang.String) and Intbox.setValue(java.lang.Integer).

It invokes coerceFromString(java.lang.String) fisrt and then validate(java.lang.Object). Derives might override them for type conversion and special validation.

Parameters:

value - the value; If null, it is considered as empty.

Throws:

org.zkoss.zk.ui.WrongValueException

coerceFromString

protected abstract java.lang.Object coerceFromString(java.lang.String value)
                                              throws org.zkoss.zk.ui.WrongValueException

Coerces the value passed to setText(java.lang.String).

Deriving note:
If you want to store the value in other type, say BigDecimal, you have to override coerceToString(java.lang.Object) and coerceFromString(java.lang.String) to convert between a string and your targeting type.

Moreover, when Textbox is called, it calls this method with value = null. Derives shall handle this case properly.

Throws:

org.zkoss.zk.ui.WrongValueException

coerceToString

protected abstract java.lang.String coerceToString(java.lang.Object value)

Coerces the value passed to setText(java.lang.String).

Default: convert null to an empty string.

Deriving note:
If you want to store the value in other type, say BigDecimal, you have to override coerceToString(java.lang.Object) and coerceFromString(java.lang.String) to convert between a string and your targeting type.

validate

protected void validate(java.lang.Object value)
                 throws org.zkoss.zk.ui.WrongValueException

Validates the value returned by coerceFromString(java.lang.String).

Default: use getConstraint()'s Constraint.validate(org.zkoss.zk.ui.Component, java.lang.Object), if not null.

You rarely need to override this method.

Throws:

org.zkoss.zk.ui.WrongValueException

showCustomError

protected org.zkoss.zk.ui.WrongValueException showCustomError(org.zkoss.zk.ui.WrongValueException ex)

Shows the error message in the custom way by calling (CustomConstraint.showCustomError(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.WrongValueException), if the contraint implements CustomConstraint.

Derived class shall call this method before throwing WrongValueException, such that the constraint, if any, has a chance to show the error message in a custom way.

Parameters:

ex - the exception, or null to clean up the error.

Returns:

the exception (ex)

getMaxlength

public int getMaxlength()

Returns the maxlength.

Default: 0 (non-postive means unlimited).

setMaxlength

public void setMaxlength(int maxlength)

Sets the maxlength.

getCols

public int getCols()

Returns the cols.

Default: 0 (non-positive means the same as browser's default).

setCols

public void setCols(int cols)
             throws org.zkoss.zk.ui.WrongValueException

Sets the cols.

Throws:

org.zkoss.zk.ui.WrongValueException

getTabindex

public int getTabindex()

Returns the tab order of this component.

Default: -1 (means the same as browser's default).

setTabindex

public void setTabindex(int tabindex)
                 throws org.zkoss.zk.ui.WrongValueException

Sets the tab order of this component.

Throws:

org.zkoss.zk.ui.WrongValueException

isMultiline

public boolean isMultiline()

Returns whether it is multiline.

Default: false.

getType

public java.lang.String getType()

Returns the type.

Default: text.

select

public void select()

Selects the whole text in this input.

setConstraint

public void setConstraint(java.lang.String constr)

setConstraint

public void setConstraint(Constraint constr)

Description copied from interface: Constrainted

Sets the constraint.

Default: null (means no constraint all all).

Specified by:

setConstraint in interface Constrainted

getConstraint

public final Constraint getConstraint()

Description copied from interface: Constrainted

Returns the constraint, or null if no constraint at all.

Specified by:

getConstraint in interface Constrainted

isAsapRequired

protected boolean isAsapRequired(java.lang.String evtnm)

Returns whether to send back the request of the specified event immediately -- non-deferable. Returns true if you want the component (on the server) to process the event immediately.

Default: Besides super.isAsapRequired(evtnm), it also returns true if evtnm is Events.ON_CHANGE, getConstraint() is not null, and ClientConstraint.getClientValidation() is null.

Overrides:

isAsapRequired in class org.zkoss.zk.ui.HtmlBasedComponent

getInnerAttrs

public java.lang.String getInnerAttrs()

Description copied from class: XulElement

Generates the Client-Side-Action attributes to the interior tag. Reason: onfocus is the main use.

Overrides:

getInnerAttrs in class XulElement

getOuterAttrs

public java.lang.String getOuterAttrs()

Overrides:

getOuterAttrs in class XulElement

getTargetValue

protected java.lang.Object getTargetValue()
                                   throws org.zkoss.zk.ui.WrongValueException

Returns the value in the targeting type. It is used by the deriving class to implement the getValue method. For example, Intbox.getValue() is the same as this method except with a different signature.

It invokes checkUserError() to ensure no user error.

Throws:

org.zkoss.zk.ui.WrongValueException - if the user entered a wrong value

See Also:

getText()

getRawValue

public java.lang.Object getRawValue()

Returns the raw value directly with checking whether any error message not yet fixed. In other words, it does NOT invoke checkUserError().

Note: if the user entered an incorrect value (i.e., caused WrongValueException), the incorrect value doesn't be stored so this method returned the last correct value.

See Also:

getRawText(), getText(), setRawValue(java.lang.Object)

getRawText

public java.lang.String getRawText()

Returns the text directly without checking whether any error message not yet fixed. In other words, it does NOT invoke checkUserError().

Note: if the user entered an incorrect value (i.e., caused WrongValueException), the incorrect value doesn't be stored so this method returned the last correct value.

See Also:

getRawValue(), getText()

setRawValue

public void setRawValue(java.lang.Object value)

Sets the raw value directly. The caller must make sure the value is correct (or intend to be incorrect), because this method doesn't do any validation.

If you feel confusing with setValue, such as Textbox.setValue(java.lang.String), it is usually better to use setValue instead. This method is reserved for developer that really want to set an 'illegal' value (such as an empty string to a textbox with no-empty contraint).

Like setValue, the result is returned back to the server by calling getText().

See Also:

getRawValue()

isValid

public boolean isValid()

Returns the current content of this input is correct. If the content is not correct, next call to the getvalue method will throws WrongValueException.

setSelectedText

public void setSelectedText(int start,
                            int end,
                            java.lang.String newtxt,
                            boolean isHighLight)

Sets the text of this InputElement to the specified text which is begining with the new start point and ending with the new end point.

Parameters:

start - the start position of the text (included)

end - the end position of the text (excluded)

newtxt - the new text to be set.

isHighLight - Sets whether it will represent highlihgt style or cursor style.If the start point same with the end point always represent cursor style.

setSelectionRange

public void setSelectionRange(int start,
                              int end)

Sets the selection end to the specified position and the selection start to the specified position. The new end point is constrained to be at or after the current selection start. If the new start point is different with the new end point, then will represent the result of highlight in this text.

Set both arguments to the same value to move the cursor to the corresponding position without selecting text.

Parameters:

start - the start position of the text (included)

end - the end position of the text (excluded)

checkUserError

protected void checkUserError()
                       throws org.zkoss.zk.ui.WrongValueException

Checks whether user entered a wrong value (and not correct it yet). Since user might enter a wrong value and moves on to other components, this methid is called when getText() or getTargetValue() is called.

Derives rarely need to access this method if they use only getText() and getTargetValue().

Throws:

org.zkoss.zk.ui.WrongValueException

getAreaText

public java.lang.String getAreaText()

Returns the text for HTML AREA (Internal Use Only).

Used only for component generation. Not for applications.

isChildable

public boolean isChildable()

Not childable.

Specified by:

isChildable in interface org.zkoss.zk.ui.Component

Overrides:

isChildable in class org.zkoss.zk.ui.AbstractComponent

newExtraCtrl

protected java.lang.Object newExtraCtrl()

Overrides:

newExtraCtrl in class org.zkoss.zk.ui.HtmlBasedComponent

onWrongValue

public org.zkoss.zk.ui.WrongValueException onWrongValue(org.zkoss.zk.ui.WrongValueException ex)

Specified by:

onWrongValue in interface org.zkoss.zk.ui.sys.ComponentCtrl

Overrides:

onWrongValue in class org.zkoss.zk.ui.AbstractComponent