Microchip Graphics Suite (MGS) Harmony Composer User Guide

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

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

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

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
Open existing design
Save design
Generate code

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

	Adds a new screen
	Deletes the selected screen
	Deletes all the screens
	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:

	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.

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.
Console: The console displays actions performed by the MGS Harmony Composer such as Opening of a project, saving, output generation etc.
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).
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.
- To learn how to use the object editor to edit the different widgets, refer to the widget tutorial.
- To learn how to use the scheme editor to edit the scheme, refer to the "About the Schemes and Scheme Editor" page.

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

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

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.

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

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

Choose the desired color mode and click Next.

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.

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

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

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.

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

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 the widget you want to edit from the Screen tree and edit it in the Object Editor.

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

Adding/Editing Layers

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.

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.

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

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

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.

Figure 14: 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 15, 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 16.

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.

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.

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.

Figure 19: 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