View source

class StageText

package openfl.text

extends EventDispatcher

@:fileXml("tags=\"haxe,release\"")@:noDebug

Available on AIR, Android, Flash, Linux, Neko, Windows, iOS, macOS

The StageText class is used to present the user with a native text input field.

This class enables mobile applications to gather user input using native text input controls on mobile devices. Input controls on mobile devices often have extensive user interfaces and supporting behaviors that don't exist on the desktop. For example, many mobile devices support text input features like the following:

  • auto-complete
  • auto-correct
  • touch-based text selection
  • customizable soft keyboards

The underlying operating system (or a component library bundled with the operating system) draws native text input fields. Native text input fields provide an experience that is familiar to anyone who has used other applications on the same device. However, because the operating system draws the text input fields instead of the player, you cannot use embedded fonts.

OpenFL target support: On all platforms, except AIR, StageText uses the runtime TextField fallback.

Adobe AIR profile support: This feature is supported on iOS and Android platforms. StageText uses native text input fields on Android and iOS mobile devices. On other platforms, StageText uses the Flash Runtime TextField.

When native inputs are used, StageText objects are not display objects and you cannot add them to the Flash display list. Instead, you display a StageText object by attaching it directly to a stage using the stage property. The StageText instance attached to a stage is displayed on top of any OpenFL display objects. You control the size and position of the rendering area with the viewPort property. There is no way to control depth ordering of different StageText objects. Overlapping two instances is not recommended.

When a StageText object has focus, it has the first opportunity to handle keyboard input. The stage to which the StageText object is attached does not dispatch any keyboard input events.

Because the StageText class wraps a different native control on every platform, its features are supported to varying degrees by each platform. Where features are supported, they may behave differently between platforms. When you attempt to use a particular feature on a particular platform, it is best to test the behavior. Only on desktop platforms where native controls are not used is StageText behavior similar to runtime TextField behavior.

StageText on Apple TV takes focus by default. To manage focus between different objects in your application keep a note of below points:

  • To override default focus from StageText, or to assign focus to any other display object use stage.focus.
  • To assign focus to StageText, use stageText.assignFocus().

Constructor

@:value({ initOptions : null })new(?initOptions:StageTextInitOptions)

Creates a StageText object.

The StageText object is invisible until it is attached to a stage and until the viewPort property is set.

Variables

@:value(NONE)autoCapitalize:AutoCapitalize = NONE

Controls how a device applies auto capitalization to user input. Valid values are defined as constants in the AutoCapitalize class:

  • "none"
  • "word"
  • "sentence"
  • "all"

This property is only a hint to the underlying platform, because not all devices and operating systems support this functionality.

Note: If you enable autoCapitalize while text is being edited or otherwise in focus, the updated behavior isn't applied until focus is released and reestablished.

@:value(false)autoCorrect:Bool = false

Indicates whether a device auto-corrects user input for spelling or punctuation mistakes.

This property is only a hint to the underlying platform, because not all devices and operating systems support this functionality.

Note: If you enable autoCorrect while text is being edited or otherwise in focus, the updated behavior isn't applied until focus is released and reestablished.

@:value(WHILE_EDITING)clearButtonMode:StageTextClearButtonMode = WHILE_EDITING

The mode of the clear button for the current StageText object. There are four modes associated with this property:

Note: This property is supported for iOS only.

color:UInt

Specifies text color. You specify text color as a number containing three 8-bit RGB components. The first component represents red, the second represents green, and the third component represents blue. For example, 0xFF0000 specifies red, 0x00FF00 specifies green, and 0x0000FF specifies blue. The default text color is black (0x000000).

displayAsPassword:Bool

Indicates whether the text field is a password text field. If true, the text field hides input characters using a substitute character (for example, an asterisk).

Note: If you enable displayAsPassword while text is being edited or otherwise in focus, the updated behavior isn't applied until focus is released and reestablished.

