Skip to content

You are here: Creating a TextArea Using a Constructor: voltmx.ui.TextArea2

TextArea Widget

The TextArea widget allows you to enter multiple lines of text. It inherits all the properties of the TextBox widget.

Following are the key use cases of Text Area widget:

  • Feedback: User feedback can comprise multiple lines of text. Text Area widget is apt in all the scenarios where the feedback of user is taken.

  • Comments Section: Text Area widget is apt for the applications that support usersā€™ comments. For instance, consider the following screen from the Resorts application. Here, users can provide comments on their requirements.

  • Address Field: Address generally comprises multiple lines. Text Area widget is used for the address field in the user profile.

  • Text messages: Text Area widget is used in all the social networking applications for sending messages.

Note: In Windows platform, when a FlexForm has multiple TextArea/ TextBox widgets, and none of the widgets are in focus, the focus control of the form moves to the first focussable widget. This will also make the Form scroll up to the first widget.

Widgets are normally added to your application using Volt MX Iris, but can also be added from code. For general information on using widgets in Volt MX Iris, see Designing an Application in the Iris User Guide.

For general information on the TextArea2 widget see the TextArea2 topic in the Volt MX Iris User Guide.

This widget supports drag and drop of text for iOS 11 on iPad.

The TextArea widget capabilities can be broadly categorized into the following:

Layout

Events Description
doLayout Invoked for every widget when the widget position and dimensions are computed.
Properties Description
bottom Determines the bottom edge of the widget and is measured from the bottom bounds of the parent container.
centerX Determines the center of a widget measured from the left bounds of the parent container.
centerY Determines the center of a widget measured from the top bounds of the parent container.
contentAlignment Specifies the alignment of the text for a widget with respect to its boundaries.
height Determines the height of the widget and measured along the y-axis.
left Determines the lower left corner edge of the widget and is measured from the left bounds of the parent container.
maxHeight Specifies the maximum height of the widget and is applicable only when the height property is not specified.
maxWidth Specifies the maximum width of the widget and is applicable only when the width property is not specified.
minHeight Specifies the minimum height of the widget and is applicable only when the height property is not specified.
minWidth Specifies the minimum width of the widget and is applicable only when the width property is not specified.
padding Defines the space between the content of the widget and the widget boundaries.
paddingInPixel Indicates if the padding is to be applied in pixels or in percentage.
right Determines the lower right corner of the widget and is measured from the right bounds of the parent container.
top Determines the top edge of the widget and measured from the top bounds of the parent container.
width Determines the width of the widget and is measured along the x-axis.
zIndex Specifies the stack order of a widget.

Data Management

Methods Description
clone When this method is used on a container widget, then all the widgets inside the container are cloned.
Events Description
onBeginEditing This is an event callback that is invoked by the platform when the user clicks within the TextArea and is about to start editing.
onDone This event is triggered when user is done with entering text in textarea and click or touch the Go or Enter option.
onEndEditing This is an event callback that is invoked by the platform.
onTextChange This is an event callback triggered when text in the TextArea changes.
Properties Description
autoCapitalize Specifies the character capitalization behavior.
autoCorrect Determines whether auto-correction is enabled or disabled during typing.
autoSuggestions Used to enable or disable suggestions such as spell checker, predictive text and corrections in the application.
closeButtonText Specifies the text to replace the "Done" button that appears in the Keypad (opens when you select a textbox).
isSensitiveText Used to secure the text entered in a TextArea widget.
keyboardActionLabel Specifies if the text to be displayed in action key of the keyboard.
maxTextLength Specifies the maximum number of characters that the text field can accept.
placeholder Specifies a short hint that describes the expected value of an input field (example, a sample value or a short description of the expected format).
restrictCharactersSet Restricts users from entering a set of input characters from the soft keyboard in the TextArea widget.
secureTextEntry Specifies whether the text entered by the user will be secured using a mask character, such as asterisk or dot.
text Specifies a general or descriptive text for the TextArea widget.
textInputMode Specifies the type of input characters that a user can enter into the TextArea widget.
toolTip Specifies the hint text when the cursor hovers over a widget, without clicking it.
wrapText Allows you to specify whether text in the TextArea Widget should be wrapped or not.

Animations

