You are here: Creating a Label Using a Constructor: voltmx.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:

• Naming widgets: Label widget is used to provide static names to other widgets. For instance, consider a login form that has Employee details as the title of the form.

• Providing Information: Label widget is used to provide static data. For instance, consider the following employee details form providing employee details such as Employee ID, Name, and Designation.

• Tool Tip: Using Label widget, you can display a message on hovering the mouse pointer over a widget. It is very helpful for a new user to know more about various functionalities.

• Text Copyable: Label widget enables you to copy a text and paste it elsewhere.

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 Label widget see the Label topic in the Volt MX Iris 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
• Animations
• Data Management
• User Input Handling
• 3D Touch
• UI Appearance
• Enabling RTL
• Miscellaneous
• Configurations Common To All Widgets

Layout

Animations

Data Management

3D Touch

User Input Handling

UI Appearance

Enabling RTL

Miscellaneous

Configurations Common To All Widgets

Label Widget Basics

When do I use a Label Widget?

You can use a Label widget in the following scenarios:

• To identify or name a neighboring widget.
• To provide instructions to the user on the usage of a feature or a widget. For example, if you want to inform a user to select one of the options from a CheckBoxGroup, you can place a Label before the CheckBoxGroup widget with the text “Choose one of the following”.

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

var lbl1 = new voltmx.ui.Label(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 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 voltmx.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:

• contentAlignment: Specifies the alignment of the content within widget boundaries.
• 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.
• fontMetrics. Controls the label’s characteristics that govern the Label’s appearance such as the top, bottom, ascent, descent, and point size of the text.
• textStyle. Defines properties such as the line spacing, letter spacing, strikethrough, base line, and line height of a Label’s text.

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 voltmx.application.setApplicationBehaviors function as follows:

voltmx.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 Label 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.

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.

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

var fontMatricesObject = form.label.fontMetrics;  
voltmx.print ("ascent :" + fontMatricesObject.ascent);  
voltmx.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.

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:

• If the text in the Label is occupying more space than the allocated height of the Label widget, the Label is stretched vertically to accommodate the full text (infinite wrapping) and does not stretch in the horizontal direction.
• If you place a Label in the Form and do not enter a text, when rendered, the height and width occupied by the Label depends on the following:
  • If the Expand property is false, the Label occupies zero height and width.
  • If the Expand property is true, the Label occupies the width and height as determined by the Expand property.