org.zkoss.zul.impl
Class InputElement

java.lang.Object
  extended by org.zkoss.zk.ui.AbstractComponent
      extended by org.zkoss.zk.ui.HtmlBasedComponent
          extended by org.zkoss.zul.impl.XulElement
              extended by org.zkoss.zul.impl.InputElement
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, Component, Disable, Readonly, Scope, ComponentCtrl, Constrainted
Direct Known Subclasses:
FormatInputElement, Textbox

public abstract class InputElement
extends XulElement
implements Constrainted, Readonly, Disable

A skeletal implementation of an input box.

Events: onChange, onChanging, onFocus, onBlur, onSelection.

Author:
tomyeh
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class org.zkoss.zk.ui.HtmlBasedComponent
HtmlBasedComponent.ExtraCtrl
 
Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent
AbstractComponent.Children
 
Field Summary
protected  java.lang.Object _value
          The value.
 
Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent
_zclass
 
Fields inherited from interface org.zkoss.zk.ui.Component
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE
 
Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl
CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE
 
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.
 void clearErrorMessage(boolean revalidateRequired)
          Clears the error message.
 java.lang.Object clone()
          Clones the component.
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).
 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.
 boolean getInstant()
          Returns true if onChange event is sent as soon as user types in the input component.
 int getMaxlength()
          Returns the maxlength.
 java.lang.String getName()
          Returns the name of this component.
 java.lang.String getPlaceholder()
          Returns the placeholder text
 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 isChildable()
          Not childable.
 boolean isDisabled()
          Returns whether it is disabled.
 boolean isInplace()
          Returns whether enable the inplace-editing.
 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 marshall(java.lang.Object value)
          Marshall value to be sent to the client if needed.
 WrongValueException onWrongValue(WrongValueException ex)
          Notifies that an WrongValueException instance is thrown, and WrongValueException.getComponent() is this component.
protected  void renderProperties(ContentRenderer renderer)
          Renders the content of this component, excluding the enclosing tags and children.
 void select()
          Selects the whole text in this input.
 void service(AuRequest request, boolean everError)
          Processes an AU request.
 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 setErrorMessage(java.lang.String errmsg)
          Associates an error message to this input.
 void setInplace(boolean inplace)
          Sets to enable the inplace-editing function that the look and feel is like a label.
 void setInstant(boolean instant)
          Sets the instant attribute.
 void setMaxlength(int maxlength)
          Sets the maxlength.
 void setName(java.lang.String name)
          Sets the name of this component.
 void setPlaceholder(java.lang.String placeholder)
          Sets the placeholder text that is displayed when input is empty.
 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 beginning 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  void setValueDirectly(java.lang.Object value)
          Sets the value directly.
protected  WrongValueException showCustomError(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 constraint implements CustomConstraint.
protected  java.lang.Object unmarshall(java.lang.Object value)
          Unmarshall value returned from client if needed.
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
getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip
 
Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent
focus, getAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZindex, getZIndex, setAction, setClass, setDraggable, setDroppable, setFocus, setHeight, setHeightDirectly, setHflex, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTooltiptext, setTop, setTopDirectly, setVflex, setWidth, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly
 
Methods inherited from class org.zkoss.zk.ui.AbstractComponent
addAnnotation, addAnnotation, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addScopeListener, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableClientUpdate, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getChildren, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getStubonly, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, removeScopeListener, render, render, render, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setTemplate, setVisible, setVisibleDirectly, setWidgetAttribute, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, willPassivate, willPassivate, willSerialize, willSerialize
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_value

protected java.lang.Object _value
The value.

Constructor Detail

InputElement

public InputElement()
Method Detail

getPlaceholder

public java.lang.String getPlaceholder()
Returns the placeholder text

Since:
6.5.0

setPlaceholder

public void setPlaceholder(java.lang.String placeholder)
Sets the placeholder text that is displayed when input is empty. Only works for browsers supporting HTML5.

Since:
6.5.0

setInplace

public void setInplace(boolean inplace)
Sets to enable the inplace-editing function that the look and feel is like a label.

Since:
5.0.0

isInplace

public boolean isInplace()
Returns whether enable the inplace-editing.

default: false.

Since:
5.0.0

isDisabled

public boolean isDisabled()
Returns whether it is disabled.

Default: false.

Specified by:
isDisabled in interface Disable

setDisabled

public void setDisabled(boolean disabled)
Sets whether it is disabled.

Specified by:
setDisabled in interface Disable

isReadonly

public boolean isReadonly()
Returns whether it is readonly.

Default: false.

Specified by:
isReadonly in interface Readonly

setReadonly

public void setReadonly(boolean readonly)
Sets whether it is readonly.

Specified by:
setReadonly in interface 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().


setErrorMessage

public void setErrorMessage(java.lang.String errmsg)
Associates an error message to this input. It will cause the given error message to be shown at the client.

Notice that the application rarely invokes this method. Rather, throw WrongValueException instead.

Notice it does not invoke CustomConstraint.showCustomError(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.WrongValueException) even if getConstraint() implements CustomConstraint.

Since:
5.0.4

clearErrorMessage

public void clearErrorMessage(boolean revalidateRequired)
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 manually 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 second 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).

