Image Widget Documentation

Last modified by Microchip on 2024/06/21 11:36


An Image Widget is a Graphical User Interface (GUI) that allows users to customize their size, position, opacity, format, etc. The widget supports a wide range of image formats such as PNG, JPG, RAW, and GIF, and can be converted as RGB, PND, JPEG, and Monochrome. Image is imported from Image Manager, which allows importing multiple images, selecting different image format/color modes for each image, selecting compression methods for each image, and displaying the memory footprint of each.

The Image Widget document covers:

  1. Creating and customizing image widgets using Microchip Graphics Suite (MGS) Harmony Composer
  2. Image Properties
  3. Handling image widget properties and events through application code
  4. Image widget example project
  5. Application Program Interfaces (APIs) specific to Image 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 Image Widgets Using MGS Harmony Composer

Follow these steps to add an Image Widget to your design:

In the graphic composer, locate the Image widget within the Toolbox on the right panel. Drag and position this widget to your preferred location on the screen.

Image widget

Figure 1

Note that this widget is initially empty, thus requiring an import of the necessary image from the Image Manager.

Back to Top

To add and customize Image, go to Asset > Images. This will open the Image Manager. To learn how to use Image Manager, refer to the "Using Images in Microchip Graphics Suite (MGS)" page.

Asset > Images menu

Figure 2

Back to Top

After importing the desired images, return to Screen0. From there, import the image to the Image Widget from the Object Editor.

Object Editor pane

Figure 3

Back to Top

Upon encountering the Select Image pop-up window, choose the preferred image import into the Image widget, then proceed by clicking OK.

Select Image pop-up window

Figure 4

Back to Top

The intended image will subsequently appear on the Image Widget. Refer to the "Base Widget Documentation" page for a detailed description of the properties listed in Object Editor.

image on the Image Widget

Figure 5

Back to Top

Managing Image Widget Schemes

Schemes control the look and feel of a widget.

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 an image, click on the question mark button next to the Scheme property editor of the Object Editor.

Object Editor pane

Figure 6

This will launch the Image Scheme Helper window containing tips on how different sections of the scheme settings manipulate various elements of the image.

Image Scheme Helper window

Figure 7

Figure 2 shows an example color scheme and the resulting image appearance:

example color scheme and the resulting image appearance

Figure 8

The information from the Image Scheme helper and the example color scheme is summarized in Figure 9.

information from the Image Scheme helper and the example color scheme

Figure 9

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

Image Properties


This will be used to reference the image by the application. Example- Screen0_ImageWidget_0.
ImageThis will be used to add Image to the widget that will display on the Image Widget.

Widget properties specific to Image Widget were discussed. For the properties common to all widgets, refer to the "Base Widget Documentation" page.

Back to Top

Managing Image 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 User Interface (UI) and developing application code, refer to the "Designing an Application with Microchip Graphics Suite (MGS)" page.

Let us suppose that an image widget is created with the following properties in MGS Harmony Composer:

Object Editor pane

Figure 10

For the image widget with the properties shown in Figure 10, MCC will automatically generate the following lines of code in src\confg\default\gfx\legato\generated\screen\le_gen_screen_Screen0.c

  • A new image widget is created by the variable name Screen0_Image1.

 Screen0_Image1= leImageWidget_New();

  • Its position is set to pixel location 20x120.

 Screen0_Image1->fn->setPosition(Screen0_Image1, 20, 120);

  • The image size is set to have a width of 80 pixels and a height of 80 pixels.

Screen0_Image1->fn->setSize(Screen0_Image1, 80, 80);

  • This image scheme is set to Scheme1

Screen0_Image1->fn->setScheme(Screen0_Image1, Scheme1);

  • This image is set to have no border in this example. However, you can have a line border or a beveled border.

Screen0_Image1->fn->setBorderType(Screen0_Image1, LE_WIDGET_BORDER_NONE);

  • This image is imported from the Image Asset and its image name is "icon1".

Screen0_Image1->fn->setImage(Screen0_Image1, (leImage*)&icon1);

  • Finally, the image is added to the screen.

root0->fn->addChild(root0, (leImage*)(leWidget*)Screen0_Image);

Back to Top

Image Widget Example Project

The example image widget project illustrates the various settings in which an image can be placed:

  1. Set as background
  2. How to add Scheme for an image
  3. How to apply Alpha Blending and adjust Alpha level
  4. Add border line

Back to Top

MGS Simulator Output

Simple Image example

Back to Top

Image Widget APIs Description

This section describes the APIs specific to the image widget. For a description of APIs common to all widgets, refer to the "Base Widget Documentation" page.


leImage* getImage(const leImageWidget* _this)

Get the image properties from the image asset.


leImageWidget*_thisImage widget pointer to operate on.

Returns image pointer.


leResult setImage(leImageWidget* _this, leImage* imgAst)

Set the image widget to display the image asset.


leImageWidget*_thisImage widget pointer to operate on.
leImage*imgAstPointer to the image asset that should show on the image widget.


Back to Top