Packageqnx.ui.text
Classpublic class TextInput
InheritanceTextInput Inheritance SkinnableComponent Inheritance UIComponent Inheritance flash.display.MovieClip

The TextInput class contains the functionality for capturing text input from a user. A TextInput instance is a simple, single-line text field in which the user can enter a text String.

View the examples

See also

KeyboardType
ReturnKeyType
Label

Public Properties
 PropertyDefined By
  autoSize : String
Deprecated: Deprecated as of version 1.0.1. Value is ignored.
Gets or sets a String that indicates how a label is sized and aligned to fit the value of its text property.
TextInput
  clearIconMode : int
Gets or sets a value that determines how the clear button appears in the text field.
TextInput
 Inheritedcontainment : String
Gets or sets a property that determines how a component is contained within a parent container.
UIComponent
  displayAsPassword : Boolean
Gets or sets a Boolean that determines whether text should be masked.
TextInput
  embedFonts : Boolean
Gets or sets the embedFonts property of the internal TextField of the label.
TextInput
  format : TextFormat
Gets or sets the TextFormat object of the label.
TextInput
  keyboardType : String
The virtual keyboard type to use when this text input has focus.
TextInput
  leftIcon : DisplayObject
Gets or sets the left icon for the TextInput component.
TextInput
  leftIconMode : int
Gets or sets a value that controls how the left icon is displayed in the text field.
TextInput
  maxChars : int
Gets or sets the maximum number of characters that the text field can contain, as entered by a user.
TextInput
  prompt : String
Gets or sets the placeholder text that is displayed in the text field when there is no other text in the text field.
TextInput
  restrict : String
Gets or sets the restrict property of the internal TextField.
TextInput
  returnKeyDisable : Boolean
When set to true the virtual keyboard return key is disabled, when this text input has focus.
TextInput
  returnKeyType : String
The virtual keyboard enter key type to use when this text input has focus.
TextInput
  rightIcon : DisplayObject
Gets or sets the right icon for the TextInput component.
TextInput
  rightIconMode : int
Gets or sets a value that controls how the right icon is displayed in the text field.
TextInput
 Inheritedsize : Number
