Skip to Content

Panel Widget Documentation

Last modified by Microchip on 2024/10/30 14:38

Introduction

Panel widgets are background elements for the Graphical User Interface (GUI) that enable the users to make the GUI attractive by changing the background color and transparency.

This Panel Widget document covers the following topics:

  • Creating and customizing panel widgets using Microchip Graphics Suite (MGS) Harmony Composer
  • Panel widget properties
  • Managing panel widget with the help of a button through programming
  • Panel widget example project
  • APIs specific to panel 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 Panel Widgets using MGS Harmony Composer

To add a panel widget to your design, select and drag PanelWidget from the Tool Box to your screen designer workspace.

Select Panel Widget

Figure 1: Select Panel Widget

Next, select the widget from the Screen Tree and modify its properties using the Object Editor. This will customize the panel widget.

Showing the Object Editor

Figure 2: Showing the Object Editor

Back to Top

Managing Panel Widget Schemes

Schemes control the look and feel of a widget.

Note: To learn more about Schemes, like 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 panel, click on the ? button next to the Scheme property editor of the Object Editor. 

Scheme Button from Object Editor

Figure 3: Scheme Button from Object Editor

This launches the Panel Scheme Helper window, which contains tips on how different sections of the scheme color table manipulate various widget elements.

Panel Widget Scheme Helper

 Figure 4: Panel Widget Scheme Helper

The following is an example of the color scheme and the resulting panel appearance.

Scheme settings for panel widget

Figure 5: Scheme Settings for Panel Widget

The information from the Panel Scheme Helper and the example color scheme is summarized in the following table.

Description of Scheme Helper

Figure 6: Description of Scheme Helper

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

Back to Top

Panel Properties

You can set the following properties of the Panel using the Object Editor:

  Name        This will be used to reference the panel by the application. Example-

                    Screen0_PanelWidget_0

Note: Refer to the “Base Widget Documentation” page for other common properties.

Managing Panel 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

Suppose a new panel widget is created with the following properties in MGS Harmony Composer.

Panel Widget Object Editor

Figure 7: Panel Widget Object Editor

For the Panel 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 Panel widget is created by the variable name Screen0_PanelWidget_0

Screen0_PanelWidget_0 = leWidget_New();

  • Its position is set to pixel location 256x23.

Screen0_PanelWidget_0->fn->setPosition(Screen0_PanelWidget_0, 256, 23);

  • The Panel size is set to have a width of 140 and a height of 103.

Screen0_PanelWidget_0->fn->setSize(Screen0_PanelWidget_0, 140, 103);

  • Its background value is set to fill which gives it its gray color. The background can be set to blank.

Screen0_PanelWidget_0->fn->setBackgroundType(Screen0_PanelWidget_0, LE_WIDGET_BACKGROUND_FILL);

  • The Panel is set to have a bevel border in this example. However, you can have a line border or no border.

Screen0_PanelWidget_0->fn->setBorderType(Screen0_PanelWidget_0, LE_WIDGET_BORDER_BEVEL);

  • Finally, the Panel Widget is added to the screen.

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

Back to Top

Panel Widget Example Project

Refer to the Panel Widget Example Project on GitHub

In this example, we show:

  • How to create panels
  • How to handle the panel scheme with buttons

MGS Harmony Web Simulator Output

Panel Widget Example

This example shows the pressed and released callback functions of the panel color button that can be added to the application code to change the Scheme of the Panel Widget. See app.c in Github.

/* When the Panel color button is in pressed state, the Screen0_PanelWidget_0 panel

*widget will change the scheme to green and Screen0_PanelWidget_1 change the scheme to Blue*/

void void event_Screen0_ButtonWidget_0_OnPressed(leButtonWidget* btn){

    Screen0_PanelWidget_0->fn->setScheme(Screen0_PanelWidget_0, &GreenScheme);

    Screen0_PanelWidget_1->fn->setScheme(Screen0_PanelWidget_1, &BlueScheme);

}

/* When the Panel color button is in Released state, the Screen0_PanelWidget_0 panel

*widget will change the scheme back to yellow and Screen0_PanelWidget_1 change the scheme back to Orange*/

void void event_Screen0_ButtonWidget_0_OnReleased(leButtonWidget* btn){

    Screen0_PanelWidget_0->fn->setScheme(Screen0_PanelWidget_0, &YellowScheme);

    Screen0_PanelWidget_1->fn->setScheme(Screen0_PanelWidget_1, &OrangeScheme);

}

Back to Top

Panel Widget APIs Description

For the description of Panel widget APIs, refer to the “Widget API Description” section.

Back to Top