Creating a New GUI Application From Scratch
Introduction
This user guide provides information on how to create a new Microchip Graphics Suite (MGS) Graphical User Interface (GUI) application from scratch.
Directory Structure
The SDK's directory structure is as follows:
| File/Directory | Sub-Folder | Description |
| CMakeLists.txt | CMake configuration file | |
| apps | Contains the MGS Quickstart and demo applications | |
| gfx | Contains the MGS graphics library | |
| system | Contains the platform-specific library and interface code | |
| /gfx | Cross-platform versions of certain MGS library middleware | |
| /linux | Interface code for Linux®-based platforms |
Adding a New Application
To add a new MGS application to the SDK, the application folder must be created in the apps/ directory. For example, to create a new application named "mynewapp":
cd <mgs_xp>
mkdir -p apps/mynewapp
In the application folder, add the app and gfx subfolders.
mkdir -p apps/mynewapp/gfx
mkdir -p apps/mynewapp/app
These subdirectories will contain the following:
| apps/ subfolder | Description |
| gfx | Will contain the MGS Composer-generated code |
| app | Will contain the application code, like the screen and widget event callbacks and other application-specific code |
Next, create a main.c file for the new application. The quick way to do this is to copy the existing main.c from the MGS Quickstart application to the new application folder.
cp apps/quickstart/main.c apps/mynewapp/
Then, add the CMake configuration file for the new application. You can create a new CMakeLists.txt file or copy and modify the one from the MGS Quickstart application example.
cp apps/quickstart/CMakeLists.txt apps/mynewapp/
Modify the CMakeLists.txt file and change mgs_quickstart to the new application name, mynewapp.
vi apps/mynewapp/CMakeLists.txt
Next, update the root CMakeLists.txt file to include the new application to the build.
vi CMakeLists.txt
Creating a New MGS Composer Project
The next step is to create a new MGS Composer project.
First, launch MGS Composer using the steps in the user guide.
Use the New Project Wizard to create a New Project.
Set the project configuration.
A. Template: Clean Design if starting from a blank screen, or select Quickstart to start with a simple GUI design.
B. Display Resolution: Select a preset resolution or manually set the display width and height.
C. Color Mode: Use RGB565 for 16-bit colors, or RGBA8888 for 32-bit colors with alpha.
D. Memory Profile: Select MPU for embedded Linux devices. This will configure the memory pools and scratch buffer for MPUs.
E. Create: Click to create the new design.
Quickstart Design
The following image shows a Quickstart design, which contains an image, a button, and a label.
Clean Design
A clean design will have a screen and a background panel identical to the one shown in the accompanying image.
Configuring the MGS Composer Project Settings
The MGS Composer project settings will need to be configured further for a cross-platform configuration. In MGS Composer, go to Project > Settings.
Code Generator Settings
The code generator needs to be set so MGS Composer will generate the screen design code to the right location in the project.
Click Code Generator.
Uncheck Generate Harmony Interface. This will disable all Harmony-specific generated code.
Set Generate Path to the absolute path of the gfx folder in the new application directory, <mgs_xp>/apps/mynewapp/gfx.
Set Generate Name to legato.
Renderer Settings
The renderer needs to be configured so that the scratch buffer size is optimized. Ideally, the scratch buffer size must be greater than or equal to the frame buffer size in bytes, which is width × height × bytes per pixel.
For this example project, the frame buffer size is 800 × 480 × 2 bytes per pixel = 768 kB. So the scratch buffer size (kB) is set to 768.
Start Designing the UI
You can start designing the UI by dragging and dropping the widgets from the toolbar.
In the example below, a button widget is added and resized to the screen.
For more information on how to use MGS Composer, refer to the "Microchip Graphics Suite (MGS) Harmony Composer User Guide".
MGS Composer on Linux can also import designs from Figma®. See "Working with UI Designs in Figma" for details.
Save and Generate the Design
Save the MGS project to the new application folder. For this example, the design project file is named using the convention, design_<resolution>.zip.
Next, generate the design by clicking the Generate button in MGS Composer.
This will generate the design source files to the <mgs_xp>/apps/<new application>/gfx/legato directory.
Building and Running the Application
Build the application for desktop Linux and run the cmake commands to reconfigure the makefiles.
cd <mgs_xp>/build/host
cmake ../../
make all -j
The new application build output will be in the <mgs_xp>/build/host/apps/mynewapp/ directory. Launch the application directly.
./apps/mynewapp/mynewapp
The new application will launch in its own window.
Clicking on the gray button will toggle it.
To build the new application for the embedded Linux device, refer to "Building Microchip Graphics Suite (MGS) for Embedded Linux".