TextField

From WebOS101

Contents 1 Introduction 1.1 Declaration 1.2 Events 1.3 Instantiation 1.4 Attribute Properties 1.5 Model Properties 1.6 Methods 2 Using the TextField 2.1 Notes 2.2 Detecting Enter Key 2.3 Restricting Input to Integers 2.4 Dynamic hintText 2.5 Limit Multi-Line Growth 3 Styling a TextField

Introduction

Note: An un-wrapped TextField will disappear from a scene if it has no text and no focus

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 frameworks styles
name	Optional	Any String	Add a unique name to the textfield widget; generally used in templates when used

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,
        autoFocus: 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 multline, if this is set, then enter 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 Text will either all be selected (Select), or a cursor will appear where the user tapped (Insert) or the cursor will go to end of text (Append)
changeOnKeyPress	Boolean	Optional	FALSE	If true, sends a propertyChange event on every character change to a field; otherwise only when focus 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	Required Enter key to submit; other navigation will not genterate 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

Method	Arguments	Description
focus	none	Focus the input part of the text field
blur	none	Blur the input part of the text field
getValue	none	Get the plaintext value of the text field
setText	String	DEPRECATED Set the plaintext value of the text field; also used by alt char picker to set the value
setValue	String	Set the plaintext value of the text field
getCursorPosition	none	Returns on object with {selectionStart: int, selectionEnd: int} that describe the position of the cursor; if start is not equal to end, then there is text selected
setCursorPosition	start, end	Set 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

Using the TextField

Notes

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

Detecting Enter Key

Option 1: Detect enter key using a key handler on the document:

this.controller.document.addEventListener("keyup", this.keyupHandler, true);
;;;
YourProgram.prototype.keyupHandler = function(event)
{
  if (Mojo.Char.isEnterKey(event.keyCode)) {
    if(event.srcElement.parentElement.id=="myTextField") {
      $('myTextField').mojo.blur();
      setTimeout(this.enterKeyContinue.bind(this), 10);
    }
  }
}

Restricting Input to Integers

The TextField widget supports an attribute to set a function to limit the allowed characters. This function receives an integer value of the character the user enters. This function allows one decimal point to be entered (you must set the acceptDecimal elsewhere in the code).

charsAllow: function( charCode ) {
    if (this.acceptDecimal && (charCode === 46) ) {
        this.acceptDecimal = false;
        return( true );
    }
    else {
        return( ( charCode >= 48 && charCode <= 57) );
    }
}.bind(this)

Notes:

• Use 'keyup' instead of Mojo.Event.keyup. The latter will not work
• Blur allows the model to be updated, though properly setting up the model may obviate this need
• (test: When setting up the TextField set requiresEnterKey to false, there may be other settings required, check this out!)

Dynamic hintText

To have a dynamic hintText, just update the attribute like so:

this.attributes.hintText = 'my new hint text!';

Then call a modelChanged():

this.controller.modelChanged(this.model);

Limit Multi-Line Growth

Multi-line TextFields will grow indefinitely if you do not limit them. Setting limitResize is not enough. You must set the max-height style on the div in order for limitResize to be respected.

Styling a TextField

When using a multi-line textfield in your project you will notice that by using css to change the font color of the textfield the onfocus color of the field will still be black, to over come this you will have to set the TEXTAREA property color.

TEXTAREA {
    color:#FFFFFF;
}

To change the hint text color change

.multiline-hint-text {
    color:#FFFFFF;
}