Important: On iOS, a multiline stage text object does not display substitute characters even when the value of this property is true.

editable:Bool

Indicates whether the user can edit the text field.

fontFamily:String

Indicates the name of the current font family. A value of null indicate the system default. To enumerate the available fonts, use openfl.text.Font.enumerateFonts(). If the font family is unknown, the default font family is used.

fontPosture:FontPosture

Specifies the font posture, using constants defined in the FontPosture class.

fontSize:Int

The size in pixels for the current font family.

fontWeight:FontWeight

Specifies the font weight, using constants defined in the FontWeight class.

@:value("en")locale:String = "en"

Indicates the locale of the text. StageText uses the standard locale identifiers. For example "en", "en_US" and "en-US" are all English; "ja" is Japanese. See iso639-2 code list for a list of locale codes.

maxChars:Int

Indicates the maximum number of characters that a user can enter into the text field. A script can insert more text than maxChars allows. If maxChars equals zero, a user can enter an unlimited amount of text into the text field.

read onlymultiline:Bool

Indicates whether the StageText object can display more than one line of text. Read-only. This value matches that of the multiline property in the StageTextInitOptions object used during construction.

restrict:String

Restricts the set of characters that a user can enter into the text ield. The system scans the restrict string from left to right.

The value of restrict specifies the following text input restriction ules:

  • If the value is null, a user can enter any character.
  • If the value is an empty string, a user cannot enter any characters.
  • If the value is a string of characters, a user can enter only the characters in the string.
  • If the value includes a caret (^), a user cannot enter any characters that follow the caret.
  • The value can specify a range of allowable input characters by using the hyphen (-) character.
  • The value can use the \u escape sequence to construct a restrict string.

Special Characters:

Use a backslash to enter a caret (^) or dash (-) character verbatim. The accepted backslash sequences are -, \^ and . The backslash must be an actual character in the string. When you specify a backslash in Haxe, use a double backslash.

Examples of restrict property settings:

The following example allows a user to enter only the dash (-) and caret (^) characters:

my_txt.restrict = "\\-\\^";

The following example allows a user to enter only uppercase characters, spaces, and numbers:

my_txt.restrict = "A-Z 0-9";

The following example excludes only lowercase letters:

my_txt.restrict = "^a-z";

The following example allows a user to enter only uppercase letters, but excludes the uppercase letter Q:

my_txt.restrict = "A-Z^Q";

The following example allows a user to enter only the characters from ASCII 32 (space) to ASCII 126 (tilde).

my_txt.restrict = "\u0020-\u007E";

Note: Restrictions apply only to user input; a script can insert any characters into the text field.

@:value(DEFAULT)returnKeyLabel:ReturnKeyLabel = DEFAULT

Indicates the label on the Return key for devices that feature a soft keyboard. The available values are constants defined in the ReturnKeyLabel class:

  • "default"
  • "done"
  • "go"
  • "next"
  • "search"

This property is only a hint to the underlying platform, because not all devices and operating systems support these values. This property has no effect on devices that do not feature a soft keyboard.

read onlyselectionActiveIndex:Int

The zero-based character index value of the last character in the current selection. For example, the first character is 0, the second character is 1, and so on.

If no text is selected, this method returns the insertion point. If the StageText instance does not have focus, this method returns -1.

On iOS, this property is not supported for for non-multiline StageText objects and returns -1.

read onlyselectionAnchorIndex:Int

The zero-based character index value of the first character in the current selection. For example, the first character is 0, the second character is 1, and so on.

If no text is selected, this method returns the insertion point. If the StageText instance does not have focus, this method returns -1.

On iOS, this property is not supported for for non-multiline StageText objects and returns -1.

@:value(DEFAULT)softKeyboardType:SoftKeyboardType = DEFAULT

Controls the appearance of the soft keyboard.

