Skip to Content

Progress Bar Widget Documentation

Last modified by Microchip on 2025/09/12 10:02

Introduction

The Progress Bar widget in Microchip Graphics Composer (MGC) is highly customizable, allowing developers to tailor its appearance and behavior to fit the specific needs of their applications. With intuitive drag-and-drop functionality and a wide range of configuration options, the progress bar enhances user experience by updating the progress value and integrate event callbacks for interactive feedback.

This Progress Bar widget document covers the following topics:

  1. Creating and customizing Progress Bar widgets using Microchip Graphics Suite (MGS) Harmony Composer
  2. Progress Bar properties
  3. Handling Progress Bar widget properties and events through application code
  4. Progress Bar widget example project
  5. Application Program Interfaces (APIs) specific to the Progress Bar widget

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, refer to the "Getting Started with Microchip Graphics Suite (MGS) Harmony" page.

Designing Progress Bar Widget Using MGS Harmony Composer

To add the Progress Bar widget to your design, follow the steps given below:

In the Graphics Composer, select and drag the Progress Bar from the Toolbox to your screen designer workspace as shown in the accompanying image:

Drag "Progress Bar" widget from Tool Box to your screen

Figure 1: Progress Bar from Toolbox

Back to Top

To customize the Progress Bar, select it from the Screen Tree and modify its properties using the Object Editor.

To set the Border aspect property of the progress bar, click on the button beside it and from the Border window choose the desired aspect as shown in the accompanying image:

Border Aspect

Figure 2: Border Aspect

Setting the progress bar initial value can be done by adding any numerical value, from 0 to 100, in the Value section as in Figure 3. (The example from Step 2.1 presents a progress bar with a value of 0.)

Progress Bar Value

Figure 3: Progress Bar Value

The progress bar filling direction can be set from the Fill Direction section. (The previous example, Step 2.2, shows the Fill Direction as Right.)

Fill Direction

Figure 4: Fill Direction

To set an event handler function when the Progress Bar widget value is changed, select the corresponding checkbox under Events as shown in the following image:

Value Changed Event

Figure 5: Value Changed Event

The rest of the checkboxes can be set using the Object Editor depending on your needs. An example is shown in the accompanying image:

Object Editor

Figure 6: Object Editor

Back to Top

Managing Progress Bar Widget Schemes

Schemes control the look and feel of a widget.

To learn more about Schemes, 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 the progress bar, click on the question mark (?) button next to the Scheme Property editor of the Object Editor.

Scheme helper button

Figure 7: Scheme Helper Button

This launches the Progress Bar Scheme Helper window containing tips on how different sections of the scheme color table manipulate various elements of the widget:

Progress Bar Scheme Helper Window

Figure 8: Progress Bar Scheme Helper Window

Figuure 9 shows an example color scheme and the resulting appearance of the Progress Bar:

Color Scheme Example

Figure 9: Color Scheme Example

The information about the Progress Bar scheme adjustments and the example color scheme are summarized in Figure 10:

Color Scheme Table

Figure 10: Color Scheme Table

Note: Understanding how the various segments of the color table influence the appearance of the list assists you in selecting the appropriate colors.

Back to Top

Progress Bar Properties

You can set the following properties of the Progress Bar using the Object Editor:

NameThis will be used to reference the progress bar by the application. Example - Screen0_ProgressBarWidget_0.
Fill DirectionSet the progress bar filling direction, as in Section 2.3.
ValueSets a value for the progress bar as shown in Section 2.2.
Value ChangedThis will set the event that is generated when the progress bar value is changed.
Table 1: Progress Bar Widget Properties

Note: Widget properties specific to Progress Bar widget were discussed. For the properties common to all widgets, refer to the "Base Widget Documentation" page.

Back to Top

Managing Progress Bar through Programming

Once you complete creating your graphical interface with MGS Harmony Composer, the MPLAB® Code Configurator (MCC) automatically produces the necessary code for each widget according to the settings specified in the Object Editor. For additional details on the workflow from UI design to application code development, consult the "Designing an Application with Microchip Graphics Suite (MGS)" page.

Let's suppose that a new Progress Bar widget is created with the following properties in MGS Harmony Composer:

Progress Bar Example

Figure 11: Example

For the Progress Bar widget with the properties shown in the figure above, MCC will automatically generate the following lines of code in   

src\confg\default\gfx\legato\generated\screen\le_gen_screen_Screen0.c

  • A new Progress Bar widget is created by the variable name Screen0_ProgressBarWidget_0:
    Screen0_ ProgressBarWidget _0 = leProgressBarWidget _New();
  • Its position is set to pixel location 100x45:
    Screen0_ProgressBarWidget_0->fn->setPosition(Screen0_ProgressBarWidget_0, 100, 45);
  • The Progress Bar size is set to have a width of 600 pixels and a height of 130:
    Screen0_ProgressBarWidget_0->fn->setSize(Screen0_ProgressBarWidget_0, 600, 130);
  • Its background and filling color is set based on the selected color scheme:
    Screen0_ProgressBarWidget_0->fn->setScheme(Screen0_ProgressBarWidget_0, &ProgressBarScheme);
  • The Progress Bar filling value is set at 50%, by using a numerical character:
    Screen0_ProgressBarWidget_0->fn->setValue(Screen0_ProgressBarWidget_0, 50);
  • The setValueChangedCallback API adds callback function when the Progress Bar value is changed. These callback functions are implemented in the application code:
    Screen0_ProgressBarWidget_0->fn->setValueChangedCallback(Screen0_ProgressBarWidget_0, event_Screen0_ProgressBarWidget_0_ValueChanged);
  • Finally, the progress bar is added to the screen:
    root0->fn->addChild(root0, (leWidget*)Screen0_ProgressBarWidget_0);

