uiTextArea

uiTextArea

The uiTextArea component is used to display multiline text, either editable or non-editable, with optional horizontal and vertical scrollbars. This component is a composite consisting of a uiTextInput, uiScrollBar and uiVScrollBar. The actual text-related functions are handled by the uiTextInput instance.

Using uiTextArea

ActionScript 3.0 Example

import com.ghostwire.ui.containers.uiBox;
import com.ghostwire.ui.controls.uiTextArea;
import com.ghostwire.ui.controls.uiCheckBox;
 
var txt:uiTextArea = new uiTextArea("Initial text...");
 
var editableCheck:uiCheckBox = new uiCheckBox("Editable");
editableCheck.addEventListener(Event.CHANGE,on_editCheck);
editableCheck.selected = true;
 
// ** box for easy layout **
var box:uiBox = new uiBox();
box.vertical = true;
box.addChild(txt);
box.addChild(editableCheck);
 
// ** add to display list **
addChild(box);
 
// ** checkbox toggle handler **
function on_editCheck(evt:Event):void
{
    txt.editable = editableCheck.selected;
}

ScrollBars

var txt:uiTextArea = new uiTextArea();
txt.hScrollPolicy = SCROLLBAR.ON;
txt.vScrollPolicy = SCROLLBAR.ON;

The hScrollPolicy property indicates whether a horizontal scroll bar should be shown (anchored at the bottom of the component instance). Qualified values are SCROLLBAR.ON (always shown), SCROLLBAR.OFF (never shown), or SCROLLBAR.AUTO (shown when it is needed/hidden when it is not needed)¹⁾. Any other values will set the property to SCROLLBAR.AUTO. The default value is SCROLLBAR.AUTO. Setting this property to SCROLLBAR.ON can improve performance.

NOTE: If hScrollPolicy is set to SCROLLBAR.OFF, the text will automatically wrap.

In order for the horizontal scroll bar to appear, the width of the uiTextArea instance must be greater than the desired width of the scroll bar (enough space to show the left/right arrow buttons).

The vScrollPolicy property indicates whether a vertical scroll bar should be shown (anchored on the right-hand-side of the component instance). Qualified values are as for hScrollPolicy. The default value is SCROLLBAR.AUTO. Setting this property to SCROLLBAR.ON can improve performance.

In order for the vertical scroll bar to appear, the height of the uiTextArea instance must be greater than the desired height of the scroll bar (enough space to show the up/down arrow buttons).

NOTE: The scroll bars are updated automatically during run-time if the scrollable area changes, ie if maxScrollH and/or maxScrollV of the embedded TextField instance changes. Note also that due to the fact that the Flash Player has a tendency to exaggerate the value of maxScrollH, horizontal scrolling may be present before it is really necessary.

Size

The uiTextArea has a fixed default size of 100px width and 100px height; the amount and size of the text displayed does not affect this default size. Use the setSize(width,height) method to set preferred dimensions.

var txt:uiTextArea = new uiTextArea();
txt.setSize(200,300);

The component will allocate enough space to the scroll bars first; the balance is then allocated to the content area.

"uitextinput"

The uiTextArea component embeds an instance of uiTextInput, which is responsible for all the text-related functions. You can access this instance via the uitextinput property.

User Interaction

While a uiTextArea instance has focus, the user can type inside the text field (if editable property is true), or use the following keys to interact with the control:

Key	Action
Arrow Keys	Moves the insertion caret position.*
Shift+Tab	Moves focus to previous UI control in the tab focus chain.
Tab	Moves focus to next UI control in the tab focus chain.

* If the text is non-editable and non-selectable, the scrolling by arrow keys will not work. This is due to a bug/limitation of the Flash Player. The text must be selectable for scrolling by arrow keys to work properly.

The user can also use the mouse wheel to scroll the text just like in the native TextField.

API Reference

For more information on the members of the com.ghostwire.ui.controls.uiTextArea class, please refer to the API Reference.

¹⁾ Import com.ghostwire.ui.enums.SCROLLBAR