Devices with soft keyboards can customize the keyboard's buttons to match the type of input expected. For example, if numeric input is expected, a device can use SoftKeyboardType.NUMBER to display only numbers on the soft keyboard. Valid values are defined as constants in the SoftKeyboardType class:

  • "default"
  • "punctuation"
  • "url"
  • "number"
  • "contact"
  • "email"
  • "phone"
  • "decimalpad"

These values serve as hints, to help a device display the best keyboard for the current operation.

stage:Stage

The stage on which this StageText object is displayed.

Set stage to null to hide this StageText object.

text:String

The current text in the text field. The carriage return character ('\r', ASCII 13) separates lines of text. Text contained in this property is unformatted (it has no formatting tags).

textAlign:TextFormatAlign

Indicates the paragraph alignment. Valid values are defined as constants in the TextFormatAlign class:

- "left" - "center" - "right" - "justify" - "start" - "end"

Not all platforms support every textAlign value. For unsupported textAlign values, platforms use the default value (TextFormatAlign.START).

viewPort:Rectangle

The area on the stage in which the StageText object is displayed. The default is the zero rect.

visible:Bool

Indicates whether the StageText object is visible. StageText objects that are not visible are disabled.

Methods

assignFocus():Void

Assigns focus to the StageText object. For non-editable objects, assignFocus() does nothing.

dispose():Void

Disposes of the StageText object.

Calling dispose() is optional. If you do not maintain a reference to this StageText instance, it is eligible for garbage collection. Calling dispose() can make garbage collection occur sooner, or occur at a more convenient time.

drawViewPortToBitmapData(bitmapData:BitmapData):Void

Draws the StageText's view port to a bitmap.

Capture the bitmap and set the stage to null to display the content above the StageText object.

The bitmap is typically the same width and height as the viewport. Starting with AIR 15.0, when the player is on HiDPI displays, the bitmap's width and height can optionally be contentsScaleFactor times the width and height of the viewport. For instance, on a Mac Retina Display, contentsScaleFactor is 2, because the pixel resolution of the stage is doubled, so the bitmap can correspondingly be twice the size of the viewport.

If you call this method before the Event.COMPLETE event, the method could draw the view port incorrectly.

selectRange(anchorIndex:Int, activeIndex:Int):Void

Selects the text specified by the index values of the first and last characters. You specify the first and last characters of the selection in the anchorIndex and activeIndex parameters. If both parameter values are the same, this method sets the insertion point.

On iOS, for non-multiline StageText objects, this function is not supported and always returns -1. If you call this method selecting the complete text string, the selection is visible. However, if you call this method selecting a subset of the text string, the selection is not visible.

For some devices or operating systems, the selection is only visible when the StageText object has focus.

Inherited Variables

Inherited Methods

Defined by EventDispatcher

@:value({ useWeakReference : false, priority : 0, useCapture : false })addEventListener<T>(type:EventType<T>, listener:T ‑> Void, useCapture:Bool = false, priority:Int = 0, useWeakReference:Bool = false):Void

Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. You can register event listeners on all nodes in the display list for a specific type of event, phase, and priority.

After you successfully register an event listener, you cannot change its priority through additional calls to addEventListener(). To change a listener's priority, you must first call removeListener(). Then you can register the listener again with the new priority level.

Keep in mind that after the listener is registered, subsequent calls to addEventListener() with a different type or useCapture value result in the creation of a separate listener registration. For example, if you first register a listener with useCapture set to true, it listens only during the capture phase. If you call addEventListener() again using the same listener object, but with useCapture set to false, you have two separate listeners: one that listens during the capture phase and another that listens during the target and bubbling phases.

You cannot register an event listener for only the target phase or the bubbling phase. Those phases are coupled during registration because bubbling applies only to the ancestors of the target node.

If you no longer need an event listener, remove it by calling removeEventListener(), or memory problems could result. Event listeners are not automatically removed from memory because the garbage collector does not remove the listener as long as the dispatching object exists(unless the useWeakReference parameter is set to true).

Copying an EventDispatcher instance does not copy the event listeners attached to it.(If your newly created node needs an event listener, you must attach the listener after creating the node.) However, if you move an EventDispatcher instance, the event listeners attached to it move along with it.

If the event listener is being registered on a node while an event is being processed on this node, the event listener is not triggered during the current phase but can be triggered during a later phase in the event flow, such as the bubbling phase.

If an event listener is removed from a node while an event is being processed on the node, it is still triggered by the current actions. After it is removed, the event listener is never invoked again(unless registered again for future processing).

Parameters:

type

The type of event.

useCapture

Determines whether the listener works in the capture phase or the target and bubbling phases. If useCapture is set to true, the listener processes the event only during the capture phase and not in the target or bubbling phase. If useCapture is false, the listener processes the event only during the target or bubbling phase. To listen for the event in all three phases, call addEventListener twice, once with useCapture set to true, then again with useCapture set to false.

priority

The priority level of the event listener. The priority is designated by a signed 32-bit integer. The higher the number, the higher the priority. All listeners with priority n are processed before listeners of priority n-1. If two or more listeners share the same priority, they are processed in the order in which they were added. The default priority is 0.

useWeakReference

Determines whether the reference to the listener is strong or weak. A strong reference(the default) prevents your listener from being garbage-collected. A weak reference does not.

Class-level member functions are not subject to garbage collection, so you can set useWeakReference to true for class-level member functions without subjecting them to garbage collection. If you set useWeakReference to true for a listener that is a nested inner function, the function will be garbage-collected and no longer persistent. If you create references to the inner function(save it in another variable) then it is not garbage-collected and stays persistent.

Weak references are supported on some OpenFL targets only, including html5, cpp, and flash/air. On other targets, this parameter is ignored, and the reference will be strong instead.

Throws:

ArgumentError

The listener specified is not a function.

dispatchEvent(event:Event):Bool

Dispatches an event into the event flow. The event target is the EventDispatcher object upon which the dispatchEvent() method is called.

Parameters:

event

The Event object that is dispatched into the event flow. If the event is being redispatched, a clone of the event is created automatically. After an event is dispatched, its target property cannot be changed, so you must create a new copy of the event for redispatching to work.

Returns:

A value of true if the event was successfully dispatched. A value of false indicates failure or that preventDefault() was called on the event.

Throws:

Error

The event dispatch recursion limit has been reached.

hasEventListener(type:String):Bool

Checks whether the EventDispatcher object has any listeners registered for a specific type of event. This allows you to determine where an EventDispatcher object has altered handling of an event type in the event flow hierarchy. To determine whether a specific event type actually triggers an event listener, use willTrigger().

The difference between hasEventListener() and willTrigger() is that hasEventListener() examines only the object to which it belongs, whereas willTrigger() examines the entire event flow for the event specified by the type parameter.

When hasEventListener() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

type

The type of event.

Returns:

A value of true if a listener of the specified type is registered; false otherwise.

@:value({ useCapture : false })removeEventListener<T>(type:EventType<T>, listener:T ‑> Void, useCapture:Bool = false):Void

Removes a listener from the EventDispatcher object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.

Parameters:

type

The type of event.

useCapture

Specifies whether the listener was registered for the capture phase or the target and bubbling phases. If the listener was registered for both the capture phase and the target and bubbling phases, two calls to removeEventListener() are required to remove both, one call with useCapture() set to true, and another call with useCapture() set to false.

toString():String

willTrigger(type:String):Bool

Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. This method returns true if an event listener is triggered during any phase of the event flow when an event of the specified type is dispatched to this EventDispatcher object or any of its descendants.

The difference between the hasEventListener() and the willTrigger() methods is that hasEventListener() examines only the object to which it belongs, whereas the willTrigger() method examines the entire event flow for the event specified by the type parameter.

When willTrigger() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

type

The type of event.

Returns:

A value of true if a listener of the specified type will be triggered; false otherwise.