Methods Description
animate Applies an animation to the widget.
Properties Description
transform Contains an animation transformation that can be used to animate the widget.
widgetSwipeMove Used to enable and configure the left or right swipe actions for a widget.

3D Touch

Methods Description
registerForPeekandPop Registers a widget to enable 3D Touch peek and pop gestures.
setOnPeek Sets and overrides the existing onPeekCallback for the widget.
setOnPop Overrides the existing onPopCallback for the widget.
unregisterForPeekandPop Unregisters a widget from 3D Touch peek and pop gestures.

User Input Handling

Methods Description
addGestureRecognizer Allows you to set a gesture recognizer for a specified gesture for a specified widget.
removeGestureRecognizer Allows you to remove the specified gesture recognizer for the specified widget.
setGestureRecognizer Allows you to set a gesture recognizer for a specified gesture for a specified widget.
Events Description
onBackKeyPress This event callback is invoked when the back button of an Android mobile device is clicked.
onKeyBoardDidHide This event callback is invoked when the soft keyboard of an Android device has been closed.
onKeyboardDidShow This event callback is invoked after the soft keyboard of an Android device appears.
onKeyboardWillHide This event callback is invoked when the soft keyboard of an Android device is about to close.
onKeyboardWillShow This event callback is invoked when the soft keyboard of an Android device is about to appear.
onKeyDown This event callback that is invoked by the platform when the user presses a key (on the keyboard).
onKeyUp This event callback that is invoked by the platform when the user releases a key (on the keyboard).
onScrollWidgetPosition This event callback is invoked by the platform when the widget location position gets changed on scrolling.
Properties Description
isSelectable Enables you to select the content inside the TextArea
smartDashes Allows you to insert hyphens without space in the text.
smartInsertDelete Enables you to add a space when you copy and paste a text.
smartQuotes Enables you to add curly quotes in the text.
textCopyable Enable or disable the cut, copy and, paste of the text.

UI Appearance

Properties Description
backgroundColor Specifies the background color of the widget in hex format.
backgroundColorMultiStepGradient Specifies the multi-step gradient color for the background of the widget.
backgroundColorTwoStepGradient Specifies the two-step gradient color for the background of the widget.
backgroundImage Sets the image for the background of the widget.
borderColor Specifies the border color of the widget.
borderColorGradient Specifies the multi-step gradient color for the border of the widget.
borderStyle Specifies the border style for the widget.
borderWidth Specifies the width of the border for the widget in pixels.
cornerRadius Specifies the radius of the border for the widget.
disabledStateSkinProperties Specifies the skin properties that define the look and feel of the widget, when the widget is disabled or blocked.
focusStateSkinProperties Specifies the skin properties that define the look and feel of the widget, when the widget is in focus.
fontColor Specifies the font color of the widget.
fontFamily Specifies the font family for the font of the widget.
fontSize Specifies the font size for the widget in percentage (%) units.
fontStyle Specifies the font style for the widget.
fontWeight Specifies the weight for the font of the widget.
hoverStateSkinProperties Specifies the skin properties that define the look and feel of the widget, when the cursor hovers on the widget.
pressedStateSkinProperties Specifies the skin properties that define the look and feel of the widget, when the widget is pressed or clicked.
shadowColor Specifies the color for the shadow of the widget.
shadowOffset This property specifies the current coordinates of the shadow region in the widget.
shadowRadius Specifies the radius for the blur value of the shadow.
textShadowColor Specifies the color for the text shadow of the widget.
textShadowOffset This property specifies the current coordinates of the text shadow region in the widget.
textShadowRadius Specifies the radius for the blur value of the text shadow.
focusSkin Specifies the look and feel of the widget when in focus.
hoverSkin Specifies the look and feel of a widget when the cursor hovers on the widget.
keyboardAppearance Allows you to set the on screen keyboard to a dark or light color scheme.
keyBoardStyle When you interact with a TextBox widget, a keyboard is displayed.
nativeThumbLook Provides the native thumb look of the Switch.
opacity Specifies the opacity of the widget.
placeholderSkin Specifies the skin to be applied to the placeholder text in the TextArea widget.
skin Specifies a background skin for Switch widget.
shadowDepth Defines the depth of the shadow effect applied to the TextArea Widget.
shadowType Sets a type of the shadow effect to apply to the TextArea Widget.
showCloseButton Specifies if the "Done" button that appears in the keypad (opens when you select text box) must be visible or not.
showProgressIndicator Specifies if there must be an indication to the user that the widget content is being loaded.

Enabling RTL

Properties Description
retainContentAlignment Helps to retain the content alignment of the widget while applying RTL.
retainFlexPositionProperties Helps to retain the left, right and padding properties while applying RTL.
retainFlowHorizontalAlignment Enables you to change the horizontal flow of the widget from left to right.

Miscellaneous

Properties Description
cursorType Specifies the type of the mouse pointer used.
enableHapticFeedback Allows you to enable or disable haptic feedback on the TextArea widget.
inputAccessoryViewType The extra buttons (or controls) allow specific operations needed by your application, such as moving to the next or previous text field, making the keyboard disappear and so on. The area above the keyboard is known as Input Accessory View
selectedIndex Accessible only from code and it specifies the option of the Switch that must be shown as selected when rendered.
Methods Description
getBadge Enables you to read the badge value (if any) attached to the specified widget.
setBadge Enables you to set the badge value to the given widget at the upper, right corner of the widget.

Configurations Common To All Widgets

Properties Description
accessibilityConfig Enables you to control accessibility behavior and alternative text for the widget.
enable Allows you to make a widget visible but not actionable.
enableCache Enables you to improve the performance of Positional Dimension Animations.
id A unique identifier of TextArea consisting of alpha numeric characters.
info A custom JSObject with the key value pairs that a developer can use to store the context with the widget.
isVisible Controls the visibility of a widget on the form.
parent Helps you access the parent of the widget.
Methods Description
convertPointFromWidget Allows you to convert the coordinate system from a widget to a point (receiver's coordinate system).
convertPointToWidget Allows you to convert the coordinate system from a point (receiver's coordinate system) to a widget.
removeFromParent Allows you to remove a child widget from a parent widget.
setEnabled Specifies the widget that must be enabled or disabled.
setFocus Specifies the widget on which there must be focus.
setVisibility Use this method to set the visibility of the widget.

TextArea2 Widget Basics

TextArea is used to provide an editable field for the user to enter text which spans over multiple lines .

Note: The TextArea widget inherits all the properties of the TextBox widget.

Creating a TextArea Using a Constructor: voltmx.ui.TextArea2


var setTextArea1 = new voltmx.ui.TextArea2 (basicConf, layoutConf, pspConf);
  • basicConf is an object with basic properties.
  • layoutConf is an object with layout properties.
  • pspConf is an object with platform specific properties.

Note: The configuration properties should be passed only in the respective configuration objects otherwise they are ignored

Example

//Defining properties for TextArea.
var tAreaBasic = {
    id: "txtArea",
    skin: "txtSkin",
    focusSkin: "txtFSkin",
    text: "Text",
    maxTextLength: 20,
    isVisible: true,
    secureTextEntry: true,
    placeholder: "enter text"
};

var tAreaLayout = {
    padding: [5, 5, 5, 5],
    margin: [5, 5, 5, 5],
    containerWeight: 100,
    hExpand: true,
    widgetAlignment: constants.WIDGET_ALIGN_TOP_LEFT
};

var tAreaPSP = {
    keyboardActionLabel: constants.TEXTAREA_KEYBOARD_LABEL_SEND,
    pasteboardType: constants.TEXTAREA_PASTE_BOARD_TYPE_SYSTEM_LEVEL,
    showProgressIndicator: true
};
//Creating the TextArea.
var txtArea = new voltmx.ui.TextArea2(tAreaBasic, tAreaLayout, tAreaPSP);

//Reading the widgetAlignment of the TextArea.  
alert("TextArea widgetAlignment ::" + txtArea.widgetAlignment);

Customizing Appearance

You can customize the appearance of the TextArea widget using the following properties:

  • widgetAlignment: Specifies the alignment of the widget.
  • margin: Defines the space around the widget.
  • padding: Defines the space between the content of the widget and the widget boundaries.
  • skin: Specifies the skin.
  • focusSkin: Specifies the focus skin.

Important Considerations

The following are the important considerations for the TextArea widget:

  • Editing on devices with small form factor takes place in a new screen.
  • Editing on devices with medium or large form factor takes place in the same screen.