Back to Top

Application Code

The default code generated by MCC establishes the initial state of the widget. You can modify the properties or behavior of the widgets using the APIs mentioned earlier in the application code. Further discussion on application code related to the Progress Bar widget is provided below.

Here is an example of activating the event when the Progress Bar value is changed, modifying the size of the Progress Bar widget and setting the filling direction:

Screen0_ProgressBarWidget_0->fn>setPosition(Screen0_ProgressBarWidget_0, 0, 0);

Screen0_ProgressBarWidget_0->fn->setSize(Screen0_ProgressBarWidget_0, 200, 200);

Screen0_ProgressBarWidget_0->fn->setDirection(Screen0_ProgressBarWidget_0, LE_PROGRESSBAR_DIRECTION_DOWN);

Screen0_ProgressBarWidget_0->fn->setValueChangedCallback(Screen0_ProgressBarWidget_0, event_Screen0_ProgressBarWidget_0_ValueChanged);

Back to Top

Progress Bar Widget Example Project

An example project for the Progress Bar widget is provided.

In this example, we show:

  1. How to create a Progress Bar widget, which gets filled depending on a Slider widget
  2. How to show the value of the progress bar, using its event

Back to Top

MGS Simulator Output

Progress Bar Example

Adjusting the slider widget triggers its associated event handler within the application code, allowing the user to modify the progress bar’s value according to the slider’s current position. When the progress bar value is updated, its event handler is subsequently invoked, which then updates the label to display the corresponding percentage of completion.

  • The Slider Event Callback gets invoked when the slider's position is moved and it takes the position of the slider, transforming it into the value:
void event_Screen0_SliderWidget_0_OnValueChanged(leSliderWidget* scr)
{
   /*Get the value of the slider*/
    sliderValue = Screen0_SliderWidget_0->fn->getValue(Screen0_SliderWidget_0);
    sliderChanged = true;
}
  • The screen's function, called "Screen0_On_Update", which gets called repeatedly in the application code, checks the value of the bool variable set in the function above and if it's true, the value of the Progress Bar widget is set using its API:
void Screen0_OnUpdate(void)
{
   /*Update the value of the Progress Bar Widget when the event of the Slider is entered*/
   if(sliderChanged == true)
    {
        Screen0_ProgressBarWidget_0->fn->setValue(Screen0_ProgressBarWidget_0, sliderValue);
        sliderChanged = false;
    }        
}
  • The Progress Bar Event Callback gets called every time the progress bar's value gets changed and updates a string value, which is placed in a label:
void event_Screen0_ProgressBarWidget_0_ValueChanged(leProgressBarWidget* wgt, uint32_t val)
{
   /*Update the string value shown on the widget when the Progress Bar value changes*/
   char valueCStr[VALUE_STR_SIZE_8] = {0};
   
    snprintf(valueCStr, VALUE_STR_SIZE_8, "%u", sliderValue);
       
    sliderStr.fn->setFromCStr(&sliderStr, valueCStr);
    Screen0_LabelWidget_1->fn->setString(Screen0_LabelWidget_1, (leString *) &sliderStr);
}

Back to Top

Progress Bar Widget APIs Description

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

getDirection()

The following gets the progress bar filling direction: leProgressBarDirection getDirection(const leProgressBarWidget* _this).

Parameters

const leProgressBarWidget*_this

Progress Bar widget pointer to operate on

This returns the filling direction.

setDirection()

The following sets the progress bar filling direction: leResult setDirection(leProgressBarWidget* _this, leProgressBarDirection dir).

Parameters

leProgressBarWidget*_thisProgress Bar widget pointer to operate on
leProgressBarDirectiondirFilling Direction (LE_PROGRESSBAR_DIRECTION_RIGHT,
                           LE_PROGRESSBAR_DIRECTION_UP,
                           LE_PROGRESSBAR_DIRECTION_LEFT,
                           LE_PROGRESSBAR_DIRECTION_DOWN).

This returns LE_SUCCESS or LE_FAILURE.

getValue()

The following gets the progress bar valueuint32_t getValue(const leProgressBarWidget* _this).

Parameters

const leProgressBarWidget*_thisProgress Bar widget pointer to operate on

This returns the progress bar value.

setValue()

The following gets the progress bar value: leResult setValue(leProgressBarWidget* _this, uint32_t value).

Parameters

leProgressBarWidget*_thisProgress Bar widget pointer to operate on
uint32_tvalueProgress Bar value

This returns LE_SUCCESS or LE_FAILURE.

getValueChangedEventCallback()

The following gets value changed event callback pointer: leProgressBar_ValueChangedEventCallback getValueChangedEventCallback(const leProgressBar* _this).

Parameters

leProgressBar*_thisProgress Bar widget pointer to operate on

This returns the callback pointer.

setValueChangedCallback()

The following sets value changed event callback pointer: leResult setValueChangedCallback(leProgressBar* _this, leProgressBar_ValueChangedEventCallback cb).

Parameters

leProgressBar*_thisProgress Bar widget pointer to operate on
leProgressBar_ValueChangedEventCallbackcbThe callback pointer

This returns LE_SUCCESS or LE_FAILURE.

Back to Top