Gets or sets the size for this component (as a percentage of the container's size, or in pixels).
UIComponent
 InheritedsizeMode : String
Gets or sets the size mode for this component.
UIComponent
 InheritedsizeUnit : String
Gets or sets the unit of measure for the size property.
UIComponent
  text : String
Gets or sets the text String of the label.
TextInput
  textField : TextField
[read-only] Gets a reference to the internal TextField of the Label.
TextInput
  textHeight : int
[read-only] Returns the height of the text in the label (in pixels).
TextInput
  textWidth : int
[read-only] Returns the width of the text in the label (in pixels).
TextInput
Public Methods
 MethodDefined By
  
TextInput()
Creates a TextInput instance.
TextInput
 Inherited
destroy():void
Call this method when you want to have your object collected by the garbage collector.
UIComponent
 Inherited
drawNow():void
Calls the draw() method.
UIComponent
  
getLeftIconRect():Rectangle
Gets the position and size of the left icon.
TextInput
  
getRightIconRect():Rectangle
Gets the position and size of the right icon.
TextInput
 Inherited
invalidate(property:String = all, invalidateNow:Boolean = false):void
Marks the property as invalid and the draw() method is called on the next frame or the next render, whichever comes first.
UIComponent
 Inherited
setPosition(x:Number, y:Number):void
Sets the x and y position of the component.
UIComponent
 Inherited
setSize(w:Number, h:Number):void
Sets the width and height of the component.
UIComponent
 Inherited
setSkin(cellSkin:Object):void
Set the skin object on the component for it to render.
SkinnableComponent
Protected Methods
 MethodDefined By
 Inherited
callLater(method:Function):void
Calls the specified method on the next frame or the next render, which ever happens first.
UIComponent
 Inherited
createInstance(linkage:Object):DisplayObject
Calling this method will attempt to create a DisplayObject instance based on the value of the linkage parameter.
UIComponent
 Inherited
draw():void
Called every time you set the width and height of the component.
UIComponent
 Inherited
isInvalid(property:String, ... properties):Boolean
Checks to see if the property is invalid and returns true if it is.
UIComponent
 Inherited
onAdded():void
Called when the instance is added to the stage.
UIComponent
 Inherited
onRemoved():void
Called when the instance is removed from the stage.
UIComponent
 Inherited
setEnabled(val:Boolean):void
Called when the enabled property changes.
UIComponent
 Inherited
validate(property:String = all):void
Lets the component know that the specified property has been validated.
UIComponent
Events
 Event Summary Defined By
  
change
Dispatched when the text in the input field is modified.TextInput
Property Detail
autoSizeproperty
autoSize:String
Deprecated: Deprecated as of version 1.0.1. Value is ignored.

Gets or sets a String that indicates how a label is sized and aligned to fit the value of its text property.

NOTE: This value is deprecated and its value is ignored.

The following are valid values:

The default value is The default value is TextFieldAutoSize.NONE..


Implementation
    public function get autoSize():String
    public function set autoSize(value:String):void
clearIconModeproperty 
clearIconMode:int

Gets or sets a value that determines how the clear button appears in the text field.


Implementation
    public function get clearIconMode():int
    public function set clearIconMode(value:int):void

See also

TextInputIconMode
displayAsPasswordproperty 
displayAsPassword:Boolean

Gets or sets a Boolean that determines whether text should be masked.

When set to true, any character entered into the TextInput instance will appear as an asterisk.

A textInputfield with the clear text icon enabled.


Implementation
    public function get displayAsPassword():Boolean
    public function set displayAsPassword(value:Boolean):void
embedFontsproperty 
embedFonts:Boolean

Gets or sets the embedFonts property of the internal TextField of the label.

When set to false, fonts are rendered as device fonts. When set to true, you must specify a font using the font property of a TextFormat object and set it to the format property. This font must be included in the in your application. If it is not included, the text will not be rendererd.

The default value is false.


Implementation
    public function get embedFonts():Boolean
    public function set embedFonts(value:Boolean):void
formatproperty 
format:TextFormat

Gets or sets the TextFormat object of the label.

The TextFormat object is used to format and style the text of the label. The label has the following default text format:

In the following listing, a TextFormat object is created and applied to the TextInput field by setting the format property. 

        
        var myFormat:TextFormat = new TextFormat();
        myFormat.size = 18;
        myFormat.italic = true;
        myFormat.bold = true;
                    
        myInput = new TextInput();
        myInput.setPosition(200, 200);
        myInput.width = 300;
        myInput.format = myFormat;
        this.addChild(myInput);


Implementation
    public function get format():TextFormat
    public function set format(value:TextFormat):void
keyboardTypeproperty 
keyboardType:String

The virtual keyboard type to use when this text input has focus.

When the user touches a TextInput instance and the TextInput gains focus, a virtual keyboard slides in from the bottom of the screen. You can set the KeyboardType property to define the keyboard layout type that best suits the type of data that the TextInput instance will contain. The following virutal keyboard appears by default:


Implementation
    public function get keyboardType():String
    public function set keyboardType(value:String):void

See also

KeyboardType
ReturnKeyType
leftIconproperty 
leftIcon:DisplayObject

Gets or sets the left icon for the TextInput component.

The icon is sized and positioned according to the value that is returned from the getLeftIconRect method.


Implementation
    public function get leftIcon():DisplayObject
    public function set leftIcon(value:DisplayObject):void

See also

getLeftIconRect()
leftIconModeproperty 
leftIconMode:int

Gets or sets a value that controls how the left icon is displayed in the text field.


Implementation
    public function get leftIconMode():int
    public function set leftIconMode(value:int):void

See also

TextInputIconMode
leftIcon
maxCharsproperty 
maxChars:int

Gets or sets the maximum number of characters that the text field can contain, as entered by a user. A script can insert more text than maxChars allows; the maxChars property indicates only how much text a user can enter. If the value of this property is 0, a user can enter an unlimited amount of text.

The default value is 0.


Implementation
    public function get maxChars():int
    public function set maxChars(value:int):void
promptproperty 
prompt:String

Gets or sets the placeholder text that is displayed in the text field when there is no other text in the text field.


Implementation
    public function get prompt():String
    public function set prompt(value:String):void
restrictproperty 
restrict:String

Gets or sets the restrict property of the internal TextField. For more information, see Adobe's TextField ActionScript 3 reference.


Implementation
    public function get restrict():String
    public function set restrict(value:String):void
returnKeyDisableproperty 
returnKeyDisable:Boolean

When set to true the virtual keyboard return key is disabled, when this text input has focus.


Implementation
    public function get returnKeyDisable():Boolean
    public function set returnKeyDisable(value:Boolean):void
returnKeyTypeproperty 
returnKeyType:String

The virtual keyboard enter key type to use when this text input has focus.


Implementation
    public function get returnKeyType():String
    public function set returnKeyType(value:String):void

See also

KeyboardType
ReturnKeyType
rightIconproperty 
rightIcon:DisplayObject

Gets or sets the right icon for the TextInput component. The icon is sized and positioned according to the value that is returned from the getRightIconRect method.


Implementation
    public function get rightIcon():DisplayObject
    public function set rightIcon(value:DisplayObject):void

See also

getRightIconRect()
rightIconModeproperty 
rightIconMode:int

Gets or sets a value that controls how the right icon is displayed in the text field.


Implementation
    public function get rightIconMode():int
    public function set rightIconMode(value:int):void

See also

TextInputIconMode
rightIcon
textproperty 
text:String

Gets or sets the text String of the label.


Implementation
    public function get text():String
    public function set text(value:String):void
textFieldproperty 
textField:TextField  [read-only]

Gets a reference to the internal TextField of the Label.


Implementation
    public function get textField():TextField
textHeightproperty 
textHeight:int  [read-only]

Returns the height of the text in the label (in pixels).


Implementation
    public function get textHeight():int
textWidthproperty 
textWidth:int  [read-only]

Returns the width of the text in the label (in pixels).


Implementation
    public function get textWidth():int
Constructor Detail
TextInput()Constructor
public function TextInput()

Creates a TextInput instance.

Method Detail
getLeftIconRect()method
public function getLeftIconRect():Rectangle

Gets the position and size of the left icon.

Returns
Rectangle — Returns the rectangle in which the left icon occupies.

See also

leftIcon
getRightIconRect()method 
public function getRightIconRect():Rectangle

Gets the position and size of the right icon.

Returns
Rectangle — Returns the rectangle in which the right icon occupies.

See also

rightIcon
Event Detail
change Event
Event Object Type: flash.events.Event
Event.type property = flash.events.Event.CHANGE

Dispatched when the text in the input field is modified.

Examples
The following example creates a simple TextInput field that uses a URL-specific keyboard. 
package
{
    
    import flash.display.Sprite;
    
    import qnx.ui.text.KeyboardType;
    import qnx.ui.text.ReturnKeyType;
    import qnx.ui.text.TextInput;
    import qnx.ui.text.TextInputIconMode;
    
    [SWF(height="600", width="1024", frameRate="30",
    backgroundColor="#FFFFFF")]
    public class textInputSample extends Sprite
    {
        
        private var myInput:TextInput;
        
        public function textInputSample()
        {
            initializeUI();
        }
        
        private function initializeUI():void
        {
            myInput = new TextInput();
            myInput.setPosition(200, 200);
            myInput.width = 300;
            // set the keyboard type to be url
            myInput.keyboardType = KeyboardType.URL;
            myInput.returnKeyType = ReturnKeyType.DEFAULT;
            myInput.clearIconMode = TextInputIconMode.UNLESS_EDITING;
            this.addChild(myInput);
        }
    }
}



Copyright 2012 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Mon Jan 23 2012, 01:04 PM -05:00