RichText Widget

A RichText widget displays a user defined HTML string. It is capable of displaying text, links and images.

Following are a few real-time examples of RichText widget:

  • You can display subscript or superscript using the RichText widget. For instance, when you want to write display percentages, you must use superscripts.
  • You can use RichText widget for links.

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 RichText widget see the RichText topic in the Quantum Visualizer User Guide.

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

The RichText 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
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.

Animations

Methods Description
animate Applies 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.
 

Data Management

MethodsDescription
cloneWhen this method is used on a container widget, then all the widgets inside the container are cloned.
 
PropertiesDescription
appendsHTTPForHyperLinksEnables you to add HTTP to the hyperlinks in the text of the RichText widget.
breakStrategySpecifies the method to perform line breaks on paragraphs of text in RichText widget.
hyphenationFrequencySets the periodicity in which words break in a text in RichText widget.
textSpecifies a general or descriptive text for the RichText widget.
toolTip Specifies the hint text when the cursor hovers over a widget, without clicking it.

 

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 Overrides the existing onPopCallback for the widget.
unregisterForPeekandPop Unregisters a widget from 3D Touch peek and pop gestures.

Gestures

EventsDescription
onClick Invoked by the platform when the user performs a click action on the portion of the text only where a link is defined.
onScrollWidgetPosition Invoked by the platform when the widget location position gets changed on scrolling.
onTouchEnd Invoked by the platform when the user touch is released from the touch surface.
onTouchMove Invoked by the platform when the touch moves on the touch surface continuously until movement ends.
onTouchStart Invoked by the platform when the user touches the touch surface.
 
MethodsDescription
addGestureRecognizer Allows you to set a gesture recognizer for a specified gesture for a specified widget.
removeGestureRecognizerAllows 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.

 

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.
clipView Defines a shape to clip the widget view.
hoverSkin Specifies the look and feel of a widget when the cursor hovers on the widget.
linkFocusSkin Specifies the skin that must be applied to the link when focused.
linkSkin Specifies the skin that must be applied to the link in the RichText widget.
opacity Specifies the opacity of the widget.
shadowDepth Defines the depth of the shadow effect applied to the RichText Widget.
shadowType Sets a type of the shadow effect to apply to the RichText Widget.
skin Specifies the look and feel of the RichText when not in focus.
superScriptSkin Specifies the skin to be applied to superscripts in the RichText widget.
telephoneLinkSkin Specifies the skin to be applied to the telephone links in the RichText widget.
wrapping When the content of the RichText reaches the boundaries, it starts wrapping.

 

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

PropertiesDescription
cursorTypeSpecifies the type of the mouse pointer used.
 
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.

Configurations Common To All Widgets

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

 

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 RichText 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.
isVisibleControls the visibility of a widget on the form.
parentHelps you access the parent of the widget.

 

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

RichText Widget Basics

Use the Rich Text widget to display well formatted text using HTML formatting tags.

RichText widget is used to display non-editable and well formatted text on the Form. HTML formatting tags are used in RichText widget to display text with styles (bold, underlined etc.), links, and images.

You can use a RichText widget to show a read-only view of a well formatted text and to display text with different formatting styles.

For example, you can use the RichText widget in the "Contact Us" Form of an Application. You can use the widget's text styles (bold, italics etc.) to display the contact information, URL's telephone numbers instead of using multiple widgets like Label, Phone, and Link widgets on the Form.

Creating a RichText Using a Constructor: kony.ui.RichText

var RichText1 = new kony.ui.RichText(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



//The below function is the callback function for onClick event of RichText widget.
function onClickCalBck(richText) {
    //Write your logic here
}

//Defining properties for a RichText with onClick:onClickCalBck
var rTextBasic = {
    id: "rText",
    skin: "rTextSkin",
    linkSkin: "lnkSkin",
    text: "Sample text",
    isVisible: true,
    onClick: onClickCalBck
};

var rTextLayout = {
    containerWeight: 100,
    padding: [5, 5, 5, 5],
    margin: [5, 5, 5, 5],
    paddingInPixel: true,
    marginInPixel: true,
    hExpand: true,
    vExpand: false
};

var rTextPSP = {};

//Creating the RichText.
var rText = new kony.ui.RichText(rTextBasic, rTextLayout, rTextPSP);

Supported HTML formatting tags

The intended use of Rich Text is to display well formatted text using the following HTML formatting tags:

TagsDescription
<b>Text </b> Displays Text in Bold.
<i> Text </i>Displays Text in italics.
<u> Text </u>

Displays Text underlined.

<a href=""> </a>This tag is used to display a link. It supports optional href attribute.

NOTE: The skin attribute of the <a> tag, does not change the skin of the link inside the RichText widget. You must use the linkSkin Property to change the skin of the text given inside the <a> tag.

<img src="" > </img>

This tag is used to display an image and supports src attribute. The path for the image can be local or url based.

NOTE: Specify the absolute path of an image for MobileWeb platforms.

<sub>Subscript</sub> Displays text as Subscript.
<sup>Superscript</sup>

Displays text as Superscript.

<label style="color:#rgbhexformat"> </label>

Displays the text in the color specified. To display a red colored text, enter the following:

<label style="color:#FF0000">This is a red colored text</label>
<br/> Inserts a line break.
<tel number=""></tel>Displays a telephone number on Native Applications.
<a href="tel:"></a>Displays a telephone number on Mobile Web platforms.

NOTE: If you need to apply multiple formats on the same text, the tags given in the above table can be nested. For example: <b><i><u>BoldItalicandUnderlined</u></i></b>.

Customizing Appearance

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

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

Important Considerations

The RichText widget has the following considerations:

  • All Platforms: If you specify a skin for the RichText widget, all the font level settings (color style, or size etc.) is applied to the complete content in RichText widget. You can use the label style HTML formatting tag to override the text color specified at the skin level.
  • iPhone: <img> HTML formatting tag is not supported. While integrating custom fonts, the name of the font file should match its PostScript name. You have to determine the PostScript name using some tool (in Mac you can install the font to find the PostScript name) and make sure that you name the font file as the <postscriptname>.ttf. For example, if the PostScript font file name is "DBOzoneX-BoldItalic", then the font name during integration should be "DBOzoneX-BoldItalic.ttf". OpenType fonts (OTF) are also supported.