org.zkoss.zul.impl.api
Interface InputElement

All Superinterfaces:
java.lang.Cloneable, Component, Constrainted, HtmlBasedComponent, Scope, java.io.Serializable, XulElement
All Known Subinterfaces:
Bandbox, Combobox, Datebox, Decimalbox, Doublebox, FormatInputElement, Intbox, Longbox, NumberInputElement, Spinner, Textbox, Timebox
All Known Implementing Classes:
Bandbox, Combobox, Datebox, Decimalbox, Doublebox, FormatInputElement, InputElement, Intbox, Longbox, NumberInputElement, Spinner, Textbox, Timebox

public interface InputElement
extends XulElement, Constrainted

A skeletal implementation of an input box.

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

Since:
3.5.2
Author:
tomyeh

Field Summary
 
Fields inherited from interface org.zkoss.zk.ui.Component
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE
 
Method Summary
 void clearErrorMessage()
          Clears the error message.
 void clearErrorMessage(boolean revalidateRequired)
          Clears the error message.
 int getCols()
          Returns the cols.
 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.
 java.lang.String getText()
          Returns the value in the String format.
 java.lang.String getType()
          Returns the type.
 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.
 void select()
          Selects the whole text in this input.
 void setCols(int cols)
          Sets the cols.
 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.
 
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.Component
addEventListener, addForward, addForward, addForward, addForward, appendChild, applyProperties, clone, containsVariable, detach, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getChildren, getDefinition, getDesktop, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setAuService, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, setWidgetListener, setWidgetOverride, unsetVariable
 
Methods inherited from interface org.zkoss.zk.ui.ext.Scope
addScopeListener, getAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute
 
Methods inherited from interface org.zkoss.zul.ext.Constrainted
getConstraint, setConstraint
 

Method Detail

isDisabled

boolean isDisabled()
Returns whether it is disabled.

Default: false.


setDisabled

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


isReadonly

boolean isReadonly()
Returns whether it is readonly.

Default: false.


setReadonly

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


getName

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

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

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

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 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).

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 constrcuted, the initial value is assumed to be "not-validated-yet".

clearErrorMessage

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

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 InputElement.checkUserError() to ensure no user error.

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

Throws:
WrongValueException - if user entered a wrong value

setText

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 InputElement.coerceFromString(java.lang.String) fisrt and then InputElement.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

getMaxlength

int getMaxlength()
Returns the maxlength.

Default: 0 (non-postive means unlimited).


setMaxlength

void setMaxlength(int maxlength)
Sets the maxlength.


getCols

int getCols()
Returns the cols.

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


setCols

void setCols(int cols)
             throws WrongValueException
Sets the cols.

Throws:
WrongValueException

getTabindex

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

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


setTabindex

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

Throws:
WrongValueException

isMultiline

boolean isMultiline()
Returns whether it is multiline.

Default: false.


getType

java.lang.String getType()
Returns the type.

Default: text.


select

void select()
Selects the whole text in this input.


setConstraint

void setConstraint(java.lang.String constr)

getRawValue

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 InputElement.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

java.lang.String getRawText()
Returns the text directly without checking whether any error message not yet fixed. In other words, it does NOT invoke InputElement.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

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).

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().

See Also:
getRawValue()

isValid

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

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

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)


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