TextBoxControl

A text input control.

Remarks

TextBoxControl supports user text input using either an HTML <input> or <textara> form element. The control uses ID_isMultiLine and ID_isPassword properties to determine how to render itself:

PropertyRenders as HTML element
ID_isMultiLine = false<input type="text">
ID_isMultiLine = true<textarea>
ID_isPassword = true (and ID_isMultiLine = false)<input type="password">

TextBoxcontrol provides a common API to both input mechanisms, and also adds support for databinding, validation, and submitters.

.

Properties

ID_animators (inherited from Control)A SitedList of animators.
ID_controlId (inherited from Control)The ID this control is known in the nearest binding container parent.
ID_eventMask (inherited from Control)(Advanced) A comma-separated list of peer events this control should receive.
ID_isBindingContainer (inherited from Control)(Advanced) Force this control to act as a binding container.
ID_isInvalidTrue if the current text value fails to validate.
ID_isMultiLineTrue if this control should use a textarea.
ID_isPasswordTrue if this text box is for password entry.
ID_isPeerless (inherited from Control)(Advanced) Set this to true to prevent this control from generating a peer element in the rendered HTML.
ID_submitterIdThe ID of the submitter this control uses.
ID_submitters (inherited from Control)A SitedList of submitters.
ID_tagName (inherited from Control)Overrides the default HTML tag name used for this control.
ID_textThe text value.
ID_updateMode Either ID_enter, ID_explicit, or ID_everyKeyStroke.
ID_validationErrorMessageAn error message from the validation system.
ID_visible (inherited from Control)True if this control is visible, false if it is hidden.

Events

ID_changeEvent handler called every time the raw text in the text box changes.
ID_mouseDown (inherited from Control)Event handler called when a mouse button is pressed down.
ID_mouseMove (inherited from Control)Event handler called when the mouse is moved.
ID_mouseOut (inherited from Control)Event handler called when a leaves a control.
ID_mouseOver (inherited from Control)Event handler called when a mouse moves over a control.
ID_mouseUp (inherited from Control)Event handler called when a mouse button is released.
ID_updatedEvent handler called when the text is updated. See updateMode below.

Methods

acceptsDrop (inherited from Control)Called to determine if this control will accept a drop.
addBinding (inherited from Control)Adds a databinding between a property on this object and a binding path.
addBindingEx (inherited from Control)Extended entry point for adding a binding.
addCalculatedBinding (inherited from Control)Adds a calculated binding for a property.
addClassName (inherited from Control)Adds a CSS class to this controls "class" attribute
addEventHandler (inherited from SitedObject)Adds a delegate to be called when the specified eventId occurs on this object.
animateEx (inherited from Control)Animates a property to a value.
blur (inherited from Control)Tells this control's peer to relinquish keyboard focus.
bubble (inherited from Control)Bubbles a message up the control hierarchy - calls onBubbleEvent on this control and each of its parents.
captureMouse (inherited from Control)Register a control to receive mouse move/up events
construct (inherited from Control)Used to initialize a markup control.
equals (inherited from SitedObject)Tests if two objects are equal.
fireEventHandler (inherited from SitedObject)Invokes any user event handlers registered for a particular event using SitedObject.addEventHandler().
focus (inherited from Control)Tells this control's peer to request keyboard focus.
getBindingContainer (inherited from Control)Gets this object's nearest enclosing binding container.
getBindingStatus (inherited from SitedObject)Provides debugging information on bindings for this object.
getEventMask (inherited from Control)Gets an object indicating which peer events this control is interested in.
getParent (inherited from Control)Gets the parent Control of this control.
getPathValue (inherited from SitedObject)Traverses a binding path and returns the value at the end of it.
getPeer (inherited from Control)Gets the peer DOM element associated with this control.
getPeerForParent (inherited from Control)Gets the peer element of this control that the parent control should use in DOM manipulations.
getPropertyInfo (inherited from SitedObject)Gets information on a property.
getRawTextGets the raw value of the textbox
getResource (inherited from Control)Given the ID of a resource, returns the resource's value.
getSelectionGets the current selection start and end index.
getSite (inherited from SitedObject)Gets this object's site.
getTagName(Override) Returns either 'input' or 'textarea'
getValue (inherited from Control)Gets a property, style or attribute.
getViewState (inherited from Control) Retrieve any viewstate that has been saved for this control in a previous session.
getViewStateId (inherited from Control) Get a unique and consistent viewstateId for this control.
invalidateLayout (inherited from Control)Tells the layout system to redo layout.
onBubbleEvent (inherited from Control)Called to handle a bubbled event.
onDragEvent (inherited from Control)Called to handle a drag drop event..
onFirstRender (inherited from Control)Called the first time a control is rendered.
onPeerCreated (inherited from Control)Called when a peer is created.
onPeerEvent (inherited from Control)Called to dispatch low level events that arise in the Dom.
onSetValue (inherited from SitedObject)Called by SitedObject.setValue() when a property value is set on this object.
onSited (inherited from SitedObject)Called when this object is sited.
onSitedRoot (inherited from Control)Called when a control is added to the main control tree.
onUnsited (inherited from SitedObject)Called when this object is about to lose its site.
onUnsitedRoot (inherited from Control)Called when a control is removed from the main control tree.
onValidateRuns validation.
onValueSited (inherited from SitedObject)Called when an object is sited within this object.
onValueUnsited (inherited from SitedObject)Called when an object is about to be unsited in this.
onViewStateChanged (inherited from Control) Overridable. Controls implement this method to update their viewstate.
reflectOnBoundValue (inherited from Control)Gets runtime reflection information on an underlying bound object.
removeClassName (inherited from Control)Removes a CSS class from this controls "class" attribute
removeEventHandler (inherited from SitedObject)Remove an existing delegate from the list of delegates for the specified event.
render (inherited from Control)Places the Html representation of this control into the htmlBuilder.
renderAttributes(Override) Called by Control.render() to render attributes for this control.
renderChildren (inherited from Control)Places the Html markup for all the Control inside this control into the htmlBuilder.
setBounds (inherited from Control)Convenience method to set the left/top/width/height of an element.
setInitialValues (inherited from SitedObject)Sets multiple property values on an object (during initialization only)
setPathValue (inherited from SitedObject)Traverses a binding path and sets the value at the end of it.
setSelectionSets the text selection start and end points.
setValue (inherited from Control)Sets a property, style or attribute.
setViewState (inherited from Control) Save viewstate that should persist across sessions.
startAnimator (inherited from Control)Starts an animation.
startDragDrop (inherited from Control)Start a drag drop operation.
stopAnimator (inherited from Control)Stops an animation.
toString (inherited from SitedObject)Returns a string representation of this object.
updateValidates the text and updates the ID_text property.

