Open topic with navigation

You are here: Creating a Label Using a Constructor: kony.ui.Label

Label Widget

The Label widget is used to display static text on a form. It can be used as a form label or an area header with various text alignments and styles.

Following are the key concepts of Label widget:

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

For general information on the Label widget see the Label topic in the Kony Visualizer User Guide.

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

The Label 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.
 
PropertiesDescription
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.
leftDetermines 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.
paddingInPixelIndicates if the padding is to be applied in pixels or in percentage.
topDetermines 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

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.
 

Data Management

MethodsDescription
cloneWhen this method is used on a container widget, then all the widgets inside the container are cloned.
 
PropertiesDescription
breakStrategySpecifies the method to perform line breaks on paragraphs of Label text.
fontMetrics Enables apps to obtain information about the metrics of a Label widget's text.
hyphenationFrequencySets the periodicity in which words break in a text in Label widget.
pasteboardType Enables an application to share data within the application or with another application using system-wide or application-specific pasteboards.
text Specifies a general or descriptive text for a Label widget.
textCopyable Enables you to copy a text from a Label widget when the widget is enabled state.
textStyle Enables apps to get and set values that control the appearance of the Label widget's text.
textTruncatePosition Enables the appearance of ellipses at a particular position (start, middle, and end of the line) if the text gets truncated due to the maxNumberOfLines property.
toolTip Specifies the hint text when the cursor hovers over a widget, without clicking it.
wrapping When the content of the label reaches the boundaries, it starts wrapping.
 

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.
 

User Input Handling

EventsDescription
onScrollWidgetPosition This event callback is invoked by the platform when the widget location position gets changed on scrolling.
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.
 
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.
 

UI Appearance

PropertiesDescription
backgroundColor Specifies the background color of the widget in hex format.
blurYou can enable or disable a blur-effect for a widget
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.
opacity Specifies the opacity of the widget.
renderAsAnchor Most of the Mobile Web browsers do not offer a very good user experience when the entire segment is made clickable.
shadowDepth Defines the depth of the shadow effect applied to the Label Widget.
shadowType Sets a type of the shadow effect to apply to the Label Widget.
 

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.
maxNumberOfLines Defines the maximum number of lines of text allowed in a Label Widget.
newUnderlineBehaviourUnderlines the text in Label widget for iOS platform.
 
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

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.
removeFromParentAllows 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 Sets the visibility of the widget.
 
PropertiesDescription
accessibilityConfig Enables you to control accessibility behavior and alternative text for the widget.
enableCache Enables you to improve the performance of Positional Dimension Animations.
idid is a unique identifier of Image 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.
 

Label Widget Basics

When do I use a Label Widget?

You can use a Label widget in the following scenarios:

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

var lbl1 = new kony.ui.Label(basicConf, layoutConf, pspConf);

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

Example

//Defining the properties for a label with id:"label"
var lblBasic = {
    id: "label",
    skin: "lblSkn",
    text: "Hello world",
    isVisible: true
};
var lblLayout = {
    containerWeight: 100,
    padding: [5, 5, 5, 5],
    margin: [5, 5, 5, 5],
    hExpand: true,
    vExpand: false
};
var lblLayout = {
    renderAsAnchor: true,
    wrapping: constants.WIDGET_TEXT_WORD_WRAP
};
//Creating the label.
var lbl = new kony.ui.Label(lblBasic, lblLayout, lblLayout);

//Reading the id of the label.
alert("Label id::" + lbl.id);

Customizing a Label's Appearance

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

Changing the Text Size through the Larger Text option in iOS

You can now change the text size of Label 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

Platform Availability

Limitations

Font Metrics and Text Style

To gain finer control over the appearance of the text in a Label widget, your app can use the fontMetrics and textStyle properties. Both the fontMetrics and textStyle properties contain JavaScript objects that hold the font information.

A font's metrics and text style as defined for Android and iOS as shown in the following diagrams.

Android:

iOS:

The fontMetrics property is contains an object that encapsulates about how to render a particular font. Specifically, it controls the following properties of the Label's text.

PropertyPlatform Availability

top

Android
bottomAndroid
ascentAndroid, iOS
descentAndroid, iOS
leadingAndroid, iOS
pointSizeiOS
capHeightiOS
xHeightiOS
lineHeightAndroid, iOS

The fontMetrics property is read-only. The following example shows how an app can read the fontMetrics property.

var fontMatricesObject = form.label.fontMetrics;
kony.print ("ascent :" + fontMatricesObject.ascent);
kony.print ("descent:" + fontMatricesObject.descent);

The textStyle property enables your app to set or get the following text properties of a Label widget. It contains a JavaScript object of key/value pairs. The keys are shown in the following table.

PropertyPlatform Availability

lineSpacing

Android, iOS
letterSpacingAndroid, iOS
strikeThroughAndroid, iOS
strikeThroughStyle iOS
baseLine iOS
minLineHeight iOS
maxLineHeight iOS

The textStyle property is read/write. The following code provides an example of how an app might use the textStyle property.

//Writing values to the textStyle property.
form.label.textStyle = {
    "lineSpacing": 10,
    "letterSpacing": 10,
    "strikeThrough": true,
    "strikeThroughStyle": constants.TEXTSTYLE_STRIKETHROUGH_STYLE_THICK,
    "baseline": 0.5
};
//Reading values from the textStyle property.
var textStyleInfo = form.label.textStyle;

Important Considerations

Label has the following considerations:

premCopyright © 2012 Kony, Inc. All rights reserved.
premCopyright © 2012 Kony, Inc. All rights reserved.

Open topic with navigation