Image Sequence Widget Documentation

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

Introduction

The Image Sequence widget allows the image displayed on the screen to be scheduled and sequenced. To transition through the images in the sequence, the application can utilize the widget Application Programming Interfaces (APIs) or employ a system timer within the graphics library to automatically play the images in sequence.

The Image Sequence Widget document covers:

Creating and customizing image sequence widgets using Microchip Graphics Suite (MGS) Harmony Composer.
Image Sequence widget Properties.
Handling Image Sequence widget properties and events through application code.
Image Sequence widget example project.
APIs specific to Image Sequence 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 Sequence Widgets Using MGS Harmony Composer

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

In the Graphic Composer, locate the ImageSequenceWidget within the Toolbox on the left panel. Drag and position this widget to your preferred location on the screen.

Note: To use the Image Sequence widget, we need to first import images to the project using Image Manager. To learn how to use Image Manager, refer to the "Using Images in Microchip Graphics Suite (MGS)" page.

Select the Image Sequence widget and click the Configure button in the Object Editor to add images to the widget, as shown in Figure 2.

Configure Images — Figure 2: Add multiple images by clicking on the Configure button.

In the Configure Data Items window, click on button at the top left, then choose the desired images from the Select Image window by clicking on the button beside the Image property and click OK. Each entry is configurable based on the settings information shown in Table 1. Similarly, add as many images as required and click Close.

1	Name	Name of this entry
2	Image	The image name that is imported from the Image Asset
3	Horizontal Alignment	Horizontal alignment (Left, Center, Right).
4	Vertical Alignment	Vertical alignment (Top, Middle, Bottom).
5	Duration	The duration to show the image in milliseconds, ex: 1000 ms

Table 1: Image Sequence Entry Settings.

The intended image will subsequently appear on the Image Sequence widget.

Image Sequence Screen — Figure 4: Image Sequence Widget displaying the first image in the sequence.

To allow the graphics library to display images in the sequence automatically, the application developer must define a system timer. To do this, from Project Settings, click Code Generator and enable Generate Delta Time Interface.

Figure 5: Configure Delta Time Interface from Project Settings.

Enabling this feature will declare a timer in the le_gen_harmony.c file as shown in the accompanying image :

Note: The application developer must define the function app_Legato_QueryDeltaTime(void) in the application code.

Managing Image Sequence Widget Scheme

Schemes control the look and feel of a widget.

Note: 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 Image Sequence widget, click on the button next to the Scheme Property editor of the Object Editor.

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

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

Scheme Settings — Figure 9: Scheme settings for Image Sequence Widget.

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

Scheme Color — Figure 10: Description of Scheme Helper.

Note: Understanding how the various segments of the color table influence the appearance of the image assists you in selecting the appropriate colors.

Image Sequence Properties

Name	This will be used to reference the image sequence widget by the application. Example- Screen0_ImageSequenceWidget_0.
Configure Images	This will be used to configure and add multiple images entry to the Image Sequence widget.
Starting Image	The starting index of the image to display in the Image Sequence widget.
Play By Default	Indicates if the image sequence should play automatically.
Repeat	Indicates if the image sequence should repeat after displaying the last image.
Image Changed	This event is generated when the current image changes.

Table 2: Image Sequence Properties.

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

Managing Image Sequence Widget Through Programming

Once the graphical design is completed using MGS 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 sequence widget is created with the following properties in MGS Composer:

Figure 11: Image Sequence Widget Object Editor.

For the image sequence widget with the properties shown in Figure 11, 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 sequence widget is created by the variable name Screen0_ImageSequenceWidget_1.

Screen0_ImageSequenceWidget_1 = leImageSequenceWidget_New();

Its position is set to pixel location 495 x 171.

Screen0_ImageSequenceWidget_1 ->fn->setPosition(Screen0_ImageSequenceWidget_1, 495, 171);

The image size is set to have a width of 79 pixels and a height of 47 pixels.

Screen0_ImageSequenceWidget_1 ->fn->setSize(Screen0_Image1, 79, 47);

The image sequence background type is set to NONE.

Screen0_ImageSequenceWidget_1 ->fn->setBackgroundType(Screen0_ImageSequenceWidget_1, LE_WIDGET_BACKGROUND_NONE);

The image sequence image count is set to 5.

Screen0_ImageSequenceWidget_1->fn->setImageCount(Screen0_ImageSequenceWidget_1, 5);

This image sequence entry 0 image is set to ImageBatt0.

Screen0_ImageSequenceWidget_1->fn->setImage(Screen0_ImageSequenceWidget_1, 0, &ImageBatt0);

This image sequence entry 0 image delay time is set to 1000 milliseconds.

Screen0_ImageSequenceWidget_1->fn->setImageDelay(Screen0_ImageSequenceWidget_1, 0, 1000);

Note: Similarly, for each image entry, the setImage and setImageDelay API is called.

Finally, the image sequence is added to the screen.

root0->fn->addChild(root0, (leWidget*)Screen0_ImageSequenceWidget_1);

