Image Sequence Widget Documentation

Last modified by Microchip on 2024/09/26 16:53

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:

  1. Creating and customizing image sequence widgets using Microchip Graphics Suite (MGS) Harmony Composer.
  2. Image Sequence widget Properties.
  3. Handling Image Sequence widget properties and events through application code.
  4. Image Sequence widget example project.
  5. 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.

Image Sequence Widget

Figure 1: Select Image Sequence Widget

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.

Back to Top


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.

 

Back to Top


In the Configure Data Items window, click on Plus button 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.

Configure Data Items

Figure 3: Modify images settings in the Configure Data Items window.

1NameName of this entry
2ImageThe image name that is imported from the Image Asset
3Horizontal AlignmentHorizontal alignment (Left, Center, Right).
4Vertical AlignmentVertical alignment (Top, Middle, Bottom).
5Duration

The duration to show the image in milliseconds, ex: 1000 ms

Table 1: Image Sequence Entry Settings.

Back to Top


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.

Delta Time

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 :

app_legato_Query Delta Time

Figure 6: app_Legato_QueryDeltaTime declaration in le_gen_harmony.c.

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

 

Back to Top

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 Question button button next to the Scheme Property editor of the Object Editor.

Scheme

Figure 7: Scheme button from 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.

Scheme Helper

Figure 8: Image Sequence Scheme Helper.

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.

Back to Top

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 ImageThe starting index of the image to display in the Image Sequence widget.
Play By DefaultIndicates if the image sequence should play automatically. 
RepeatIndicates if the image sequence should repeat after displaying the last image.
Image ChangedThis 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.

Back to Top

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:

Object Editor

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);

Back to Top

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);  

Back to Top

Image Sequence Widget Example Project

Refer to the Image sequence widget example project in GitHub:

In this example, we show:

  1. How to configure multiple images to the Image sequence widget.
  2. 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.
  3. How to add Play By Default and Repeat feature for image sequence.
  4. How to add application code to Image Changed event.

Back to Top

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

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.

Example 2

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

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;
    }

}

Back to Top

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*_thisThe image sequence widget to operate on.

Returns the number of images the widget is configured to use.

setImageCount()

leResult setImageCount(leImageSequenceWidget* _this, uint32_t* count)

Sets the number of images the widget will use. If the number of images assigned to the widget through the composer is 10, and the setImageCount(5) is called, the widget is configured to use only five images.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.
uint32_t*countNumber of image entries for this widget

Returns LE_SUCCESS or LE_FAILURE.

getImage()

leImage* getImage (const leImageSequenceWidget* _this, uint32_t idx)

Gets the image pointer.

Parameters

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

Returns idx the image pointer.

setImage()

leResult setImageCount(leImageSequenceWidget* _this, uint32_t idx, const leImage* imgAst)

Sets the image pointer.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.
uint32_t*idxThe index
leImage*imgAstThe image pointer

Returns LE_SUCCESS or LE_FAILURE.

getImageDelay()

uint32_t getImageDelay(const leImageSequenceWidget* _this, uint32_t* idx)

Gets the image cycle delay.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.
uint32_t*idxThe index

Returns the image delay.

setImageDelay()

leResult setImageDelay(leImageSequenceWidget* _this, uint32_t idx, uint32_t dly)

Sets the image delay.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.
uint32_t*idxThe index
uint32_tdlyThe image delay

Returns LE_SUCCESS or LE_FAILURE. 

getImageHAlignment()

leHAlignment getImageHAlignment(const leImageSequenceWidget* _this, uint32_t idx)

Gets the image horizontal alignment.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.
uint32_t*idxThe index

Returns the alignment.

setImageHAlignment()

leResult setImageHAlignment(leImageSequenceWidget* _this, uint32_t idx, leHAlignment align)

Sets the image horizontal alignment.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.
uint32_tidxThe index
leHAlignmentalignThe alignment

Returns LE_SUCCESS or LE_FAILURE.

getImageVAlignment()

leVAlignment set(leImageSequenceWidget* _this, uint32_t idx)

Gets the image vertical alignment.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.
uint32_tidxThe index

Returns the alignment.

setImageVAlignment()

leResult setImageVAlignment(leImageSequenceWidget* _this, uint32_t idx, leVAlignment align)

Sets the image vertical alignment.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.
uint32_tidxThe index
leVAlignmentalignThe alignment

Returns LE_SUCCESS or LE_FAILURE.

stop()

leResult stop(leImageSequenceWidget* _this)

Stops the sequence from automatically cycling.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.

Returns LE_SUCCESS or LE_FAILURE.

play()

leResult play(leImageSequenceWidget* _this)

Starts the sequence automatic cycle.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.

Returns LE_SUCCESS or LE_FAILURE.

rewind()

leResult rewind(leImageSequenceWidget* _this)

Returns the sequence to the first image.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.

Returns LE_SUCCESS or LE_FAILURE.

isPlaying()

leBool isPlaying(const leImageSequenceWidget* _this)

Indicates if the sequence is automatically cycling.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.

Returns LE_TRUE or LE_FALSE.

getRepeat()

leBool getRepeat(const leImageSequenceWidget* _this)

Indicates if the sequence will repeat the cycle.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.

Returns LE_TRUE or LE_FALSE.

setRepeat()

leResult setRepeat(leImageSequenceWidget* _this, leBool rpt)

Sets the repeat flag.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.
leBoolrptThe setting value.

Returns LE_SUCCESS or LE_FAILURE.

showImage()

leResult showImage(leImageSequenceWidget* _this, uint32_t idx)

Sets the current visible image index.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.
uint32_tidxThe index

Returns LE_SUCCESS or LE_FAILURE.

showNextImage()

leResult showNextImage(leImageSequenceWidget* _this)

Advance to the next image.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.

Returns LE_SUCCESS or LE_FAILURE.

showPreviousImage()

leResult showPreviousImage(leImageSequenceWidget* _this)

Return to the previous image.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.

Returns LE_SUCCESS or LE_FAILURE.

getImageChangedEventCallback()

leImageSequenceImageChangedEvent_FnPtr getImageChangedEventCallback(const leImageSequenceWidget* _this)

Get image changed event callback pointer.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.

Returns the callback pointer. 

setImageChangedEventCallback()

leResult setImageChangedEventCallback(leImageSequenceWidget* _this, leImageSequenceImageChangedEvent_FnPtr cb)

Sets image changed event callback pointer.

Parameters

leImageSequenceWidget*_thisThe image sequence widget to operate on.
leImageSequenceImageChangedEvent_FnPtrcbThe callback function

Returns LE_SUCCESS or LE_FAILURE.

Back to Top