Microchip Graphics Suite (MGS) Harmony Composer User Guide

Last modified by Microchip on 2025/02/19 16:05

Introduction

The Microchip Graphics Suite (MGS) Harmony Composer is a graphical user interface design tool.

The MGS Harmony Composer is integrated as part of MPLAB^® Code Configurator (MCC). Tightly coupled with the MGS Harmony library, this tool enables you to easily design and configure user interfaces for MGS applications. If the GUI design is available in Figma - a collaborative design tool, you can easily import it into the MGS Harmony Composer, significantly reducing the time it takes to develop the application. This document covers the following topics:

The layout of the MGS Harmony Composer
How to launch the Composer
How to design a graphics user interface with the Composer and generate design files
How to import a Figma design into a Composer project

For a complete guide that describes how to create a graphics application with MPLAB X IDE, MCC and MGS Harmony Composer, refer to the "Getting Started with a New Harmony Graphics Application" Microchip University course.

Overview of the User Interface

MGS Harmony Composer includes everything you need to create a UI design. It provides a gallery of widgets and containers. It supports multiple screens and layers. It provides property editors with color schemes and objects. It is capable of creating designs that run on all Microchip hardware and a wide range of display resolutions.

Referencing Figure 1, take a few moments to familiarize yourself with the main sections of the MGS Harmony Composer workspace. You will find Figure 1 labeled with numbers and their corresponding description below:

Microchip Graphics Composer window — Figure 1: Microchip Graphics Suite Composer Main Window

Main menu bar: At the top of the workspace are user menus that you can use to perform project tasks and configure your work environment. The main menu bar contains menus that you can use to perform these tasks:

File	Open, Save, Import projects, and Generate design files
Edit	Undo/Redo, Cut/Copy/Paste, set user preference to auto-save design while generating design files for MCC
View	Set object clipping (if clipping is turned on, objects are clipped to the rectangles of their parents when they are rendered) and display language preferences
Project	Set project properties, launch event manager, memory tools
Asset	Add assets for images, fonts, strings, and palette
Window	Manage user interface windows

