## Class TTextBox

Description

Implements interfaces:

- IPostBackDataHandler
- IValidatable
- IDataRenderer

TTextBox class

TTextBox displays a text box on the Web page for user input. The text displayed in the TTextBox control is determined by the Text property. You can create a SingleLine, a MultiLine, or a Password text box by setting the TextMode property. If the TTextBox control is a multiline text box, the number of rows it displays is determined by the Rows property, and the Wrap property can be used to determine whether to wrap the text in the component.

To specify the display width of the text box, in characters, set the Columns property. To prevent the text displayed in the component from being modified, set the ReadOnly property to true. If you want to limit the user input to a specified number of characters, set the MaxLength property. To use AutoComplete feature, set the AutoCompleteType property.

If AutoPostBack is set true, updating the text box and then changing the focus out of it will cause postback action. And if CausesValidation is true, validation will also be processed, which can be further restricted within a ValidationGroup.

WARNING: Be careful if you want to display the text collected via TTextBox. Malicious cross-site script may be injected in. You may use SafeText to prevent this problem.

NOTE: If you set Wrap to false or use AutoCompleteType, the generated HTML output for the textbox will not be XHTML-compatible. Currently, no alternatives are available.

- since: 3.0
- version: $Id: TTextBox.php 2541 2008-10-21 15:05:13Z qiang.xue $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/UI/WebControls/TTextBox.php (line 51)

    TComponent
       |
       --TApplicationComponent
          |
          --TControl
             |
             --TWebControl
                |
                --TTextBox

Direct descendents

Class | Description
--- | ---
TActiveTextBox | TActiveTextBox class.
TColorPicker | TColorPicker class.
TDatePicker | TDatePicker class.
THtmlArea | THtmlArea class

Class Constant Summary
DEFAULT_COLUMNS = 20
DEFAULT_ROWS = 4
Method Summary
void addAttributesToRender (THtmlWriter $writer)
TTextBoxAutoCompleteType getAutoCompleteType ()
boolean getAutoPostBack ()
boolean getAutoTrim ()
boolean getCausesValidation ()
string getClientClassName ()
integer getColumns ()
string getData ()
boolean getDataChanged ()
boolean getEnableClientScript ()
bool getIsValid ()
integer getMaxLength ()
boolean getPersistPassword ()
array getPostBackOptions ()
boolean getReadOnly ()
integer getRows ()
string getSafeText ()
mixed getSafeTextParser ()
string getTagName ()
string getText ()
TTextBoxMode getTextMode ()
string getValidationGroup ()
mixed getValidationPropertyValue ()
boolean getWrap ()
boolean loadPostData (string $key, array $values)
void onTextChanged (TEventParameter $param)
void raisePostDataChangedEvent ()
void renderClientControlScript (mixed $writer)
void renderContents (THtmlWriter $writer)
void setAutoCompleteType (TTextBoxAutoCompleteType $value)
void setAutoPostBack (boolean $value)
void setAutoTrim (boolean $value)
void setCausesValidation (boolean $value)
void setColumns (integer $value)
void setData (string $value)
void setEnableClientScript (boolean $value)
void setIsValid (bool $value)
void setMaxLength (integer $value)
void setPersistPassword (boolean $value)
void setReadOnly (boolean $value)
void setRows (integer $value)
void setText (string $value)
void setTextMode (TTextBoxMode $value)
void setValidationGroup (string $value)
void setWrap (boolean $value)
Methods
addAttributesToRender (line 101)

Adds attribute name-value pairs to renderer.

This method overrides the parent implementation with additional textbox specific attributes.

- access: protected

void addAttributesToRender (THtmlWriter $writer)

- THtmlWriter $writer: the writer used for the rendering purpose

Redefinition of:

TWebControl::addAttributesToRender()
  Adds attribute name-value pairs to renderer.

Redefined in descendants as:

- TActiveTextBox::addAttributesToRender() : Ensure that the ID attribute is rendered and registers the javascript code for initializing the active control.
- TInPlaceTextBox::addAttributesToRender() : Ensure that the ID attribute is rendered and registers the javascript code for initializing the active control.
- TDatePicker::addAttributesToRender() : Add the client id to the input textbox, and register the client scripts.
- THtmlArea::addAttributesToRender() : Adds attribute name-value pairs to renderer.

