Microchip Graphics Suite (MGS) Harmony Composer User Guide

Last modified by Microchip on 2024/04/01 09:35


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

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:

Microchip Graphics Composer window

Figure 1: Microchip Graphics Suite Composer Main Window

  1. 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:

    FileOpen, Save, Import, and Generate design files
    EditUndo/Redo, Cut/Copy/Paste, set user preference to auto-save design while generating design files for MCC
    ViewSet object clipping (if clipping is turned on, objects are clipped to the rectangles of their parents when they are rendered) and display language preferences
    ProjectSet project properties, launch event manager, memory tools
    AssetAdd assets for images, fonts, strings, and palette
    WindowManage user interface windows
  2. Toolbar: Below the main menu is the toolbar. It contains convenience buttons that you can click to perform the following tasks:


    Create a new design

    1711147363330-643.pngOpen existing design

    Save design


    Generate code

  3. Screen Tree Pane: At the top left is the screen tree pane. It 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

    1711147385823-840.pngDeletes the selected layer
    1711147385823-806.pngMoves the selected widget up the tree
    1711147385823-434.pngMoves the selected widget to the top of the layer
    1711147385824-185.pngMoves the selected widget down the tree
    1711147385824-310.pngMoves the selected widget to the bottom of the layer
  4. Screen and Scheme Pane: At the bottom left, are screen and scheme panes.

    Screen Pane: You can create one or more screens. Each screen will contain layers and each layer will contain widgets. The following screen-related icons are provided:

    1711155469230-520.pngAdds a new screen
    1711155469230-448.pngDeletes the selected screen
    1711155469231-972.pngDeletes all the screens
    1711155469231-440.png Duplicates a screen

    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.

    Scheme Pane: Schemes define color layout. They can be assigned to objects such as widgets. The following scheme related icons are provided:

    1711162651972-906.pngAdds a new
    1711162683911-950.pngDeletes the selected scheme
    1711155469231-972.pngDeletes all the schemes
    1711162739100-541.pngBrings up the scheme editor to edit the selected scheme
    1711162814733-910.pngPrecomputes alpha blending of selected colors into a lookup table for enhanced performance
    1711162856531-602.pngResets the scheme to default values
    1711162893612-107.pngSets 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.

  5. 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.

  6. Console: The console displays actions performed by the MGS Harmony Composer such as Opening of a project, saving, output generation etc. 

  7. Tool Box Pane: To the right of the screen designer is the toolbox. 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 (#5 in this list).

  8. Object and Scheme Editor Pane: At the bottom right are the object and scheme editor panes using which you can edit the properties of widgets and schemes. 

Back to Top

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. 

Back to Top

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.

Back to Top


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


Figure 2: 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 3: 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 4.

Microchip Graphics Composer window

Figure 4: MGS Harmony Composer on launch

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 the next section, we show you how to create a design from scratch using the wizard.

Back to Top


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.

Back to Top

Using MGS Harmony Composer New Project Wizard

From Figure 4, 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. We will now learn how to create a new design using the wizard.

Click the Create a new project New Project button button.

Back to Top

You can choose a preset, if available, for your display and click Apply or directly enter the width and height of the display used. Click Next.

New Project Wizard

Figure 5: Display Configuration

Back to Top

Choose the desired color mode and click Next

New Project Wizard

Figure 6: Color Mode

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

Project graph showing color mode setting for LCD driver

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

Back to Top

Choose the Memory Profile setting based on the target you are using. Click Next.

New Project Wizard

Figure 8:  Memory Profile

Back to Top

If you want a project with a quickstart template containing a few assets and widgets, select Start with a basic quickstart project template, otherwise leave it unchecked. Click Next

New Project Wizard

Figure 9: Basic quickstart template

Back to Top

Finally, click Finish. If you choose to create the project with a basic template, you will see the design as shown in Figure 10.

Basic quickstart example

Figure 10: Basic quickstart example

Back to Top

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.

Back to Top

Adding/Editing Widgets

  1. To add a widget to your design, choose the required widget from the Tool Box and drag it to the screen designer area.

  2. The new widget is added to the active layer in the screen tree.
  3.  Select the widget you want to edit from the Screen tree and edit it in the Object Editor.
Adding/Editing Widgets

Figure 11: Adding/Editing Widgets

To learn more about editing widgets using Object Editor, visit the "Microchip Graphics Suite (MGS) Harmony Widgets Guide" page.

Back to Top

Adding/Editing Layers

  1. The Add New Layer icon allows you to add a layer. This layer automatically becomes an "active" layer to which new widgets are added. 
  2. You can choose a different layer to be active using the Activate Selected Layer button.
  3. You can delete a selected icon using the Delete icon.
  4. You can move widgets within a layer using the Move Object icons.
  5. 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).
  6. 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 Layers

Figure 12: 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.

Back to Top

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.

Back to Top

Adding Screens

You can add screens, delete one more screen, 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.

Back to Top

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.

Back to Top

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 13.

event Manager GIF

Figure 13: Event Manager

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 14.

Event handlers in screen header file

Figure 14: Event handlers in screen header file

Back to Top

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


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



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


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

Back to Top

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 15, where 65KBytes of memory is set aside in QSPI at an offset of 0x70000000. 

Memory Locations

Figure 15: Adding new memory location in QSPI to store assets

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

Storing assets in different memory location

Figure 16: Storing assets in different memory location

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

Back to Top

Saving Project

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

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

Save Project As

Figure 17: Saving the Composer design

If MCC has generated code for the project, you will see additional folders as seen in Figure 16. 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.

Console log showing project is saved

Figure 18: Console log showing project is saved

Generating Design Files

To generate design files for the MGS Harmony Composer project, click on the Generate Code Generate code button icon 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. 

Design successfully generated

Figure 19: Design successfully generated

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

Back to Top

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.

Generate MCC code

Figure 20: Generate MCC code

The following table lists the generated files:

Generated filesDescription


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


driver, legato

MCC generated output for graphics - display controller driver(s), Microchip Graphics Suite library
src/app.cUser Application


.legato_generate_cache.zip <config>_design.zip

MGS Harmony Composer output

Back to Top

Learn More

Back to Top