TextBoxControl getRawText method

Gets the raw value of the textbox

JavaScript

var strVal = textBoxControl.getRawText()

Remarks

This obtains the current text value out of the peer text control, without performing any validation.

Returns

The text string, or '' if no peer has been created yet.

TextBoxControl getSelection method

Gets the current selection start and end index.

JavaScript

var selectionObj = textBoxControl.getSelection()

Remarks

If the text box has any text selected, this returns the start and end index of the selected text, in an object with two properties, start and end.

Returns

A JavaScript object with two properties, start and end.

Example

To compute the length of the selection, use:

var sel = textBox.getSelection();
alert("Text selection length is: " + sel.end - sel.start);

TextBoxControl getTagName method (override)

Returns either 'input' or 'textarea'

JavaScript

textBoxControl.getTagName()

Remarks

If ID_isMultiLine is true, this returns 'textarea', otherwise it returns 'input' (see TextBoxControl.renderAttributes() below).

Returns

An HTML tag name string, e.g. "span", "tr", "div" etc.

Base Implementation

TextBoxControl ID_change event

Event handler called every time the raw text in the text box changes.

JavaScript

textBoxControl.addEventHandler(ID_change, new Delegate(obj, func))

Xml

<j:TextBox change="alert('change happened')" ... >

Example

In Xml, writing:

<j:TextBox change="alert('hello');"/>

creates a change event handler on the button. Whenever the user edits the text in any way, an alert pops up saying 'hello'.

In JavaScript, you write:

// create a click function
function myChange() { alert('Hello'); }

// create a text box
var tb = new TextBoxControl();

// register myChange as an event handler for the textbox
tb.addEventHandler(ID_change, new Delegate(tb, myChange));

TextBoxControl ID_isInvalid property

True if the current text value fails to validate.

JavaScript

var boolVal = textBoxControl.getValue(ID_isInvalid)

Remarks

This read-only property is set to true if the current value in the textbox control fails to validate. It is set to false if the text validation succeeds.

TextBoxControl ID_isMultiLine property

True if this control should use a textarea.

JavaScript

var boolVal = textBoxControl.getValue(ID_isMultiLine)
textBoxControl.setValue(ID_isMultiLine, boolVal)

Xml

<j:TextBox isMultiLine="true"  ... >
or
<j:TextBox isMultiLine="false" ... >

Remarks

If ID_isMultiLine is set to true, TextBox renders as a <textarea> control.

By default, TextBox renders as either an <inputtype="text"> or <inputtype="password"> control, depending on the value of TextBoxControl.ID_isPassword.

TextBoxControl ID_isPassword property

True if this text box is for password entry.

JavaScript

var boolVal = textBoxControl.getValue(ID_isPassword)
textBoxControl.setValue(ID_isPassword, boolVal)

Xml

<j:TextBox isPassword="true"  ... >
or
<j:TextBox isPassword="false" ... >

Remarks

if ID_isPassword is true, this TextBox renders as a <inputtype="password"> peer. Otherwise it renders as a <inputtype="text"> peer.

TextBoxControl ID_submitterId property

The ID of the submitter this control uses.

JavaScript

var idname = textBoxControl.getValue(ID_submitterId)
textBoxControl.setValue(ID_submitterId, idname)

Xml

<j:TextBox submitterId="string"  ... >

Remarks

Set this to the ID name of the submitter group this control is linked to. If this is undefined, the control does not use a submitter group.

TextBoxControl ID_text property

The text value.

JavaScript

var strVal = textBoxControl.getValue(ID_text)
textBoxControl.setValue(ID_text, strVal)

Xml

<j:TextBox text="string"  ... >

Remarks

This is the current text value of the textbox, after validation.

TextBoxControl ID_updated event

Event handler called when the text is updated. See updateMode below.

JavaScript

textBoxControl.addEventHandler(ID_updated, new Delegate(obj, func))

Xml

<j:TextBox updated="alert('updated happened')" ... >

Example

In Xml, writing:

<j:TextBox updated="alert('hello');"/>

creates an updated event handler on the button. When the user edits the text and then hits enter, the alert pops up saying 'hello'.

TextBoxControl ID_updateMode property

Either ID_enter, ID_explicit, or ID_everyKeyStroke.

JavaScript

var idname = textBoxControl.getValue(ID_updateMode)
textBoxControl.setValue(ID_updateMode, idname)

Xml

<j:TextBox updateMode="enter"  ... >
or
<j:TextBox updateMode="everyKeyStroke" ... >
or
<j:TextBox updateMode="explicit" ... >

Remarks

Specifies when the textbox updates its ID_text property (causing changes to propagate to anything bound to that property).

If ID_updateMode is ID_enter (the default), the ID_text property is only updated when the user hits ENTER or when the keyboard focus leaves the control.

If ID_updateMode is ID_everyKeyStroke, every time the user types in the text box the ID_text property is updated to reflect the new value.

If ID_updateMode is ID_explicit, the application must explicitly call TextBoxControl.update() to update the ID_text property.

In all three cases, the ID_text property will not be updated if the current value in the textbox fails to validate.

TextBoxControl ID_validationErrorMessage property

An error message from the validation system.

JavaScript

var strVal = textBoxControl.getValue(ID_validationErrorMessage)

Remarks

This read-only property is set to a string containing an error message from the validation system, if the text value in the text box fails to validate. If the text validation succeeds, this property is "".

TextBoxControl onValidate method

Runs validation.

JavaScript

var boolVal = textBoxControl.onValidate()

Remarks

This gets the current raw text value in the control and performs any necessary validation. A side effect of calling this method is that ID_isInvalid and ID_validationErrorMessage are updated.

This method does not update ID_text - use TextBoxControl.update() for that.

Returns

true if the text is valid, and false otherwise.

TextBoxControl renderAttributes method (override)

Called by Control.render() to render attributes for this control.

JavaScript

textBoxControl.renderAttributes(htmlBuilder)

Remarks

If Control.getTagName() returns 'input', the TextBoxControl.renderAttributes method looks at ID_isPassword - if ID_isPassword is false, TextBox renders as an <input type="text"> element. Otherwise TextBox renders as a <input type="password"> element.

Base Implementation

TextBoxControl setSelection method

Sets the text selection start and end points.

JavaScript

textBoxControl.setSelection(startIndex,endIndex)

TextBoxControl update method

Validates the text and updates the ID_text property.

JavaScript

textBoxControl.update()

Remarks

This method calls TextBoxControl.onValidate(). If validate returns true, this gets the raw text value of the text field (using TextBoxControl.getRawText()) and sets it as the current value of ID_text - causing any databindings to update.