getAutoCompleteType (line 304)

- return: the AutoComplete type of the textbox
- access: public

TTextBoxAutoCompleteType getAutoCompleteType ()
getAutoPostBack (line 323)

- return: a value indicating whether an automatic postback to the server will occur whenever the user modifies the text in the TTextBox control and then tabs out of the component. Defaults to false.
- access: public

boolean getAutoPostBack ()

Redefined in descendants as:

- THtmlArea::getAutoPostBack()

getAutoTrim (line 342)

- return: a value indicating whether the input text should be trimmed spaces. Defaults to false.
- access: public

boolean getAutoTrim ()
getCausesValidation (line 359)

- return: whether postback event trigger by this text box will cause input validation, default is true.
- access: public

boolean getCausesValidation ()
getClientClassName (line 186)

Gets the name of the javascript class responsible for performing postback for this control.

This method overrides the parent implementation.

- return: the javascript class name
- access: protected

string getClientClassName ()

Redefined in descendants as:

- TActiveTextBox::getClientClassName() : Gets the name of the javascript class responsible for performing postback for this control.
- TAutoComplete::getClientClassName()
- TInPlaceTextBox::getClientClassName()
- TColorPicker::getClientClassName() : Gets the name of the javascript class responsible for performing postback for this control.
- THtmlArea::getClientClassName() : Gets the name of the javascript class responsible for performing postback for this control.

getColumns (line 375)

- return: the display width of the text box in characters, default is 0 meaning not set.
- access: public

integer getColumns ()
getData (line 481)

Returns the text content of the TTextBox control.

This method is required by IDataRenderer. It is the same as getText().

- return: the text content of the TTextBox control.
- access: public
- since: 3.1.0
- see: TTextBox::getText()

string getData ()

Redefined in descendants as:

- TDatePicker::getData() : Returns the timestamp selected by the user.

getDataChanged (line 232)

Returns a value indicating whether postback has caused the control data change.

This method is required by the IPostBackDataHandler interface.

- return: whether postback has caused the control data change. False if the page is not in postback mode.
- access: public

boolean getDataChanged ()
getEnableClientScript (line 83)

- return: whether to render javascript.
- access: public

boolean getEnableClientScript ()
getIsValid (line 252)

Returns true if this control validated successfully.

Defaults to true.

- return: wether this control validated successfully.
- access: public

bool getIsValid ()
getMaxLength (line 392)

- return: the maximum number of characters allowed in the text box, default is 0 meaning not set.
- access: public

integer getMaxLength ()
getPersistPassword (line 442)

- return: whether password should be displayed in the textbox during postback. Defaults to false. This property only applies when TextMode='Password'.
- access: public

boolean getPersistPassword ()
getPostBackOptions (line 195)

Gets the post back options for this textbox.

- access: protected

array getPostBackOptions ()

Redefined in descendants as:

- TAutoComplete::getPostBackOptions()
- TInPlaceTextBox::getPostBackOptions()
- TColorPicker::getPostBackOptions() : Get javascript color picker options.

getReadOnly (line 409)

- return: whether the textbox is read only, default is false.
- access: public

boolean getReadOnly ()
getRows (line 425)

- return: the number of rows displayed in a multiline text box, default is 4
- access: public

integer getRows ()
getSafeText (line 502)

- return: safe text content with javascript stripped off
- access: public

string getSafeText ()
getSafeTextParser (line 512)

- return: safe text parser
- access: protected

mixed getSafeTextParser ()
getTagName (line 75)

- return: tag name of the textbox
- access: protected

string getTagName ()

Redefinition of:

TWebControl::getTagName()
  Returns the tag name used for this control.

Redefined in descendants as:

- TInPlaceTextBox::getTagName()

getText (line 458)

- return: the text content of the TTextBox control.
- access: public

string getText ()
getTextMode (line 522)

- return: the behavior mode of the TTextBox component. Defaults to TTextBoxMode::SingleLine.
- access: public

TTextBoxMode getTextMode ()

Redefined in descendants as:

- THtmlArea::getTextMode() : Overrides the parent implementation.

getValidationGroup (line 540)

- return: the group of validators which the text box causes validation upon postback
- access: public

string getValidationGroup ()
getValidationPropertyValue (line 242)

Returns the value to be validated.

This methid is required by IValidatable interface.

- return: the value of the property to be validated.
- access: public

mixed getValidationPropertyValue ()

Redefined in descendants as:

- TDatePicker::getValidationPropertyValue() : Returns the value to be validated.

getWrap (line 556)

- return: whether the text content wraps within a multiline text box. Defaults to true.
- access: public

boolean getWrap ()
loadPostData (line 213)

Loads user input data.

This method is primarly used by framework developers.

- return: whether the data of the component has been changed
- access: public

boolean loadPostData (string $key, array $values)

- string $key: the key that can be used to retrieve data from the input data collection
- array $values: the input data collection

Redefined in descendants as:

- TDatePicker::loadPostData() : Loads user input data. Override parent implementation, when InputMode is DropDownList call getDateFromPostData to get date data.

onTextChanged (line 272)

Raises OnTextChanged event.

This method is invoked when the value of the Text property changes on postback. If you override this method, be sure to call the parent implementation to ensure the invocation of the attached event handlers.

- access: public

void onTextChanged (TEventParameter $param)

- TEventParameter $param: event parameter to be passed to the event handlers

raisePostDataChangedEvent (line 284)

Raises postdata changed event.

This method is required by IPostBackDataHandler interface. It is invoked by the framework when Text property is changed on postback. This method is primarly used by framework developers.

- access: public

void raisePostDataChangedEvent ()
renderClientControlScript (line 174)

Renders the javascript for textbox.

- access: protected

void renderClientControlScript (mixed $writer)

Redefined in descendants as:

- TActiveTextBox::renderClientControlScript() : Override parent implementation, no javascript is rendered here instead the javascript required for active control is registered in addAttributesToRender.
- TAutoComplete::renderClientControlScript() : Override parent implementation, no javascript is rendered here instead the javascript required for active control is registered in addAttributesToRender.

renderContents (line 295)

Renders the body content of the textbox when it is in MultiLine text mode.

- access: public

void renderContents (THtmlWriter $writer)

- THtmlWriter $writer: the writer for rendering

Redefinition of:

TWebControl::renderContents()
  Renders the body content enclosed between the control tag.

Redefined in descendants as:

- TInPlaceTextBox::renderContents() : Renders the body content of the label.

setAutoCompleteType (line 313)

- access: public
- throws: TInvalidDataValueException if the input parameter is not a valid AutoComplete type

void setAutoCompleteType (TTextBoxAutoCompleteType $value)

- TTextBoxAutoCompleteType $value: the AutoComplete type of the textbox, default value is TTextBoxAutoCompleteType::None.

setAutoPostBack (line 334)

Sets the value indicating if postback automatically.

An automatic postback to the server will occur whenever the user modifies the text in the TTextBox control and then tabs out of the component.

- access: public

void setAutoPostBack (boolean $value)

- boolean $value: the value indicating if postback automatically

Redefined in descendants as:

- TDatePicker::setAutoPostBack() : AutoPostBack is not supported.

setAutoTrim (line 351)

Sets the value indicating if the input text should be trimmed spaces

- access: public

void setAutoTrim (boolean $value)

- boolean $value: the value indicating if the input text should be trimmed spaces

setCausesValidation (line 367)

- access: public

void setCausesValidation (boolean $value)

- boolean $value: whether postback event trigger by this text box will cause input validation.

setColumns (line 384)

Sets the display width of the text box in characters.

- access: public

void setColumns (integer $value)

- integer $value: the display width, set it 0 to clear the setting

setData (line 494)

Sets the text content of the TTextBox control.

This method is required by IDataRenderer. It is the same as setText().

- access: public
- since: 3.1.0
- see: TTextBox::setText()

void setData (string $value)

- string $value: the text content of the TTextBox control.

Redefined in descendants as:

- TDatePicker::setData() : Sets the timestamp represented by this control.

setEnableClientScript (line 91)

- access: public

void setEnableClientScript (boolean $value)

- boolean $value: whether to render javascript.

setIsValid (line 259)

- access: public

void setIsValid (bool $value)

- bool $value: wether this control is valid.

setMaxLength (line 401)

Sets the maximum number of characters allowed in the text box.

- access: public

void setMaxLength (integer $value)

- integer $value: the maximum length, set it 0 to clear the setting

setPersistPassword (line 450)

- access: public

void setPersistPassword (boolean $value)

- boolean $value: whether password should be displayed in the textbox during postback. This property only applies when TextMode='Password'.

setReadOnly (line 417)

- access: public

void setReadOnly (boolean $value)

- boolean $value: whether the textbox is read only

Redefined in descendants as:

- TInPlaceTextBox::setReadOnly() : Update ClientSide Readonly property

setRows (line 434)

Sets the number of rows displayed in a multiline text box.

- access: public

void setRows (integer $value)

- integer $value: the number of rows

setText (line 467)

Sets the text content of the TTextBox control.

- access: public

void setText (string $value)

- string $value: the text content

Redefined in descendants as:

- TActiveTextBox::setText() : Client-side Text property can only be updated after the OnLoad stage.
- TInPlaceTextBox::setText() : On callback response, the inner HTMl of the label and the
- TActiveDatePicker::setText() : Client-side Text property can only be updated after the OnLoad stage.

setTextMode (line 532)

Sets the behavior mode of the TTextBox component.

- access: public
- throws: TInvalidDataValueException if the input value is not a valid text mode.

void setTextMode (TTextBoxMode $value)

- TTextBoxMode $value: the text mode

Redefined in descendants as:

- THtmlArea::setTextMode() : Overrides the parent implementation.

setValidationGroup (line 548)

- access: public

void setValidationGroup (string $value)

- string $value: the group of validators which the text box causes validation upon postback

setWrap (line 565)

Sets the value indicating whether the text content wraps within a multiline text box.

- access: public

void setWrap (boolean $value)

- boolean $value: whether the text content wraps within a multiline text box.

#### Inherited Methods

Inherited From TWebControl

> TWebControl::addAttributesToRender()
> TWebControl::clearStyle()
> TWebControl::copyBaseAttributes()
> TWebControl::createStyle()
> TWebControl::getAccessKey()
> TWebControl::getBackColor()
> TWebControl::getBorderColor()
> TWebControl::getBorderStyle()
> TWebControl::getBorderWidth()
> TWebControl::getCssClass()
> TWebControl::getDisplay()
> TWebControl::getFont()
> TWebControl::getForeColor()
> TWebControl::getHasStyle()
> TWebControl::getHeight()
> TWebControl::getStyle()
> TWebControl::getTabIndex()
> TWebControl::getTagName()
> TWebControl::getToolTip()
> TWebControl::getWidth()
> TWebControl::render()
> TWebControl::renderBeginTag()
> TWebControl::renderContents()
> TWebControl::renderEndTag()
> TWebControl::setAccessKey()
> TWebControl::setBackColor()
> TWebControl::setBorderColor()
> TWebControl::setBorderStyle()
> TWebControl::setBorderWidth()
> TWebControl::setCssClass()
> TWebControl::setDisplay()
> TWebControl::setForeColor()
> TWebControl::setHeight()
> TWebControl::setStyle()
> TWebControl::setTabIndex()
> TWebControl::setToolTip()
> TWebControl::setWidth()

Inherited From TControl