Parameters:
revalidateRequired - whether to re-validate the current value when getText() or others (such as Intbox.getValue()) is called. If false, the current value is assumed to be correct and the following invocation to getText() or others (such as Intbox.getValue()) won't check the value again. Note: when an input element is constructed, the initial value is assumed to be "not-validated-yet".
Since:
3.0.1

clearErrorMessage

public void clearErrorMessage()
Clears the error message. It is the same as clearErrorMessage(false). That is, the current value is assumed to be correct. getText() or others (such as Intbox.getValue()) won't re-validate it again.

The error message is cleared automatically, so you rarely need to call this method.

See Also:
clearErrorMessage(boolean)

getText

public java.lang.String getText()
                         throws 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:
WrongValueException - if user entered a wrong value

setText

public void setText(java.lang.String value)
             throws 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) first 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:
WrongValueException

coerceFromString

protected abstract java.lang.Object coerceFromString(java.lang.String value)
                                              throws 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:
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 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:
WrongValueException

showCustomError

protected WrongValueException showCustomError(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 constraint 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-positive means unlimited).


setMaxlength

public void setMaxlength(int maxlength)
Sets the maxlength.

The length includes the format, if specified.


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 WrongValueException
Sets the cols.

Throws:
WrongValueException

getTabindex

public int getTabindex()
Returns the tab order of this component.

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


setTabindex

public void setTabindex(int tabindex)
                 throws WrongValueException
Sets the tab order of this component.

Throws:
WrongValueException

getInstant

public boolean getInstant()
Returns true if onChange event is sent as soon as user types in the input component.

Default: false

Since:
6.0.0

setInstant

public void setInstant(boolean instant)
Sets the instant attribute. When the attribute is true, onChange event will be fired as soon as user type in the input component.

Since:
6.0.0

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 Constraint getConstraint()
Description copied from interface: Constrainted
Returns the constraint, or null if no constraint at all.

Specified by:
getConstraint in interface Constrainted

getTargetValue

protected java.lang.Object getTargetValue()
                                   throws 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:
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 constraint).

Note: since 3.0.1, the value will be re-validate again if getText() or others (such as Intbox.getValue()) is called. In other words, it is assumed that the specified value is not validated yet -- the same state when this component is created. If you want to avoid the re-validation, you have to invoke clearErrorMessage().

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

See Also:
getRawValue()

setValueDirectly

protected void setValueDirectly(java.lang.Object value)
Sets the value directly. Note: Unlike setRawValue(java.lang.Object) (nor setValue), this method assigns the value directly without clearing error message or synchronizing with the client.

It is usually used only the constructor. Though it is also OK to use setRawValue(java.lang.Object) in the constructor, this method has better performance.

Since:
3.0.3

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 beginning 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 highlight 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 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 method is called when getText() or getTargetValue() is called.

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

Throws:
WrongValueException

isChildable

protected boolean isChildable()
Not childable.

Overrides:
isChildable in class AbstractComponent

onWrongValue

public WrongValueException onWrongValue(WrongValueException ex)
Description copied from class: AbstractComponent
Notifies that an WrongValueException instance is thrown, and WrongValueException.getComponent() is this component. It is a callback and the component can store the error message, show up the custom information, or even 'eat' the exception.

Default: does nothing but returns ex.

Specified by:
onWrongValue in interface ComponentCtrl
Overrides:
onWrongValue in class AbstractComponent
Parameters:
ex - the exception being thrown (never null)
Returns:
the exception to throw, or null to ignore the exception In most cases, just return ex

marshall

protected java.lang.Object marshall(java.lang.Object value)
Marshall value to be sent to the client if needed.

Overrides it if the value to be sent to the client is not JSON Compatible.

Parameters:
value - the value to be sent to the client
Returns:
the marshalled value
Since:
5.0.5

unmarshall

protected java.lang.Object unmarshall(java.lang.Object value)
Unmarshall value returned from client if needed.

Overrides it if the value returned is not JSON Compatible.

Parameters:
value - the value returned from client
Returns:
the unmarshalled value
Since:
5.0.5

service

public void service(AuRequest request,
                    boolean everError)
Processes an AU request.

Default: in addition to what are handled by HtmlBasedComponent.service(org.zkoss.zk.au.AuRequest, boolean), it also handles onChange, onChanging and onError.

Specified by:
service in interface ComponentCtrl
Overrides:
service in class HtmlBasedComponent
everError - whether any error ever occurred before processing this request.
Since:
5.0.0
See Also:
AbstractComponent.setAuService(org.zkoss.zk.au.AuService)

renderProperties

protected void renderProperties(ContentRenderer renderer)
                         throws java.io.IOException
Description copied from class: HtmlBasedComponent
Renders the content of this component, excluding the enclosing tags and children.

See also ZK Client-side Reference: Property Rendering

Overrides:
renderProperties in class XulElement
Throws:
java.io.IOException

clone

public java.lang.Object clone()
Description copied from interface: Component
Clones the component. All of its children and descendants are cloned. Also, ID are preserved.

Specified by:
clone in interface Component
Overrides:
clone in class XulElement
Returns:
the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.


Copyright © 2005-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo