Image Widget Documentation

Last modified by Microchip on 2024/03/29 13:33

Introduction

An Image Widget is a Graphical User Interface (GUI) that allow 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 that allows the user to import multiple images, select different image format/color modes for each image, select compression methods for each image, and display 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 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

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

Back to Top


To add Image 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

Back to Top


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

Screen 0

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 window

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.

Base Widget

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.

Scheme Property

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

Below is an example color scheme and the resulting image appearance:

Image Apearence Example

The information from the Image Scheme helper and the example color scheme is summarized in the following table.

Color Scheme

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

Name

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

For the image widget with the properties shown in the figure above, 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 height of 80.

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 to 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 it's 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 Harmony Web 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.

getImage()

leImage* getImage(const leImageWidget* _this)

Get the image properties from the image asset.

Parameters

leImageWidget*_thisImage widget pointer to operate on.

Returns image pointer.

setImage()

leResult setImage(leImageWidget* _this, leImage* imgAst)

Set the image widget to display the image asset.

Parameters

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

Returns LE_SUCCESS or LE_FAILURE.

Back to Top