# Mojo.Widget.TextField

## Namespace Detail

### Overview

This is a widget that extends the functionality of an input type = text HTML element with hint text and text correction behavior. The field defaults to a single-line, scrolling text field with fixed horizontal and vertical dimensions, which will submit the text (i.e., generate a Mojo.Event.propertyChange event) when it loses focus. The contents of the field will be passed to your event handler in both event.value and the widget's model.value.

### Declaration

>     <div x-mojo-element="TextField" id="textFieldId" class="textFieldClass"
>       name="textFieldName"></div>

Properties | Required | Value | Description
--- | --- | --- | ---
x-mojo-element | Required | TextField | Declares the widget as type 'TextField'.
id | Required | Any String | Identifies the widget element for use when instantiating or rendering.
class | Optional | Any String | Provide your own unique class and override the framework's styles.
name | Optional | Any String | Adds a unique name to the TextField widget; generally used in templates.

### Events

>     Mojo.Event.listen(this.controller.get("textFieldId"),
>       Mojo.Event.propertyChange, this.handleUpdate);

Event Type | Value | Event Handling
--- | --- | ---
Mojo.Event.propertyChange | {model:model, property:property, value:value, oldValue: oldValue, originalEvent: originalEvent}

### Instantiation

>     this.controller.setupWidget("textFieldId",
>       this.attributes = {
>           hintText: $L("  ... and hit Enter"),
>           multiline: false,
>           enterSubmits: false,
>           focus: true
>       },
>       this.model = {
>           value: ,
>           disabled: false
>       }
>     );

### Attribute Properties

Attribute Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
modelProperty | String | Optional | value | Model property name for selector value
disabledProperty | String | Optional | disabled | Model property name for disabled boolean
hintText | String | Optional | None | Initially displayed string; supplanted by model value if supplied.
textFieldName | String | Optional | None | DEPRECATED If supplied, the textarea will have this name, so that when it is serialized, the property can be easily pulled out.
inputName | String | Optional | None | If supplied, the textarea will have this name, so that when it is serialized, the property can be easily pulled out.
multiline | Boolean | Optional | FALSE | Auto line wrapping to field width
charsAllow | Function | Optional | None | Function must return 'true' to allow input character, or 'false' if not allowed; note: this event is sent as a result of a keyPress event, so you must check against key codes matching ASCII characters.
focus | Boolean | Optional | FALSE | DEPRECATED If true, field has focus on scene push.
autoFocus | Boolean | Optional | FALSE | If true, field has focus on scene push.
modifierState | String | Optional | None | initial state of modifier keys for this field. Can be: Mojo.Widget.shiftLock (shifts all characters typed), Mojo.Widget.numLock (uses the "Num" character equivalent for all characters typed), Mojo.Widget.shiftSingle (shifts the first character typed), Mojo.Widget.numSingle (uses "Num" character equivalent for the first character typed)
autoResize | Boolean | Optional | FALSE | DEPRECATED Automatically grow field horizontally.
growWidth | Boolean | Optional | FALSE | Automatically grow field horizontally.
autoResizeMax | Integer | Optional | None | Maximum width of field
enterSubmits | Boolean | Optional | FALSE | When used in conjunction with multiline, if this is set, then enter key will submit rather than newline.
limitResize | Boolean | Optional | FALSE | Limit height resize (scrolls text rather than grow field).
preventResize | Boolean | Optional | FALSE | There will be no resizing in any dimension.
holdToEnable | Boolean | Optional | FALSE | If the TextField is disabled, tapping and holding and releasing will enable it; if disabled is not set, this is ignored.
focusMode | String | Optional |  | Sets the cursor mode when the field gets focus. Options are: Mojo.Widget.focusSelectMode Mojo.Widget.focusInsertMode Mojo.Widget.focusAppendMode Either text will all be selected (Select), or a cursor will appear where the user tapped (Insert) or the cursor will go to the end of the text (Append).
changeOnKeyPress | Boolean | Optional | FALSE | If true, sends a propertyChange event on every character change to a field; otherwise only when focus is lost.
textReplacement | Boolean | Optional | TRUE | DEPRECATED Whether to enable the SmartTextEngine services of PalmSysMgr. Enabled by default in the TextField.
maxLength | Integer | Optional | No Limit | Maximum character length of field; does not apply to multiline fields where an exception will be thrown.
requiresEnterKey | Boolean | Optional | FALSE | Enter key required to submit; other navigation will not generate submit event.
holdToEdit | Boolean | Optional | FALSE | Tap and Hold to focus/edit; Tap only will be ignored.
autoCapitalization | Boolean | Optional | FALSE | DEPRECATED The first letter of each word (determined by whitespace) is capitalized.
emoticons | Boolean | Optional | FALSE | Enable emoticons on this field.
autoReplace | Boolean | Optional | True | Whether to enable the SmartTextEngine services of PalmSysMgr. Enabled by default in the TextField.
textCase | String | Optional | Mojo.Widget.steMode SentenceCase | Use this to change the autocapitalization on the TextField. Options are: Mojo.Widget.steModeSentenceCase (capitalization like a sentence), Mojo.Widget.steModeTitleCase (capitalize first letter of each word), Mojo.Widget.steModeLowerCase (no capitalization)

### Model Properties

Model Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
value | String | Required | Null | Initial and updated value of widget
disabled | Boolean | Optional | false | If true, toggle is inactive.

### Methods

To invoke a method on a widget, use the scene controller's `get` method for the desired widget, and append `mojo` followed by the method.

Example:

>     this.controller.get('myWidget').mojo.getValue()

Method | Arguments | Description
--- | --- | ---
focus | none | Focuses the input part of the text field.
blur | none | Blurs the input part of the text field.
getValue | none | Gets the plaintext value of the text field.
setText | String | DEPRECATED Sets the plaintext value of the text field; also used by alt char picker to set the value.
setValue | String | Sets the plaintext value of the text field.
getCursorPosition | none | Returns an object with {selectionStart: int, selectionEnd: int} that describes the position of the cursor; if start is not equal to end, then there is text selected.
setCursorPosition | start, end | Sets the cursor position in the input portion of the TextField; if start and end are not the same, then this will select the text between START and END; if start and/or end occur in invalid positions, they will be changed to valid positions at the end of the text if they were larger than the size of the value, or at the beginning, if they are smaller than the size of the value; empty text will result in a cursor at the start of the TextField.

Set `x-mojo-focus-highlight=true` on any parent div to have the focus class applied to it as well when the TextField widget becomes focused.