> TControl::__construct()
> TControl::addedControl()
> TControl::addParsedObject()
> TControl::addToPostDataLoader()
> TControl::applyStyleSheetSkin()
> TControl::autoBindProperty()
> TControl::autoDataBindProperties()
> TControl::bindProperty()
> TControl::broadcastEvent()
> TControl::bubbleEvent()
> TControl::clearChildState()
> TControl::clearControlState()
> TControl::clearNamingContainer()
> TControl::clearViewState()
> TControl::convertUniqueIdToClientId()
> TControl::createChildControls()
> TControl::createControlCollection()
> TControl::dataBind()
> TControl::dataBindChildren()
> TControl::dataBindProperties()
> TControl::ensureChildControls()
> TControl::findControl()
> TControl::findControlsByID()
> TControl::findControlsByType()
> TControl::focus()
> TControl::getAdapter()
> TControl::getAllowChildControls()
> TControl::getAttribute()
> TControl::getAttributes()
> TControl::getChildControlsCreated()
> TControl::getClientID()
> TControl::getControls()
> TControl::getControlStage()
> TControl::getControlState()
> TControl::getCustomData()
> TControl::getEnabled()
> TControl::getEnableTheming()
> TControl::getEnableViewState()
> TControl::getHasAdapter()
> TControl::getHasAttributes()
> TControl::getHasChildInitialized()
> TControl::getHasControls()
> TControl::getHasInitialized()
> TControl::getHasLoaded()
> TControl::getHasLoadedPostData()
> TControl::getHasPreRendered()
> TControl::getID()
> TControl::getNamingContainer()
> TControl::getPage()
> TControl::getParent()
> TControl::getRegisteredObject()
> TControl::getSkinID()
> TControl::getSourceTemplateControl()
> TControl::getTemplateControl()
> TControl::getUniqueID()
> TControl::getViewState()
> TControl::getVisible()
> TControl::hasAttribute()
> TControl::initRecursive()
> TControl::isDescendentOf()
> TControl::isObjectRegistered()
> TControl::loadRecursive()
> TControl::loadState()
> TControl::loadStateRecursive()
> TControl::onDataBinding()
> TControl::onInit()
> TControl::onLoad()
> TControl::onPreRender()
> TControl::onUnload()
> TControl::preRenderRecursive()
> TControl::raiseBubbleEvent()
> TControl::registerObject()
> TControl::removeAttribute()
> TControl::removedControl()
> TControl::render()
> TControl::renderChildren()
> TControl::renderControl()
> TControl::saveState()
> TControl::saveStateRecursive()
> TControl::setAdapter()
> TControl::setAttribute()
> TControl::setChildControlsCreated()
> TControl::setControlStage()
> TControl::setControlState()
> TControl::setCustomData()
> TControl::setEnabled()
> TControl::setEnableTheming()
> TControl::setEnableViewState()
> TControl::setID()
> TControl::setPage()
> TControl::setSkinID()
> TControl::setTemplateControl()
> TControl::setViewState()
> TControl::setVisible()
> TControl::trackViewState()
> TControl::traverseChildControls()
> TControl::unbindProperty()
> TControl::unloadRecursive()
> TControl::unregisterObject()
> TControl::__get()

Inherited From TApplicationComponent

> TApplicationComponent::getApplication()
> TApplicationComponent::getRequest()
> TApplicationComponent::getResponse()
> TApplicationComponent::getService()
> TApplicationComponent::getSession()
> TApplicationComponent::getUser()
> TApplicationComponent::publishAsset()
> TApplicationComponent::publishFilePath()

Inherited From TComponent

> TComponent::addParsedObject()
> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::createdOnTemplate()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Class Constants
DEFAULT_COLUMNS = 20 (line 60)

Default number of columns (for MultiLine text box)

DEFAULT_ROWS = 4 (line 56)

Default number of rows (for MultiLine text box)

#### Inherited Constants

Inherited from TControl

> TControl::AUTOMATIC_ID_PREFIX
> TControl::CLIENT_ID_SEPARATOR
> TControl::CS_CHILD_INITIALIZED
> TControl::CS_CONSTRUCTED
> TControl::CS_INITIALIZED
> TControl::CS_LOADED
> TControl::CS_PRERENDERED
> TControl::CS_STATE_LOADED
> TControl::ID_FORMAT
> TControl::ID_SEPARATOR
> TControl::IS_CHILD_CREATED
> TControl::IS_CREATING_CHILD
> TControl::IS_DISABLE_THEMING
> TControl::IS_DISABLE_VIEWSTATE
> TControl::IS_ID_SET
> TControl::IS_SKIN_APPLIED
> TControl::IS_STYLESHEET_APPLIED
> TControl::RF_ADAPTER
> TControl::RF_AUTO_BINDINGS
> TControl::RF_CHILD_STATE
> TControl::RF_CONTROLS
> TControl::RF_CONTROLSTATE
> TControl::RF_DATA_BINDINGS
> TControl::RF_EVENTS
> TControl::RF_NAMED_CONTROLS
> TControl::RF_NAMED_CONTROLS_ID
> TControl::RF_NAMED_OBJECTS
> TControl::RF_SKIN_ID

Documentation generated on Sun, 11 Jan 2009 20:24:10 -0500 by phpDocumentor 1.3.0RC4