|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.zkoss.zk.ui.AbstractComponent
org.zkoss.zk.ui.HtmlBasedComponent
org.zkoss.zul.impl.XulElement
org.zkoss.zul.impl.InputElement
public abstract class InputElement
A skeletal implementation of an input box.
Events: onChange, onChanging, onFocus, onBlur, onSelection.
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 |
---|
_height, _left, _top, _width, _zclass |
Fields inherited from class org.zkoss.zk.ui.AbstractComponent |
---|
_visible |
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. |
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. |
int |
getMaxlength()
Returns the maxlength. |
java.lang.String |
getName()
Returns the name of this component. |
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. |
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 |
setInplace(boolean inplace)
Sets to enable the inplace-editing function that the look and feel is like a label. |
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 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 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, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip |
Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent |
---|
focus, getDraggable, getDroppable, getHeight, getHflex, getLeft, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZindex, getZIndex, newExtraCtrl, setClass, setDraggable, setDroppable, setFocus, setHeight, setHflex, setLeft, setSclass, setStyle, setTooltiptext, setTop, setVflex, setWidth, setZclass, setZindex, setZIndex |
Methods inherited from class java.lang.Object |
---|
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Methods inherited from interface org.zkoss.zul.impl.api.XulElement |
---|
getAction, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip |
Methods inherited from interface org.zkoss.zk.ui.api.HtmlBasedComponent |
---|
focus, getHeight, getLeft, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZclass, getZindex, getZIndex, setDraggable, setDroppable, setFocus, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex |
Methods inherited from interface org.zkoss.zk.ui.ext.Scope |
---|
addScopeListener, getAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute |
Field Detail |
---|
protected java.lang.Object _value
Constructor Detail |
---|
public InputElement()
Method Detail |
---|
public void setInplace(boolean inplace)
public boolean isInplace()
default: false.
public boolean isDisabled()
Default: false.
isDisabled
in interface InputElement
public void setDisabled(boolean disabled)
setDisabled
in interface InputElement
public boolean isReadonly()
Default: false.
isReadonly
in interface InputElement
public void setReadonly(boolean readonly)
setReadonly
in interface InputElement
public java.lang.String getName()
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.
getName
in interface InputElement
public void setName(java.lang.String name)
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
in interface InputElement
name
- the name of this component.public java.lang.String getErrorMessage()
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()
.
getErrorMessage
in interface InputElement
public void clearErrorMessage(boolean revalidateRequired)
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).
clearErrorMessage
in interface InputElement
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 constrcuted, the initial value
is assumed to be "not-validated-yet".public void clearErrorMessage()
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.
clearErrorMessage
in interface InputElement
clearErrorMessage(boolean)
public java.lang.String getText() throws WrongValueException
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.
getText
in interface InputElement
WrongValueException
- if user entered a wrong valuepublic void setText(java.lang.String value) throws WrongValueException
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.
setText
in interface InputElement
value
- the value; If null, it is considered as empty.
WrongValueException
protected abstract java.lang.Object coerceFromString(java.lang.String value) throws WrongValueException
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.
WrongValueException
protected abstract java.lang.String coerceToString(java.lang.Object value)
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.
protected void validate(java.lang.Object value) throws WrongValueException
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.
WrongValueException
protected WrongValueException showCustomError(WrongValueException ex)
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.
ex
- the exception, or null to clean up the error.
public int getMaxlength()
Default: 0 (non-postive means unlimited).
getMaxlength
in interface InputElement
public void setMaxlength(int maxlength)
setMaxlength
in interface InputElement
public int getCols()
Default: 0 (non-positive means the same as browser's default).
getCols
in interface InputElement
public void setCols(int cols) throws WrongValueException
setCols
in interface InputElement
WrongValueException
public int getTabindex()
Default: -1 (means the same as browser's default).
getTabindex
in interface InputElement
public void setTabindex(int tabindex) throws WrongValueException
setTabindex
in interface InputElement
WrongValueException
public boolean isMultiline()
Default: false.
isMultiline
in interface InputElement
public java.lang.String getType()
Default: text.
getType
in interface InputElement
public void select()
select
in interface InputElement
public void setConstraint(java.lang.String constr)
setConstraint
in interface InputElement
public void setConstraint(Constraint constr)
Constrainted
Default: null (means no constraint all all).
setConstraint
in interface Constrainted
public Constraint getConstraint()
Constrainted
getConstraint
in interface Constrainted
protected java.lang.Object getTargetValue() throws WrongValueException
Intbox.getValue()
is the same
as this method except with a different signature.
It invokes checkUserError()
to ensure no user error.
WrongValueException
- if the user entered a wrong valuegetText()
public java.lang.Object getRawValue()
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.
getRawValue
in interface InputElement
getRawText()
,
getText()
,
setRawValue(java.lang.Object)
public java.lang.String getRawText()
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.
getRawText
in interface InputElement
getRawValue()
,
getText()
public void setRawValue(java.lang.Object value)
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).
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-valiation, you have to invoke
clearErrorMessage()
.
Like setValue, the result is returned back to the server
by calling getText()
.
setRawValue
in interface InputElement
getRawValue()
protected void setValueDirectly(java.lang.Object value)
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.
public boolean isValid()
isValid
in interface InputElement
public void setSelectedText(int start, int end, java.lang.String newtxt, boolean isHighLight)
setSelectedText
in interface InputElement
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.public void setSelectionRange(int start, int end)
Set both arguments to the same value to move the cursor to the corresponding position without selecting text.
setSelectionRange
in interface InputElement
start
- the start position of the text (included)end
- the end position of the text (excluded)protected void checkUserError() throws WrongValueException
getText()
or getTargetValue()
is
called.
Derives rarely need to access this method if they use only
getText()
and getTargetValue()
.
WrongValueException
protected boolean isChildable()
isChildable
in class AbstractComponent
public WrongValueException onWrongValue(WrongValueException ex)
AbstractComponent
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.
onWrongValue
in interface ComponentCtrl
onWrongValue
in class AbstractComponent
ex
- the exception being thrown (never null)
public void service(AuRequest request, boolean everError)
Default: in addition to what are handled by HtmlBasedComponent.service(org.zkoss.zk.au.AuRequest, boolean)
,
it also handles onChange, onChanging and onError.
service
in interface ComponentCtrl
service
in class HtmlBasedComponent
everError
- whether any error ever occured before
processing this request.AbstractComponent.setAuService(org.zkoss.zk.au.AuService)
protected void renderProperties(ContentRenderer renderer) throws java.io.IOException
HtmlBasedComponent
See also Render Special Properties
renderProperties
in class XulElement
java.io.IOException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |