TextBox2 Widget

The TextBox widget enables you to get a single-line input from users. This widget can accept input from the users in the form of numbers or text.

Here are some of scenarios where you can use a TextBox widget:

  • Getting the username and password on a login screen and the details on a sign-up screen
  • Entering purchase details while shopping online
  • Searching through a list of data to provide the relevant search results
  • Providing details while booking a flight or hotel

Some key features of the TextBox widget are as follows:

Various Input Types: Customize the soft keypad of any device. You can specify whether the soft keypad should be numeric or not, whether it should have cancel, search, done, or next and previous buttons, and much more.

Text Masking: Mask the entered text for security purposes. This feature is useful when you are designing password and payment details page.

Searching through a list: Provide a list of search items, and the TextBox widget can search through the list and generate search results. For instance, while providing the address of a user, you can create a list with all the states of a country. If the user types an alphabet, all the states that start with the alphabet A are displayed.

Restricting Input: Set certain characters that you do not want a user to use as input. This is useful when you want the user to decide a username for your application. If you want the user to not enter certain characters, for example, ‘$#@’. You can restrict the usage of these characters by using a TextBox widget.

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

For general information on the TextBox2 widget see the TextBox2 topic in the Quantum Visualizer User Guide.

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

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

Layout

Properties Description
anchorPoint Specifies the anchor point of the widget bounds rectangle using the widget's coordinate space.
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.
   
EventsDescription
doLayout This event is invoked for every widget when the widget position and dimensions are computed.
 

Data Management

PropertiesDescription
autoCapitalize Specifies the character capitalization behavior.
autoCompleteautoComplete property enables users to quickly find and select from a prepopulated list of values as they type, leveraging searching and filtering.
autoCorrect Determines whether auto-correction is enabled or disabled during typing.
autoFilter Specifies if the input characters you enter in the TextBox widget must be matched against the filterList and possible matches be displayed.
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).
isSensitiveTextUsed to secure the text entered in a TextBox widget.
filterList The values you enter in the TextBox are matched against this list and possible matches are displayed.
keyboardActionLabel Specifies 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 TextBox widget.
secureTextEntry Specifies whether the text entered by the user will be secured using a mask character, such as asterisk or dot.
setImportantForAutoFillSpecifies whether the TextBox widget should get preference to show suggestions while entering data.
text Specifies a general or descriptive text for the TextBox widget.
textContentTypeSpecifies the type of soft keyboard to be displayed when a user can enters data in the TextBox widget.
textInputMode Specifies the type of input characters that a user can enter into the TextBox widget.
 
MethodsDescription
clone When this method is used on a container widget, then all the widgets inside the container are cloned.
 
EventsDescription
onBeginEditing This is an event callback that is invoked by the platform when the user clicks within the TextBox and is about to start editing.
onCancel This event is a callback that is invoked by the platform then the user performs a click action on the Cancel button.
onDone This event is a callback that is invoked by the platform then the user performs a click action on the Go or Enter button.
onEndEditing This is an event callback that is invoked by the platform.
onTextChange This is an event callback triggered when text in the text box changes.

Animations

MethodsDescription
animateApplies an animation to the widget.
 
PropertiesDescription
transformContains an animation transformation that can be used to animate the widget.
widgetSwipeMoveUsed to enable and configure the left or right swipe actions for a widget.

3D Touch

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

 

User Input Handling

MethodsDescription
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.
 
EventsDescription
onBackKeyPressThis event callback is invoked when the back button of an Android mobile device is clicked.
onKeyBoardDidHideThis event callback is invoked when the soft keyboard of an Android device has been closed.
onKeyboardDidShowThis event callback is invoked after the soft keyboard of an Android device appears.
onKeyboardWillHideThis event callback is invoked when the soft keyboard of an Android device is about to close.
onKeyboardWillShowThis event callback is invoked when the soft keyboard of an Android device is about to appear.
onKeyDown This is an event callback that is invoked by the platform when the user presses a key (on the keyboard).
onKeyUp This is an event callback that is invoked by the platform when the user releases a key (on the keyboard).
onTouchEnd An event callback is invoked by the platform when the user touch is released from the touch surface.
onTouchMove An event callback is invoked by the platform when the touch moves on the touch surface continuously until movement ends.
onTouchStart An event callback is invoked by the platform when the user touches the touch surface.
onScrollWidgetPosition This event callback is invoked by the platform when the widget location position gets changed on scrolling.

 

PropertiesDescription
isSelectableEnables you to select the content inside the TextBox
smartDashesAllows you to insert hyphens without space in the text.
smartInsertDeleteEnables you to add a space when you copy and paste a text.
smartQuotesEnables you to add curly quotes in the text.
textCopyableEnable or disable the cut, copy and, paste of the text.

UI Appearance

PropertiesDescription
backgroundColorSpecifies the background color of the widget in hex format.
backgroundColorMultiStepGradientSpecifies the multi-step gradient color for the background of the widget.
backgroundColorTwoStepGradientSpecifies the two-step gradient color for the background of the widget.
backgroundImageSets the image for the background of the widget.
borderColorSpecifies the border color of the widget.
borderColorGradientSpecifies the multi-step gradient color for the border of the widget.
borderStyleSpecifies the border style for the widget.
borderWidthSpecifies the width of the border for the widget in pixels.
cornerRadiusSpecifies the radius of the border for the widget.
disabledStateSkinPropertiesSpecifies the skin properties that define the look and feel of the widget, when the widget is disabled or blocked.
focusStateSkinPropertiesSpecifies the skin properties that define the look and feel of the widget, when the widget is in focus.
fontColorSpecifies the font color of the widget.
fontFamilySpecifies the font family for the font of the widget.
fontSizeSpecifies the font size for the widget in percentage (%) units.
fontStyleSpecifies the font style for the widget.
fontWeightSpecifies the weight for the font of the widget.
hoverStateSkinPropertiesSpecifies the skin properties that define the look and feel of the widget, when the cursor hovers on the widget.
pressedStateSkinPropertiesSpecifies the skin properties that define the look and feel of the widget, when the widget is pressed or clicked.
shadowColorSpecifies the color for the shadow of the widget.
shadowOffsetThis property specifies the current coordinates of the shadow region in the widget.
shadowRadiusSpecifies the radius for the blur value of the shadow.
textShadowColorSpecifies the color for the text shadow of the widget.
textShadowOffsetThis property specifies the current coordinates of the text shadow region in the widget.
textShadowRadiusSpecifies the radius for the blur value of the text shadow.
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.
leftViewImage Specifies an optional image to be displayed on the left-hand side of a TextBox widget.
nativeListFieldFocusSkin Specifies the skin that is applied to a focused item in the native popup.
nativeListFieldSkin Specifies the skin that is applied to each item in the native popup (the list of items are displayed and a pop up appears just below the text field) that appears when you enter a value in the TextBox.
opacitySpecifies the opacity of the widget.
shadowType Sets a type of the shadow effect to apply to the TextBox Widget.
shadowDepth Defines the depth of the shadow effect applied to the TextBox Widget.
showClearButton Specifies if a "Clear" button must be provided.
showCloseButton Specifies if the "Done" button that appears in the keypad (opens when you select text box) must be visible or not.
skinSpecifies the look and feel of the widget when not in focus.
viewTypeSpecifies the appearance of the Textbox as Search view or a textbox to accept text input.

Enabling RTL

PropertiesDescription
retainContentAlignmentHelps to retain the content alignment of the widget while applying RTL.
retainFlexPositionPropertiesHelps to retain the left, right and padding properties while applying RTL.
retainFlowHorizontalAlignmentEnables you to change the horizontal flow of the widget from left to right.

Miscellaneous

MethodsDescription
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.

 

PropertiesDescription
cursorTypeSpecifies the type of the mouse pointer used.
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
enableHapticFeedbackAllows you to enable or disable haptic feedback on the TextBox widget.
toolTip Specifies the hint text when the cursor hovers over a widget, without clicking it.

Configurations Common To All Widgets

MethodsDescription
blurEnables you to make the widget look unfocused.
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.
enableAllows you to make a widget visible but not actionable.
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.

 

PropertiesDescription
accessibilityConfig Enables you to control accessibility behavior and alternative text for the widget.
enableAllows you to make a widget visible but not actionable.
enableCache Enables you to improve the performance of Positional Dimension Animations.
idid is a unique identifier of TextBox consisting of alpha numeric characters.
infoA custom JSObject with the key value pairs that a developer can use to store the context with the widget.
isVisibleThis property controls the visibility of a widget on the form.
ParentHelps you access the parent of the widget.

 

EventsDescription
postOnclickJS This event allows the developer to execute custom javascript function after the onClick callback of the widget is invoked.
preOnclickJS This event allows the developer to execute custom javascript function before the onClick callback of the widget is invoked.

TextBox2 Widget Basics

You can use the TextBox widget to provide a field where a user can enter input text.
For example, in the "Login" page of an Application, you can place two TextBox widgets for Login Password fields and instruct the users to enter their login credentials in those fields.

Creating an TextBox Using a Constructor: kony.ui.TextBox2



var mytextbox = new kony.ui.TextBox2 (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 the properties for a Textbox with isVisible: true.
var txtBasic = {
    id: "textBox1",
    placeholder: "enter text",
    maxTextLength: 20,
    isVisible: true,
    autoCapitalize: constants.TEXTBOX_AUTO_CAPITALIZE_SENTENCES
};

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

var txtPSP = {
    pasteboardType: constants.TEXTBOX_PASTE_BOARD_TYPE_SYSTEM_LEVEL,
    keyboardActionLabel: constants.TEXTBOX_KEYBOARD_LABEL_GOOGLE
};
//Creating the Textbox.
var textBox1 = new kony.ui.TextBox2(txtBasic, txtLayout, txtPSP);

//Reading the autoCapitalize of the Textbox.	
alert("Textbox autoCapitalize ::" + textBox1.autoCapitalize);

For backward compatibility with support for all deprecated properties and behaviors, use the constructor kony.ui.TextBox.



var myTextBox = new kony.ui.TextBox(basicConf, layoutConf, pspConf)

Changing the Text Size through the Larger Text option in iOS

You can now change the text size of TextBox widget through the Larger Text option from Settings -> General -> Accessibility -> Larger Text in iOS.

To support this feature, you must implement the 'dynamicTypeList' dictionary in the kony.application.setApplicationBehaviors function as follows:

kony.application.setApplicationBehaviors({
    dynamicTypeList: {
        enableChangeTextSizeFromAccessibility: true,
        fontTextStyle: constants.FONT_TEXT_STYLE_BODY
    }
});

Input Parameters

  • enableChangeTextSizeFromAccessibility (BOOL): If set to true, you can change the text size through the Larger Text option from Settings -> General -> Accessibility -> Larger Text in iOS. Otherwise, the text size will not be changed.
  • fontTextStyle: This is the font style applied on the TextBox widget. If you pass only the enableChangeTextSizeFromAccessibility key-value pair in the dictionary and don’t send the fontTextStyle key-value pair, the default value for fontTextStyle will be constants.FONT_TEXT_STYLE_BODY. The values for fontTextStyle are as follows:
    • constants.FONT_TEXT_STYLE_BODY

    • constants.FONT_TEXT_STYLE_HEADLINE

    • constants.FONT_TEXT_STYLE_SUBHEADLINE

    • constants.FONT_TEXT_STYLE_FOOTNOTE

    • constants.FONT_TEXT_STYLE_CAPTION1

    • constants.FONT_TEXT_STYLE_CAPTION2

    • constants.FONT_TEXT_STYLE_TITLE1 (available in iOS 9.0 and later)

    • constants.FONT_TEXT_STYLE_TITLE2 (available in iOS 9.0 and later)

    • constants.FONT_TEXT_STYLE_TITLE3 (available in iOS 9.0 and later)

    • constants.FONT_TEXT_STYLE_CALLOUT (available in iOS 9.0 and later)

    • constants.FONT_TEXT_STYLE_LARGETITLE (available in iOS 11.0 and later)

Platform Availability

  • iOS

Limitations

  • If you enable this feature, the font size and font family from the respective skin is not respected.
  • This feature is available only in iOS.

Customizing Appearance

You can customize the appearance of the TextBox 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.