Application Code

The default code generated by MCC sets the initial state of the widget. The property or behavior of the widgets can be changed by using the APIs discussed above, in the application code. Additional application code information related to the Image Sequence widget is presented below.

Here is an example to display the current image index shown on the Image Sequence widget.

/* When Image is changed, OnImageChanged event is called and get the current image index that is displayed on the Image Sequence widget*/

void event_Screen0_ImageSequenceWidget_0_0_OnImageChanged(leImageSequenceWidget* wgt)

{

    int32_t currentImage;
    currentImage = Screen0_ImageSequenceWidget_0_0->activeIdx;
    printf("Current Image Index: %d", currentImage);

}

Other Image Sequence widget application examples as shown below:

To display the next image entry from the Configure Data Items.

Screen0_ImageSequenceWidget_0_0->fn->showNextImage(Screen0_ImageSequenceWidget_0_0);

To display the previous image entry from the Configure Data Items.

Screen0_ImageSequenceWidget_0_0->fn->showPreviousImage(Screen0_ImageSequenceWidget_0_0);

To play the image sequence automatically.

Screen0_ImageSequenceWidget_0_0->fn->play(Screen0_ImageSequenceWidget_0_0);

To stop the image sequence to the current image index.

Screen0_ImageSequenceWidget_0_0->fn->stop(Screen0_ImageSequenceWidget_0_0);

Image Sequence Widget Example Project

Refer to the Image sequence widget example project in GitHub:

In this example, we show:

How to configure multiple images to the Image sequence widget.
How to create a system timer to automatically play/stop images assigned to the Image Sequence widget. Alternatively, the images can be stepped through manually using the widget APIs.
How to add Play By Default and Repeat feature for image sequence.
How to add application code to Image Changed event.

MGS Simulator Output

Simple Image Sequence Example

Callback functions for handling the screen events are defined in the app.c file.

When the + (plus) button is pressed, all three Image Sequence widgets will show the next image in the sequence using showNextImage API. Similarly, when the - (minus) button is pressed, all three Image Sequence widgets will show the previous image in the sequence using showPreviosImage API, as shown in Figure 12.

Figure 12: Example 1 - Image Sequence show next and previous image manually.

/* When the "+" button is in released state, show next image for all image sequence widget */
void event_Screen0_ButtonWidget_0_OnReleased(leButtonWidget* btn)
{
    Screen0_ImageSequenceWidget_0_0->fn->showNextImage(Screen0_ImageSequenceWidget_0_0);
    Screen0_ImageSequenceWidget_0_1->fn->showNextImage(Screen0_ImageSequenceWidget_0_1);
    Screen0_ImageSequenceWidget_0_2->fn->showNextImage(Screen0_ImageSequenceWidget_0_2);
}
/* When the "-" button is in released state, show previous images for all image sequence widget */
void event_Screen0_ButtonWidget_0_0_OnReleased(leButtonWidget* btn)
{
    Screen0_ImageSequenceWidget_0_0->fn->showPreviousImage(Screen0_ImageSequenceWidget_0_0);
    Screen0_ImageSequenceWidget_0_1->fn->showPreviousImage(Screen0_ImageSequenceWidget_0_1);
    Screen0_ImageSequenceWidget_0_2->fn->showPreviousImage(Screen0_ImageSequenceWidget_0_2);
}

When Play button is pressed, the images assigned to the widget will be played in a sequence automatically using the system timer. The Image Sequence widget repeat property is enabled in the Graphics Composer as shown in Figure 13. Therefore, the sequence is played in a loop.

Repeat_Feature — Figure 13: Repeat feature enabled from Object Editor.

When the Stop button is pressed, the widget stops at the current index and continues to play when the user presses the Play button again, as shown in Figure 14.

Figure 14: Example 2 - Image Sequence play automatically when pressing the play button and repeat the sequence.

/* When the "play" button is in released sate, show previous images for all image sequence widget *

void event_Screen0_ButtonWidget_0_1_OnReleased(leButtonWidget* btn)

{

    Screen0_ImageSequenceWidget_1_0->fn->play(Screen0_ImageSequenceWidget_1_0);
    Screen0_ImageSequenceWidget_1_1->fn->play(Screen0_ImageSequenceWidget_1_1);
    Screen0_ImageSequenceWidget_1_2->fn->play(Screen0_ImageSequenceWidget_1_2);

}

/* When the "stop" button is in released state, show previous images for all image sequence widget */

void event_Screen0_ButtonWidget_0_1_0_OnReleased(leButtonWidget* btn)

{

    Screen0_ImageSequenceWidget_1_0->fn->stop(Screen0_ImageSequenceWidget_1_0);
    Screen0_ImageSequenceWidget_1_1->fn->stop(Screen0_ImageSequenceWidget_1_1);
    Screen0_ImageSequenceWidget_1_2->fn->stop(Screen0_ImageSequenceWidget_1_2);

}

By enabling Play By Default, the image sequence will play automatically without any application code.

