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.