Screen Tree/ Screen Manager Editor: Allows users to edit the Screen Tree or Screen Manager, depending on the tab selected at the bottom of this pane (Refer #3 -Screen Tree/ Screen Manager Tab).

Screen Tree Editor: The Screen Tree editor maintains a tree of layers including widgets in each layer. It contains the following buttons:

	Creates a New layer
	Activates the selected layer so that when you drag a widget to the design area, it gets placed in this layer
	Deletes the selected layer
	Moves the selected widget up the tree
	Moves the selected widget to the top of the layer
	Moves the selected widget down the tree
	Moves the selected widget to the bottom of the layer

Screen Manager Editor: The Screen Manager editor allows users to add or delete screens. A default screen (screen shown at startup) can be set. It contains the following buttons:

	Adds a new screen
	Deletes the selected screen
	Deletes all the screens
	Duplicates a screen
	Activates the selected screen and displays the screen design

If the Visible checkbox is selected, the screen is made visible in the design. If there are more than one screen, the Startup checkbox can be used to choose which screen will be displayed at the start of the application. Refer Figure 2 below.

Screen Manager editor — Figure 2: Screen Manager showing visibility and initial screen setting

Screen Tree/ Screen Manager Tab: These tabs display the Screen Tree or the Screen Manager for the user to edit. (Refer #2 -Screen Tree/ Screen Manager Editor).
Tool Box Pane: It contains a gallery of containers, input, and display widgets. These are used to design the user interfaces. You can drag containers and objects from the toolbox to the Screen Designer area (Refer #5 -Screen Designer).
Screen Designer: The middle of the workspace is the screen designer. It contains one or more screens that you create and design in MGS Harmony Composer. You can adjust the zoom level of the design by holding the Ctrl key while scrolling with your mouse.
Console: The console displays actions performed by the MGS Harmony Composer such as Opening of a project, saving, output generation etc.

Object / Schemes Editor: Allows users to edit the properties of the selected object on the screen tree, add/delete schemes or edit the scheme properties, depending on the tab selected at the bottom of this pane (Refer #8 -Object Editor/ Schemes/ Schemes Editor Tab).

Object Editor: If the Object Editor tab is selected, the properties of the selected object from the Screen tree is displayed for the user to edit. Refer Figure 3 below.

To learn how to use the object editor to edit the different widgets, refer to the widget tutorial.

Schemes: If the Schemes tab is selected, the list of schemes in the project is displayed. Users can add/ delete schemes using the editor. Refer Figure 4 below.

Schemes Manager — Figure 4: Schemes tab selected displaying the list of schemes in the project

The following scheme related icons are provided (Refer Figure 4):

	Adds a new
	Deletes the selected scheme
	Deletes all the schemes
	Brings up the scheme editor to edit the selected scheme
	Precomputes alpha blending of selected colors into a lookup table for enhanced performance
	Resets the scheme to default values
	Sets the selected scheme as the default scheme so that newly created widgets are assigned this scheme

For more information about Schemes - how to create a new scheme and apply custom scheme to widgets, refer to the Schemes tutorial. For information on how to apply custom schemes to widgets, refer to the widget tutorial.

Schemes Editor: If the Schemes Editor tab is selected, the properties of the selected scheme from the Schemes tab is displayed for the user to edit. Refer Figure 5 below.

To learn how to use the scheme editor to edit the scheme, refer to the "About the Schemes and Scheme Editor" page.

Object Editor/ Schemes/ Schemes Editor Tab: These tabs display the Object Properties, Schemes List or Scheme Properties for the use to edit. (Refer #7 - Object / Schemes Editor).
Generate Code: Once the design of all the screens is complete, the generate code button can be used to create a zip file of the project. The location of the zip file can be specified while saving the MGS Harmony Composer project. The best practice is to save the project in the MCC project config folder. Refer "Saving Project" section.

Overview of the Workflow

In this section, we show you how to use MGS Harmony Composer to design graphics applications.

This tutorial assumes you know:

How to create an MCC application using MPLAB X IDE for your target
How to download MPLAB Harmony 3 software from the microchip GitHub repository using the content manager
How to create MCC project graph, generate code, and debug the application to your target.

For help with these topics, refer to the links provided at the bottom of the tutorial.

MGS Harmony Composer is included in the gfx package that is part of the MPLAB Harmony 3 framework. The gfx package is stored and maintained in the gfx GitHub repository.

The gfx package can be downloaded using the MCC Harmony Content Manager with the rest of the MPLAB Harmony 3 packages.

Launching MGS Harmony Composer

MGS Harmony Composer is available for Windows®, Linux®, and macOS®. It can be launched from MPLAB X IDE using the MCC plugin. It can also be launched stand-alone.

From MPLAB X IDE

MGS Harmony Composer can be launched from MPLAB X IDE using the MCC plugin as shown in Figure 6.

Lcomposer — Figure 6: Launching MGS Harmony Composer from MPLABX IDE

The MGS Harmony plugin is available in the drop-down list only if Legato™ Graphics Library is available in the project graph.

Legato Graphics Library pane — Figure 7: Legato graphics library included in the project graph

If the design for the project is already available then it is automatically opened in Microchip Graphics Composer, otherwise, you will be prompted to either create a new project using a wizard or open an existing project as shown in Figure 8.

For the design to be automatically opened in Microchip Graphics Composer from the MCC plugin, it is required that the design file is saved as <projectConfiguration>_design.zip. For example, if the project configuration is lcdc_rgba8888_mxt_a5d27_som1_ek1_wvga, the Microchip Graphics Composer design file should be saved as lcdc_rgba8888_mxt_a5d27_som1_ek1_wvga_design.zip. In addition, the design file must be saved in the project src/config folder. For example, legato_quickstart/firmware/src/config/lcdc_rgba8888_mxt_a5d27_som1_ek1_wvga folder.

In the next section, we show you how to create a design from scratch using the wizard.

Stand-alone

For Windows, MGS Harmony Composer can be launched as a stand-alone by double-clicking composer.exe in the gfx\middleware\legato\composer\windows folder.

The Composer for Linux can be found in the gfx/middleware/legato/composer/linux directory, while the version for macOS is located in the gfx/middleware/legato/composer/macos folder.

Using MGS Harmony Composer New Project Wizard

From Figure 8, we can see that when the Composer is launched, we are able to either load an existing design or create a new one using the wizard. In this section, we will learn how to create a new design using the wizard.

The Create a new project New Project Button button launches the New project wizard as shown in Figure 9. Now follow the steps below.

For a blank project, choose the Clean Design template. If you would like a Quickstart template with some basic assets and widgets for a display with one of the resolutions shown in Figure 9, choose the desired template and proceed to step 3.

If your display resolution is available in the drop down list for Display Preset as shown in Figure 10, choose the desired preset. (Refer Figure 9). You can also choose to manually enter the width and height of the display used. Refer Figure 9- 2b).

Choose the desired Color Mode from the drop-down list as shown in Figure 11.

The color mode set in this step should match the setting in the project graph for the LCD driver. An example is shown in Figure 12.

Figure 12: Project graph showing color mode setting for LCD driver

Choose the Memory Profile setting based on the target you are using. (Refer to Figure 9)

Click Create. If you chose to use the quickstart template in step 1, you will see a basic quickstart project open on MGS Harmony Composer as shown in Figure 13.

Designing with MGS Harmony Composer

MGS Harmony Composer allows you to add widgets, screens, schemes, assets, etc., to your design or edit those existing in your design. In this section, we show you how to perform these actions.

Adding/Editing Widgets

To add a widget to your design, choose the required widget from the Tool Box and drag it to the screen designer area.
The new widget is added to the active layer in the screen tree. Select from the Screen Tree the widget whose property you want to modify.
Select the Object Editor tab.
Edit the widget property in the Object Editor.

Press Ctrl+X / Ctrl+Z for undo/redo functionality.
Adjust the zoom level of the design by holding the Ctrl key while scrolling with your mouse.
Hold down the scroll button while moving the mouse to pan across the screen.
To learn more about editing widgets using Object Editor, visit the "Microchip Graphics Suite (MGS) Harmony Widgets Guide" page.

Adding/Editing Layers

The layer functionality is supported in specific devices (such as MPUs and PIC32MZ DA families of microcontrollers). Users must ensure that the target device supports layers before adding them to the Microchip Graphics Composer design. To learn more about layers and their role in graphics applications, refer to the "Working with Multiple Layers and HW Overlays" page.

When a new project is created in MGS Harmony Composer, by default a single layer is created for the screen. Additional layers can be added to the screen if the target device supports multi-layer screen design.

The Add New Layer icon allows you to add a layer. This layer automatically becomes an "active" layer to which new widgets are added.
You can choose a different layer to be active using the Activate Selected Layer button.
You can delete a selected icon using the Delete icon.
You can move widgets within a layer using the Move Object icons.
You can choose one or more widgets (by holding down Shift) and drag them over to a different layer (while holding down Shift if moving multiple widgets).
To edit a layer, choose the layer and edit it using Object Editor.
- Locked to Screen - If selected, this sets the layer size to the size of the display, otherwise, you can set a different width and height to the layer.
- Locked - If selected, you cannot drag more widgets from the toolbox to this layer. However, you can manually drag a widget from a different layer to this layer.
- Hidden - If selected, the layer is not visible in the designer area even though they will be rendered in the application. This feature is useful when you want to purview lower layers in the design area without the higher layers obstructing the view.

Adding/Editing Schemes

Schemes allow users to set the visual appearance of objects. To learn about the icons available in the Schemes pane, refer to the "Overview of the User Interface" section.

To learn about schemes including how to add new schemes, edit schemes, and apply a custom scheme to a widget, refer to the "About the Schemes and Scheme Editor" page.

Adding Screens

You can add screens, delete one or more screens, and duplicate a screen. You can choose the startup screen when multiple screens are present in the design. Icons are provided in the Screen Pane to perform these functions as discussed in the "Overview of the User Interface" section.

You can transition from one screen to another using application code.

Adding Assets

You can add assets to your design like images, fonts, and strings using the Asset Manager.

To learn how to add assets using Asset Manager, refer to the "Microchip Graphics Suite (MGS) Harmony Graphics Assets Guide" page.

Event Manager

Screens and input widgets generate events to be handled in the user application. The Event Manager allows you to select the events you want to handle in the user application, which can be accessed from the main menu as shown in Figure 16.

When the code is generated using MCC, the function definitions for these event handlers are included in the header file in the gfx\legato\generated\screen folder. An example is shown in Figure 17.

Figure 17: Event handlers in screen header file

Project Settings

From the Main Menu, click Project > Project Settings to access and set the project settings. Some commonly used project settings are discussed in this section.

Code Generator Generate Screen state Machine Generate Assets Generate Single Image File Generate Single Font File Generate Screens	Enabling this will call legato_updateScreenState() in Legato_Tasks Generates assets in le_gen_fonts, le_gen_images, le_gen_straingtable, etc Generates all images in le_gen_images.c, else, each image is in a separate file Generates all fonts in le_gen_fonts.c, else, each font is in a separate file Generates screen code in generated/screen/le_gen_screen_<screenname>.c
Display	Allows you to set the display width and height
Library Pre-emption level Streaming interface Image decoders PNG Scratch address Monochrome decoder	Allows you to configure advanced functions - re-orient the renderer, disable unused sections of the library, etc Lets you configure whether the library can fully block while updating a frame, or if it has to pre-empt itself in the middle of a frame update and let other Harmony tasks to run when running in bare metal mode Enables the callbacks from the library to fetch image and font assets from external media like SQI™ flash or USB drive If you are not using these image types, the corresponding decoders can be disabled to reduce program size Composer lets you assign a fixed address to process PNG to eliminate dynamic allocations for faster decoding Used to convert color images to black and white
Memory	MGS library has a memory manager to manage its own memory pools, the size and behavior of these memory pools are configured using Memory Settings You need to set the size of these memory pools based on the memory usage of your application The debug settings will let you enable instrumentation to help track memory usage and debug memory allocation issues
Renderer	Sets the color mode and scratch buffer size for the renderer If you are not using anti-aliased text or assets with transparency, alpha blending can be turned off

To learn more about using the Memory Settings from project settings, refer to the "Optimizing the Memory Manager Settings" page.
To learn how to set the scratch buffer size refer to the "Optimizing the Scratch Buffer Size" page.

Memory Location Manager

You can specify where you want assets saved in memory using the Memory Locations Manager, which you can access from the Main Menu by clicking Project > Memory Locations.

By default you see System Memories. You can add additional memories by clicking on the plus button icon. An example is shown in Figure 18, where 65KBytes of memory is set aside in QSPI at an offset of 0x70000000.

Now when you add images or fonts, you can can choose the memory location for storage as shown in Figure 19.

Figure 19: Storing assets in different memory location

Saving assets to other memory locations is useful when the application size or number of assets is large.

Saving Project

Once the design is complete, save the design by clicking on the save design button as shown in Figure 20. Optionally, from the Main Menu, click on File > Save or Save As.

When you are prompted to save the design, go to the MCC project config folder and provide the file name as the "<config_name>_design.zip" as shown in Figure 21. This will ensure that when you launch Microchip Graphics Composer from the MCC plugin, the design is automatically opened.

Save Project As — Figure 21: Saving the Composer design

If MCC has generated code for the project, you will see additional folders as seen in Figure 21. If you are saving the Composer design before MCC is used to generate code, you will see just the .legato_generate_cache.

On the console, you will see a log message indicating that the project is successfully saved as shown in Figure 22.

Figure 22: Console log showing project is saved

Generating Design Files

To generate design files for the MGS Harmony Composer project, click on the Generate Code button or click File > Generate Code from the Main Menu. On the Console, you will see a log message indicating that the output is successfully generated as shown in Figure 23.

Figure 23: Design successfully generated

Leaving the MGS Harmony Composer open and using MCC to generate code will automatically save and generate design output.

Overview of the Generated Files

Once the MCC project graph and the graphics design using MGS Harmony Composer is completed, click the Generate button from the Resource Management [MCC] pane to generate the project code.

The following table lists the generated files:

Generated files	Description
src/<config>/gfx/legato/generated- le_gen_fonts, le_gen_images, le_gen_scheme, le_gen_stringtable, le_gen_screen_<screenname>	Legato library and UI design files for: fonts, images, schemes, strings, screens
src/<config>/gfx/ driver, legato	MCC generated output for graphics - display controller driver(s), Microchip Graphics Suite library
src/app.c	User Application
src/<config>- .legato_generate_cache.zip <config>_design.zip	MGS Harmony Composer output

Importing Figma Design

Figma is a collaborative tool for creating screen designs for GUI based applications. An example of the screens for a EV Charger application is shown in Figure 25.

There are several assets that need to be imported and widgets that need to be added to the different screens in this design. The entire process can be completed in one-step by simply importing the Figma design to a blank project as shown in Figure 26.

Figma import — Figure 26: Figma design imported to MGS Harmony Composer project

Please refer to the Working with UI Designs in Figma document to learn how to:

Use the MGC Composer Exporter plugin for Figma and export the Figma design
How to import the figma design to MGS Harmony Composer project and optimize the design