Label Widget Documentation

Last modified by Microchip on 2024/06/21 11:38
Contents

Introduction

A Label Widget is a graphical user interface component used to display text on the screen.

It's a simple and efficient way to present non-interactive information to the user. The text within a label can be static or dynamic, and the widget supports various text rendering options, including different fonts, sizes, and colors. It's also possible to align the text within the label in different ways (left, right, center).

This Label Widget document covers the following topics:

  1. Creating and customizing Label Widgets using Microchip Graphic Suite (MGS) Harmony Composer.
  2. Label Widget properties.
  3. Handling Label Widget properties through application code.
  4. Label Widget example project.
  5. Application Program Interfaces (APIs) specific to Label Widgets.

Before following this document, ensure that you are familiar with the process of designing with MGS Harmony Composer, generating code with MPLAB® Code Configurator (MCC), and debugging with MPLAB X IDE. To learn more about this, refer to the "Getting Started with Microchip Graphics Suite (MGS) Harmony" page.

Designing Label Widget Using MGS Harmony Composer

To add a Label Widget to your design, follow the steps given below:

Select and drag the Label from the Tool Box to your screen designer workspace as shown in the accompanying image.

Drag "Label" widget from Tool Box to your screen

To customize the label, select it on the screen designer or from the Screen Tree view and modify its properties using the Object Editor.

Select Label Widget and modify it's properties

Set the label string by pressing the String button from Object Editor.

Set label string from Object Editor

To learn how to import strings for your label widget, please refer to the "Microchip Graphics Suite (MGS) Harmony Graphics Assets Guide" page.

Back to Top

Managing Label Widget Schemes

Schemes control the look and feel of a widget.

To learn more about Schemes and how to add a new scheme and apply it to the widget, refer to the "About the Schemes and Scheme Editor" page.

To learn how to set the scheme for a label, click on the Question mark  button next to the scheme property editor of the Object Editor:

Press the question mark to see detailed information about the effect of schemes on label widget

This launches the Label Scheme Helper window containing tips on how different sections of the scheme color table manipulate various elements of the label.

Label scheme helper

The accompanying image is an example color scheme and the resulting appearance of the Label Widget.

Label Widget example color scheme

Back to Top

Label Widget Properties

You can set the following properties of the Label Widget using the Object Editor.

StringWill add a String asset to the label. The effects of the settings are previewed within the MGS Harmony Composer.

Widget properties specific to Label Widget were discussed. For the properties common to all widgets, refer to the "Base Widget Documentation" page.

Back to Top

Managing Label Widget through Programming

Once the graphical design is completed using MGS Harmony Composer, MCC generates the required code for all the widgets based on the properties set in the Object Editor. To learn more about the process flow between designing a UI and developing application code, refer to the "Designing an Application with Microchip Graphics Suite (MGS)" page.

Let us suppose that a label widget is created with the following properties in MGS Harmony Composer.

Label widget properties

For the label widget with the properties shown in the accompanying figure, MCC will automatically generate the following lines of code in  src\config\default\gfx\legato\generated\screen\le_gen_screen_Screen0.c:

  • A new label widget is created by the variable name Screen0_LabelWidget_0:

Screen0_LabelWidget_1 = leLabelWidget_New();

  • Its position is set to pixel location 550x130:

Screen0_LabelWidget_1->fn->setPosition(Screen0_LabelWidget_0, 474, 200);

  • Its size is set to 225x85:

Screen0_LabelWidget_1->fn->setSize(Screen0_LabelWidget_1, 225, 85);

  • The alpha blending property is enabled:

Screen0_LabelWidget_1->fn->setAlphaEnabled(Screen0_LabelWidget_1, LE_TRUE);

  • And the alpha amount will be set to 250:

Screen0_LabelWidget_1->fn->setAlphaAmount(Screen0_LabelWidget_1, 250);

  • The label is set to have beveled border in this example.

Screen0_LabelWidget_1->fn->setBorderType(Screen0_LabelWidget_0, LE_WIDGET_BORDER_BEVEL);

  • The height aligment is set to center:

Screen0_LabelWidget_1->fn->setHAlignment(Screen0_LabelWidget_1, LE_HALIGN_CENTER);

  • If you set a string value to the label in the  MGS Harmony Composer Object editor, then the code below is added, else, it is skipped:

Screen0_LabelWidget_1->fn->setString(Screen0_LabelWidget_1, (leString*)&string_AlphaBlending);

  • Finally, the label is added to the screen:

root0->fn->addChild(root0, (leWidget*)Screen0_LabelWidget_1);

Back to Top

Label Widget Example Project

An example project for a Label Widget is provided.

In this example, we show:

  1. How to create a Label Widget. 
  2. How to change its properties (scheme, string, and alpha amount) through programming.

Back to Top

MGS Harmony Web Simulator Output

Label Widget Example

In the example application, a system timer service callback will change a flag that will mark the Label Widget scheme and also a variable that will be later used to change Label Widget alpha blending.

As a best practice, changes to the widget are done in the main loop based on the variables that are changed in the timer callback, not in the callback directly.

The system timer callback and the code that changes the Label Widget can be found in the app.c file.

  •   System timer callback:
void Timer_Callback ( uintptr_t context )
{
   if (label_state == SET_WHITE_SCHEME)
        label_state = SET_NO_SCHEME;
   else
        label_state = SET_WHITE_SCHEME;

    alpha_value -= 20;
   if (alpha_value < 30)
        alpha_value = 255;

    appData.state = APP_STATE_SERVICE_TASKS;
}
  • Modifying the Label Widget scheme and text in the main loop.
switch (label_state)
{
   case SET_WHITE_SCHEME:
    {
        Screen0_LabelWidget_0->fn->setString(Screen0_LabelWidget_0, (leString*)&string_White_scheme);
        Screen0_LabelWidget_0->fn->setScheme(Screen0_LabelWidget_0, &WhiteScheme);
       break;
    }
   case SET_NO_SCHEME:
    {
        Screen0_LabelWidget_0->fn->setString(Screen0_LabelWidget_0, (leString*)&string_No_scheme);
        Screen0_LabelWidget_0->fn->setScheme(Screen0_LabelWidget_0, NULL);
       break;
    }
   default:
       break;
}
  • Changing the alpha blending property.
Screen0_LabelWidget_1->fn->setAlphaAmount(Screen0_LabelWidget_1, alpha_value);

Back to Top

Label Widget APIs Description

This section describes the APIs specific to the Label Widget. For a description of APIs common to all widgets, refer to the "Base Widget Documentation" page.

setString()

leResult setString(leLabelWidget* _this, const leString* str)

Sets the string associated with the label.

Parameters

leLabelWidget*_thisLabel widget pointer to operate on
const leString*strPointer to the string that should be shown on the label widget 

Returns LE_SUCCESS or LE_FAILURE.

getString()

leString* getString(const leLabelWidget* _this)

Gets string assigned to the label widget.

Returns string pointer.

Learn More

For more advanced topics that are related to the Label Widget, refer to the following pages:

Back to Top