Figure 15: Example 3 - Image Sequence Widget "Play by Default"

The Play by Default requires a system timer to be defined in the application code. An example is shown below:

Note: Ensure that the Generate Delta Time Interface property is set (as shown in Figure 5) in the composer as discussed in Step 4 in the section "Designing Image Sequence with using MGS Harmony Composer".

The example below utilizes clock_gettime() to query the system time; alternatively, one could employ the hardware timer, which triggers every millisecond, to obtain the delta time with millisecond precision.

/*Global variable to store the time of the last update*/
static struct timespec LastUpdate;

/*Call this function once before starting the update loop to initialize the last update time*/

void app_Legato_InitializeUpdateTime(void)

{

clock_gettime(CLOCK_MONOTONIC, &lastUpdateTime);

}

/*Implementation of the QueryDeltaTime function*/
uint32_t app_Legato_QueryDeltaTime(void)

{

struct timespec currentTime;
clock_gettime(CLOCK_MONOTONIC, &currentTime);

    // Calculate the delta time in milliseconds
    uint32_t deltaTime = (currentTime.tv_sec - lastUpdateTime.tv_sec) * 1000 +
                         (currentTime.tv_nsec - lastUpdateTime.tv_nsec) / 1000000;

// Update the last update time to the current time
lastUpdateTime = currentTime;

return deltaTime;

}

In the example OnImageChanged event handler shown below, the activeIdx of the Image Sequence widget is read and based on this, the string value of the label widget Screen0_LabelWidget_1 is changed.

/* Change the string in label widget when image changed event occurs */
void event_Screen0_ImageSequenceWidget_0_0_OnImageChanged(leImageSequenceWidget* wgt)
{

int32_t currentImage;

//get the current image index from the Configure Data Items
currentImage = Screen0_ImageSequenceWidget_0_0->activeIdx;

//show different battery percentage in string when image change to different stage
    switch(currentImage)
    {
        case 0:
            Screen0_LabelWidget_1->fn->setString(Screen0_LabelWidget_1, (leString*)&string_Battery0);
            break;

        case 1:
            Screen0_LabelWidget_1->fn->setString(Screen0_LabelWidget_1, (leString*)&string_Battery1);
            break;

        case 2:
            Screen0_LabelWidget_1->fn->setString(Screen0_LabelWidget_1, (leString*)&string_Battery2);
            break;

        case 3:
            Screen0_LabelWidget_1->fn->setString(Screen0_LabelWidget_1, (leString*)&string_Battery3);
            break;

        case 4:
            Screen0_LabelWidget_1->fn->setString(Screen0_LabelWidget_1, (leString*)&string_Battery4);
            break;
    }

}

Image Sequence Widget APIs Description

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

getImageCount()

uint32_t* getImageCount(const leImageSequenceWidget* _this)

Gets the number of images that is added in the Configure Data Items.

Parameters

leImageSequenceWidget*

_this

Returns LE_TRUE or LE_FALSE.

setRepeat()

leResult setRepeat(leImageSequenceWidget* _this, leBool rpt)

Sets the repeat flag.

Parameters

leImageSequenceWidget*	_this	The image sequence widget to operate on.
leBool	rpt	The setting value.

Returns LE_SUCCESS or LE_FAILURE.

showImage()

leResult showImage(leImageSequenceWidget* _this, uint32_t idx)

Sets the current visible image index.

Parameters

leImageSequenceWidget*	_this	The image sequence widget to operate on.
uint32_t	idx	The index

Returns the callback pointer.

setImageChangedEventCallback()

leResult setImageChangedEventCallback(leImageSequenceWidget* _this, leImageSequenceImageChangedEvent_FnPtr cb)

Sets image changed event callback pointer.

Parameters

leImageSequenceWidget*	_this	The image sequence widget to operate on.
leImageSequenceImageChangedEvent_FnPtr	cb	The callback function

Returns LE_SUCCESS or LE_FAILURE.

Image Sequence Widget Documentation

Introduction

Designing Image Sequence Widgets Using MGS Harmony Composer

Managing Image Sequence Widget Scheme

Image Sequence Properties

Managing Image Sequence Widget Through Programming

Application Code

Image Sequence Widget Example Project

MGS Simulator Output

Image Sequence Widget APIs Description

getImageCount()

Parameters

setImageCount()

Parameters

getImage()

Parameters

setImage()

Parameters

getImageDelay()

Parameters

setImageDelay()

Parameters

getImageHAlignment()

Parameters

setImageHAlignment()

Parameters

getImageVAlignment()

Parameters

setImageVAlignment()

Parameters

stop()

Parameters

play()

Parameters

rewind()

Parameters

isPlaying()

Parameters

getRepeat()

Parameters

setRepeat()

Parameters

showImage()

Parameters

showNextImage()

Parameters

showPreviousImage()

Parameters

getImageChangedEventCallback()

Parameters

setImageChangedEventCallback()

Parameters

Menu

On This Page

Microchip Support