List Widget Documentation

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

Introduction

A list widget is a user interface component used in software and web development to display a collection of items in a scrollable list format. It allows users to view multiple entries and select one or more items from the list for further interaction.

This list widget document covers the following topics:

  1. Creating and customizing list widgets using Microchip Graphics Suite (MGS) Harmony Composer.
  2. List properties.
  3. Handling list widget properties and events through application code.
  4. List widget example project.
  5. Application Program Interfaces (APIs) specific to list widgets.

Note: 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 List Widgets Using MGS Harmony Composer

To add a list widget to your design, follow the steps given below:

Select and drag the List from the Tool Box to your screen designer workspace as shown in the figure below:

List Tool Box

Back to Top


To customize the list, select it on the screen designer and modify its properties using the Object Editor. You can create a list of entries for the list widget using the Configure Items property, by following the steps below:

Click on the Configure button next to the Configure Items property:
list Configure

In the Configure List Items window, click in the green + icon:

add List Item

Note: You may choose to add the entries for your list from the application code using static or dynamic strings instead of adding them through the MGS Harmony Composer.

For Item 0, click on the button for String property and from the Select String window, choose the desired string:

List Item Add String

Here is an example of list with just string entries:

string Only List

Note: To learn how to import images and set strings for your widget, please refer to the "Microchip Graphics Suite (MGS) Harmony Graphics Assets Guide" page.

Optionally, if you want to set an image or icon for the list beside the string, click on the button for Image property and from the Select Image window, choose the desired Image:

list Item Add Image
  

When you create a list with both images and strings, you can choose the image position with respect to the string using the Image Position property. Image can be to the left of, right of, or behind the string. You can also control the space between the string and image using the Image Margin property:

image Position Margin

Here are examples of lists containing both string and image entries with icons to the left and right of the string:

string Image List

Similarly, add as many entries as you need for your list.

Note: If the number of list entries exceeds what can be displayed using the list widget size, a scrollbar is automatically generated for it.

Back to Top


 Set the rest of the list properties using the Object Editor. An example is shown in the accompanying image:

list_properties

Managing List Widget Schemes

Schemes control the look and feel of a widget.

Note: To learn more about Schemes, how to add a new scheme, and apply it to the widget, refer to this link.

To learn how to set the scheme for a list, click on the button next to the Scheme Property editor of the Object Editor.

LSchemeHelper

This launches the List Scheme Helper window containing tips on how different sections of the scheme color table manipulate various elements of the widget.

listColorHelper

Below is an example color scheme and the resulting appearance of the list:

listColortableEx1

static list

The information from the List Scheme Helper and the example color scheme is summarized in the table below:

 list Color table Ex

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

List Properties

You can set the following properties of the list using the Object Editor:

NameThis will be used to reference the list by the application. Example- Screen0_ListWidget_Static.
Selection ModeControls how many list entries can be selected at a time - single, multiple or contiguous.
Allow EmptyAllows list to be empty.
Image PositionWhen both string and image are used for each list entry, this property decides where the image is placed with respect to the string- left, right, or behind. The effect of the setting is previewed within the MGS Harmony Composer.
Image MarginWhen both string and image are used for each list entry, this property decides how much space should be set between the string and image. The effect of the setting is previewed within the MGS Harmony Composer.
Configure ItemsUsing the Configure button, the required number of initial list entries can be added. Optionally, a string value and image can be assigned for each entry. The effect of the setting is previewed within the MGS Harmony Composer.
Selection ChangedThis will generate an event when the selected list item is changed.

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

Back to Top

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

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

Object Editor

For the list widget with the properties shown in the figure above, MCC will automatically generate the following lines of code in  src\config\default\gfx\legato\generated\screen\le_gen_screen_Screen0.c:

  • A new list widget is created by the variable name Screen0_ListWidget_Static:

Screen0_ListWidget_Static = leListWidget_New();

  • Its position is set to pixel location 20x60:

Screen0_ListWidget_Static->fn->setPosition(Screen0_ListWidget_Static, 20, 60);

  • The size is set to have a width of 238 pixels and height of 110 :

Screen0_ListWidget_Static->fn->setSize(Screen0_ListWidget_Static, 238, 110);

  • If you do not want the widget to be visible by default and un-check the visible property in the Object Editor, the following code is added:

Screen0_ListWidget_Static->fn->setVisible(Screen0_ListWidget_Static, LE_FALSE);

  • If the scheme is changed from default to custom scheme, the following code is added:

Screen0_ListWidget_Static->fn->setScheme(Screen0_ListWidget_Static, &RedScheme);

  • If list entries are added using Configure Items property, the following code is added for each entry:

Screen0_ListWidget_Static->fn->appendItem(Screen0_ListWidget_Static);

  • If strings are added to each entry through Configure Items property,  the following code is added for each entry (here Stringa is the string added to index 0):

Screen0_ListWidget_Static->fn->setItemString(Screen0_ListWidget_Static, 0, (leString*)&string_Stringa);

  • If images are added to entry through Configure Items property,  the following code is added for each entry (here icon1 is the image added to index 0):

Screen0_ListWidget_Static->fn->setItemIcon(Screen0_ListWidget_Static, 0, &icon1);

  • If the image position is changed from left, which is the default position with respect to the string, the following code is added (here the icon is set to the right of the string):

Screen0_ListWidget_Static->fn->setIconPosition(Screen0_ListWidget_Static, LE_RELATIVE_POSITION_RIGHTOF);

  • The setSelectedItemChangedEventCallback API adds callback function when the string entry selection is changed:

Screen0_ListWidget_Static->fn->setSelectedItemChangedEventCallback(Screen0_ListWidget_Static, event_Screen0_ListWidget_Static_OnSelectionChanged);

           This callback function is implemented in the application code.

  • Finally, the list is added to the screen:

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

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 discussion related to the list widget is presented below.

  • Here is another way to add list entries using application code:
Screen0_ListWidget_Static->fn->insertItem(Screen0_ListWidget_Static, 0);

Screen0_ListWidget_Static->fn->setItemString(Screen0_ListWidget_Static, 0, (leString*)&testString1);
  • You can remove all entries from the list using removeAllItems API:

Screen0_ListWidget_Static->fn->removeAllItems(Screen0_ListWidget_Static);

  • Before displaying a list, you can deselect all entries to allow user to make a selection using deselectAll API:

Screen0_ListWidget_Dynamic->fn->deselectAll(Screen0_ListWidget_Dynamic);

  • You can enable/disable an entry of the list using setItemEnable API:

Screen0_ListWidget_Static->fn->setItemEnable(Screen0_ListWidget_Static, 0, LE_FALSE );

In the example below, entry at index 0 is disabled using setItemEnableAPI:

list with multiple entries and a scroll bar

  • You can implement a callback function to handle the list entry selection change event. In the example below, the index of the selected item is found, the list is made invisible and a flag is set for the application code to handle the event in the application task:
/* On Selection Change callback function for ListWidget_Static list widget.
 * The selected item index is noted and a flag is set to update the LabelWidget_StaticSel
 * label to the selected string.
 */

void event_Screen0_ListWidget_Static_OnSelectionChanged(leListWidget* wgt, uint32_t idx, leBool selected)
{        
    selitem = Screen0_ListWidget_Static->fn->getFirstSelectedItem(Screen0_ListWidget_Static);   
    Screen0_ListWidget_Static->fn->setVisible(Screen0_ListWidget_Static, LE_FALSE);
    stringChanged = true;
}

Handling Scrollbar

As mentioned before, if the number of list entries exceed what can be displayed using the list widget size, a scrollbar is automatically generated for it.

  • You can set the scrollbar thumb height using the setExtentValue API. Two options are explored below:

Option 1: You can get the maximum value of the scrollbar and divide this by a factor:

lcount = Screen0_ListWidget_Dynamic->scrollbar->fn->getMaximumValue(Screen0_ListWidget_Dynamic->scrollbar);
Screen0_ListWidget_Dynamic->scrollbar->fn->setExtentValue(Screen0_ListWidget_Dynamic->scrollbar, lcount/LIST_SCROLLBAR_FACTOR );

Example of scrollbar with a factor of 1/2 and 1/4 are shown below:

scrollbar examples with different factors

Option 2: You can get the count of items on the list and multiply this by a multiplier:

lcount = Screen0_ListWidget_Dynamic->fn->getItemCount(Screen0_ListWidget_Dynamic);
Screen0_ListWidget_Dynamic->scrollbar->fn->setExtentValue(Screen0_ListWidget_Dynamic->scrollbar, lcount* LIST_SCROLLBAR_HANDLE_MULT);
  • You can set the scrollbar thumb to be at the start of the list using as shown below:

Screen0_ListWidget_Dynamic->scrollbar->fn->setScrollValue(Screen0_ListWidget_Dynamic->scrollbar, 0);

  • You can set the scrollbar thumb to a particular location using the setScrollValue API. In the example below, the maximum value of the scrollbar is obtained using the getMaximumValue API and the scrollbar thumb is placed midway in the list using setScrollValue API:
lcount = Screen0_ListWidget_Dynamic->scrollbar->fn->getMaximumValue(Screen0_ListWidget_Dynamic->scrollbar);
Screen0_ListWidget_Dynamic->scrollbar->fn->setScrollValue( Screen0_ListWidget_Dynamic->scrollbar, lcount/2);
  • You can manually move the scrollbar forward/backward using the stepForward/stepBackward API:
/* Stepping forward */
Screen0_ListWidget_Dynamic->scrollbar->fn->stepForward(Screen0_ListWidget_Dynamic->scrollbar);
/* Stepping backward */
Screen0_ListWidget_Dynamic->scrollbar->fn->stepBackward(Screen0_ListWidget_Dynamic->scrollbar);
  • Whenever a scrollbar property is changed, for the changes to take effect, the scrollbar needs to be invalidated as shown below:

Screen0_ListWidget_Dynamic->scrollbar->fn->invalidate(Screen0_ListWidget_Dynamic->scrollbar);

  • A scrollbar can be made visible/invisible:

Screen0_ListWidget_Dynamic->scrollbar->fn->setVisible(Screen0_ListWidget_Dynamic->scrollbar, LE_FALSE);

List Widget Example Project

An example project for list widget is available on GitHub.

In this example we show:

  1. How to create a static List. All strings for this list are pre-populated and added to the list before displaying the list.
  2. How to create a Dynamic list. All strings are dynamically created using an array of leDynamicString and added to the list.
  3. An example of how a selection change can be handled in application task is shown.
  4. How to set the scrollbar thumb size, location, and setting its visibility, is shown.

MGS Harmony Web Simulator Output

Static & Dynamic List Widget Example

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

  • Clicking on the Show List1 button will display the static list. 
static char cCharBuffer[6][12] = {"TOMATO", "STRAWBERRY", "APPLE", "CHERRY", "BEETS", "POMOGRANATE" };
void populateList(void)
{
    testString1.fn->setFromCStr(&testString1, cCharBuffer[0]);
    testString2.fn->setFromCStr(&testString2, cCharBuffer[1]);
    testString3.fn->setFromCStr(&testString3, cCharBuffer[2]);
    testString4.fn->setFromCStr(&testString4, cCharBuffer[3]);
    testString5.fn->setFromCStr(&testString5, cCharBuffer[4]);
    testString6.fn->setFromCStr(&testString6, cCharBuffer[5]);

}

void event_Screen0_ButtonWidget_List1_OnReleased(leButtonWidget* btn)
{
    populateList();
    Screen0_ListWidget_Static->scrollbar->fn->setScrollValue(Screen0_ListWidget_Static->scrollbar, 0);
    Screen0_ListWidget_Static->fn->removeAllItems(Screen0_ListWidget_Static);
   
    Screen0_ListWidget_Static->fn->insertItem(Screen0_ListWidget_Static, 0);
    Screen0_ListWidget_Static->fn->setItemString(Screen0_ListWidget_Static, 0, (leString*)&testString1);
     [..]
    Screen0_ListWidget_Static->fn->insertItem(Screen0_ListWidget_Static, 5);
    Screen0_ListWidget_Static->fn->setItemString(Screen0_ListWidget_Static, 5, (leString*)&testString6);
    Screen0_ListWidget_Static->fn->deselectAll(Screen0_ListWidget_Static);
    Screen0_ListWidget_Static->fn->setVisible(Screen0_ListWidget_Static, LE_TRUE);
}
  • User can scroll up/down the list and on selecting an entry, the string property of the selected entry is displayed using the Screen0_LabelWidget_StaticSel label widget.  The event_Screen0_ListWidget_Static_OnSelectionChanged callback function sets a flag to indicate to the application task that the list entry is changed by the user. In this example, the flag is used to update the Screen0_LabelWidget_StaticSel label widget. 
void event_Screen0_ListWidget_Static_OnSelectionChanged(leListWidget* wgt, uint32_t idx, leBool selected)
{        
    selitem = Screen0_ListWidget_Static->fn->getFirstSelectedItem(Screen0_ListWidget_Static);   
    Screen0_ListWidget_Static->fn->setVisible(Screen0_ListWidget_Static, LE_FALSE);
    stringChanged = true;
}
void APP_Tasks ( void )
{

    [..]

       case APP_STATE_SERVICE_TASKS:
        {
           if(stringChanged)
            {
                sel_String = Screen0_ListWidget_Static->fn->getItemString(Screen0_ListWidget_Static, selitem);
                Screen0_LabelWidget_StaticSel->fn->setString(Screen0_LabelWidget_StaticSel, sel_String);
                stringChanged = false;
            }
           [..]
}
  • Clicking on the Show List2 button will display the dynamic list (Screen0_LabelWidget_DynamicSel).
void event_Screen0_ButtonWidget_List2_OnReleased(leButtonWidget* btn)
{
    Screen0_ListWidget_Dynamic->fn->deselectAll(Screen0_ListWidget_Dynamic);
    Screen0_ListWidget_Dynamic->fn->setVisible(Screen0_ListWidget_Dynamic, LE_TRUE);
    userSelShowDynList = true;
}
  • When user clicks on Add String button a dynamic string is appended to the list.
void event_Screen0_ButtonWidget_AddL2_OnReleased(leButtonWidget* btn)
{
    [..]
        lcount = Screen0_ListWidget_Dynamic->fn->getItemCount(Screen0_ListWidget_Dynamic);
       if (newItemIndex < MAX_NEW_ITEMS)
        {
           //Initialize the new string object
           newItemStr[newItemIndex] = leDynamicString_New();
            newItemStr[newItemIndex]->fn->setFont(newItemStr[newItemIndex], (leFont*)&NotoSans16);
            memset(cStrBuff, 0, sizeof(cStrBuff));
            sprintf(cStrBuff, "New Item %d", (int) newItemIndex);
            newItemStr[newItemIndex]->fn->setFromCStr(newItemStr[newItemIndex], cStrBuff);
            Screen0_ListWidget_Dynamic->fn->appendItem(Screen0_ListWidget_Dynamic);
            Screen0_ListWidget_Dynamic->fn->setItemString(Screen0_ListWidget_Dynamic, lcount, (leString*)newItemStr[newItemIndex]);

            newItemIndex++;
        }
       [..]
}
  • Clicking on Clear List2 button will delete all the entries in the list, sets the scroll position to 0 and makes both the list and the scrollbar invisible.
void event_Screen0_ButtonWidget_ClearL2_OnReleased(leButtonWidget* btn)
{
   uint32_t i;
    Screen0_ListWidget_Dynamic->fn->removeAllItems(Screen0_ListWidget_Dynamic);
   if (newItemIndex > 0)
    {
       for (i = 0; i < newItemIndex; i++)
        {
            leString_Delete((leString *) newItemStr[i]);
        }
    }
    Screen0_ListWidget_Dynamic->fn->setVisible(Screen0_ListWidget_Dynamic, LE_FALSE);
    Screen0_LabelWidget_DynamicSel->fn->setVisible(Screen0_LabelWidget_DynamicSel, LE_FALSE);
   //reset and hide the scroll bar
   Screen0_ListWidget_Dynamic->scrollbar->fn->setScrollValue(Screen0_ListWidget_Dynamic->scrollbar, 0);
    Screen0_ListWidget_Dynamic->scrollbar->fn->setVisible(Screen0_ListWidget_Dynamic->scrollbar, LE_FALSE);
    Screen0_ListWidget_Dynamic->scrollbar->fn->invalidate(Screen0_ListWidget_Dynamic->scrollbar);
    newItemIndex = 0;
}
  • The event_Screen0_ListWidget_Dynamic_OnSelectionChanged callback function sets a flag to indicate to the application task that the list entry is changed by the user. In this example, the flag is used to update the Screen0_LabelWidget_DynamicSel label widget. 
void event_Screen0_ListWidget_Dynamic_OnSelectionChanged(leListWidget* wgt, uint32_t idx, leBool selected)
{
    [..]
            dynSelItem = Screen0_ListWidget_Dynamic->fn->getFirstSelectedItem(Screen0_ListWidget_Dynamic);
            Screen0_ListWidget_Dynamic->fn->setVisible(Screen0_ListWidget_Dynamic, LE_FALSE);
            Screen0_LabelWidget_DynamicSel->fn->setVisible(Screen0_LabelWidget_DynamicSel, LE_TRUE);
            DynStringChanged = true;
   [..]
   
}

void APP_Tasks ( void )
{

    [..]
           if(DynStringChanged)
            {
                Dyn_sel_String = Screen0_ListWidget_Dynamic->fn->getItemString(Screen0_ListWidget_Dynamic, dynSelItem);
                Screen0_LabelWidget_DynamicSel->fn->setString(Screen0_LabelWidget_DynamicSel, Dyn_sel_String);
                DynStringChanged = false;
            }
           [..]
}

Back to Top

List Widget APIs Description

This section describes the APIs specific to list widget. For a description of APIs common to all widgets, refer to the link here.

setSelectionMode()

leResult setSelectionMode(leListWidget* _this,
                          leListWidget_SelectionMode mode)

Controls how many list entries can be selected at a time.

Parameters

leListWidget*_thisList widget pointer to operate on
leListWidget_SelectionModemode

Selection Mode:

LE_LIST_WIDGET_SELECTION_MODE_SINGLE

LE_LIST_WIDGET_SELECTION_MODE_MULTIPLE

LE_LIST_WIDGET_SELECTION_MODE_CONTIGUOUS

Returns LE_SUCCESS or LE_FAILURE.

getSelectionMode()

leListWidget_SelectionMode getSelectionMode(const leListWidget* _this)

Gets the selection mode for the list.

Returns LE_LIST_WIDGET_SELECTION_MODE_SINGLE or LE_LIST_WIDGET_SELECTION_MODE_MULTIPLE or LE_LIST_WIDGET_SELECTION_MODE_CONTIGUOUS

setAllowEmptySelection()

leResult setAllowEmptySelection(leListWidget* _this, leBool allow)              

Sets the property to allow an empty List.

Parameters

leListWidget*_thisList widget pointer to operate on
leBoolallow

LE_FALSE or LE_TRUE

Returns LE_SUCCESS or LE_FAILURE

getAllowEmptySelection()

leBool getAllowEmptySelection(const leListWidget* _this)

Gets the allow empty setting value for the list.

Returns LE_FALSE or LE_TRUE.

setIconPosition()

leResult setIconPosition(leListWidget* _this,
                         leRelativePosition pos)

Sets the image icon position with respect to the string.

Parameters

leListWidget*_thisList widget pointer to operate on
leRelativePosition pos

Image position:

LE_RELATIVE_POSITION_LEFTOF

LE_RELATIVE_POSITION_RIGHTOF

LE_RELATIVE_POSITION_BEHIND

Returns LE_SUCCESS or LE_FAILURE.

getIconPosition()

leRelativePosition getIconPosition(const leListWidget* _this)

Gets the image icon position.

Returns LE_RELATIVE_POSITION_LEFTOF or LE_RELATIVE_POSITION_RIGHTOF or  LE_RELATIVE_POSITION_BEHIND

setIconMargin()

leResult setIconMargin(leListWidget* _this, uint32_t mg)

Sets the space between the icon image and string for the string entry.

Parameters

leListWidget*_thisList widget pointer to operate on
uint32mgThe margin value

Returns LE_SUCCESS or LE_FAILURE.

getIconMargin()

uint32_t getIconMargin(const leListWidget* _this)

Gets the space between the icon image and string for the string entry.

Returns margin value.

getItemCount()

uint32_t getItemCount(const leListWidget* _this)

Gets the number of items in the list.

Returns item count.

appendItem()

int32_t appendItem(leListWidget* _this)

Appends an item to the list.

Returns index value of the new item added.

insertItem()

int32_t insertItem(leListWidget* _this, int32_t idx)

Inserts an item into the list.

Returns index value of the new item added.

removeItem()

leResult removeItem(leListWidget* _this, int32_t idx)

Removes an item from the list.

Parameters

leListWidget*_thisList widget pointer to operate on
uint32idxThe index of entry to be removed

Returns LE_SUCCESS or LE_FAILURE.

removeAllItems()

leResult removeAllItems(leListWidget* _this)

Removes all items from the list.

Returns LE_SUCCESS or LE_FAILURE.

setItemSelected()

leResult setItemSelected(leListWidget* _this,
                        int32_t idx,
                         leBool selected)

Sets the currently selected item.

Parameters

leListWidget*_thisList widget pointer to operate on
uint32idxThe index of entry to be selected
leBool selectedLE_FALSE or LE_TRUE

Returns LE_SUCCESS or LE_FAILURE.

getItemSelected()

leBool getItemSelected(const leListWidget* _this, int32_t idx)

Gets the state of the entry at the given index.

Returns LE_FALSE or LE_TRUE.

toggleItemSelected()

leResult toggleItemSelected(leListWidget* _this, int32_t idx)                                

Toggles the state of the item at given index.

Parameters

leListWidget*_thisList widget pointer to operate on
uint32idxThe index of entry whose state should be toggled

Returns LE_SUCCESS or LE_FAILURE.

selectAll()

leResult selectAll(leListWidget* _this)

Selects  all items in the list.

Returns LE_SUCCESS or LE_FAILURE.

deselectAll()

leResult deselectAll(leListWidget* _this)

Deselects all items in the list.

Returns LE_FALSE or LE_TRUE.

getFirstSelectedItem()

int32_t getFirstSelectedItem(const leListWidget* _this)

Gets the first selected item.

Returns selected item index.

getLastSelectedItem()

int32_t getLastSelectedItem(const leListWidget* _this)

Gets the last selected item.

Returns selected item index.

getSelectionCount()

uint32_t getSelectionCount(const leListWidget* _this)

Gets the number of selected items.

Returns number of selected items.

setItemString()

leResult setItemString(leListWidget* _this,
                      int32_t idx,
                      const leString* str)

Sets the string pointer for an item at the given index.

Parameters

leListWidget*_thisList widget pointer to operate on
uint32idxThe index of entry 
leString*strThe string pointer

Returns LE_SUCCESS or LE_FAILURE.

getItemString()

leString* getItemString(const leListWidget* _this, int32_t idx)
                            

Gets the string pointer associated with the entry at the given index.

Returns string pointer.

setItemIcon()

leResult setItemIcon(leListWidget* _this,
                    int32_t idx,
                    const leImage* img)

Sets the image pointer for an item at the given index.

Parameters

leListWidget*_thisList widget pointer to operate on
uint32idxThe index of entry 
leImage*ingThe image pointer

Returns LE_SUCCESS or LE_FAILURE.

getItemIcon()

leImage* getItemIcon(const leListWidget* _this, int32_t idx)
                         

Gets the image pointer associated with the entry at the given index.

Returns image pointer.

setItemEnable()

leResult setItemEnable(leListWidget* _this,
                       int32_t idx,
                       leBool b)

Enables/Disables the state of an entry at the given index.

Parameters

leListWidget*_thisList widget pointer to operate on
uint32idxThe index of entry 
leBool bLE_FALSE or LE_TRUE

Returns LE_SUCCESS or LE_FAILURE.

getItemEnable()

leBool getItemEnable(const leListWidget* _this, int32_t idx)
                         

Gets the state of the item, whether it is enabled or disabled, at the given index.

Returns LE_FALSE or LE_TRUE.

setSelectedItemChangedEventCallback()

leResult setSelectedItemChangedEventCallback(leListWidget* _this,                                                     
                                             leListWidget_SelectedItemChangedEvent cb);
                         

Sets the callback function to handle the event generated when selected item is changed in the list by the user.

Parameters

leListWidget*_thisList widget pointer to operate on
leListWidget_SelectedItemChangedEventcbCallback function

Returns LE_SUCCESS or LE_FAILURE.

Back to Top

Scrollbar APIs Description

This sections describes the APIs specific to the list widget scrollbar.

setOrientation()

leResult setOrientation(leScrollBarWidget* _this,
                        leOrientation align,
                        leBool swapDimensions)

Sets scroll bar orientation.

Parameters

leScrollBarWidget_thisList widget pointer to operate on
leOrientationalignOrientation value: LE_ORIENTATION_HORIZONTAL or LE_ORIENTATION_VERTICAL
leBoolswapDimensionsSwap the list width and height values when changing orientation

Returns LE_SUCCESS or LE_FAILURE.

getOrientation()

leOrientation getOrientation(const leScrollBarWidget* _this)

Gets scroll bar orientation.

Returns LE_ORIENTATION_HORIZONTAL or LE_ORIENTATION_VERTICAL.

setMaximumValue()

leResult setMaximumValue(leScrollBarWidget* _this, uint32_t val)
                             

Sets the maximum scroll value.

Parameters

leScrollBarWidget_thisList widget pointer to operate on
uint32valMaximum value for the scrollbar

Returns LE_SUCCESS or LE_FAILURE.

getMaximumValue()

uint32_t getMaximumValue(const leScrollBarWidget* _this)

Gets the maximum scroll value.

Returns maximum scroll value.

setExtentValue()

leResult setExtentValue(leScrollBarWidget* _this, uint32_t val)
                           

Sets the extent of the scrollbar covered by the thumb.  If the range of the scrollbar is 0-100 and the extent is 10, then the thumb will cover 10% of the total bar.

Parameters

leScrollBarWidget_thisList widget pointer to operate on
uint32valExtent of the scrollbar covered by the thumb

Returns LE_SUCCESS or LE_FAILURE.

getExtentValue()

uint32_t getExtentValue(const leScrollBarWidget* _this)

Gets the extent of the scrollbar covered by the thumb. 

Returns scrollbar extent value.

setScrollPercentage()

leResult setScrollPercentage(leScrollBarWidget* _this, uint32_t val)
                                 

Sets the scrollbar thumb to the required location on the scrollbar specified as a % of the total scrollbar size. If the range of the scrollbar is 0-100%, then setting the scroll percentage as 50% will set the scrollbar thumb at midway point.

Parameters

leScrollBarWidget_thisList widget pointer to operate on
uint32valScroll value

Returns LE_SUCCESS or LE_FAILURE.

getScrollPercentage()

uint32_t getScrollPercentage(const leScrollBarWidget* _this)

Gets the scroll value as a percentage.

Returns scroll value.

setScrollValue()

leResult setScrollValue(leScrollBarWidget* _this, uint32_t val)
                            

Sets the scroll value to the absolute value specified. This sets the location of the scrollbar thumb to the specified location. If the range of the scrollbar is 0-100, then setting the scroll value to 50 will set the scrollbar thumb at midway point.

Parameters

leScrollBarWidget_thisList widget pointer to operate on
uint32valScroll value

Returns LE_SUCCESS or LE_FAILURE.

getScrollValue()

uint32_t getScrollValue(const leScrollBarWidget* _this)

Gets the scroll value.

Returns scroll value.

setStepSize()

leResult setStepSize(leScrollBarWidget* _this, uint32_t val)                         

Sets the step size of the scrollbar. This setting dictates by how much the scrollbar moves.

Parameters

leScrollBarWidget_thisList widget pointer to operate on
uint32valStep Size

Returns LE_SUCCESS or LE_FAILURE.

getStepSize()

uint32_t getStepSize(const leScrollBarWidget* _this)

Gets the step size of the scrollbar.

Returns step size.

stepBackward()

leResult stepBackward(leScrollBarWidget* _this)

Moves the list in the backward direction.

Returns LE_SUCCESS or LE_FAILURE.

stepForward()

leResult stepForward(leScrollBarWidget* _this)

Moves the list in the forward direction.

Returns LE_SUCCESS or LE_FAILURE.

setValueChangedEventCallback()

leResult setValueChangedEventCallback(leScrollBarWidget* _this, leScrollBarWidget_ValueChangedEvent cb)

Sets the callback function to handle the event generated when user changes the selected list entry.

Parameters

leScrollBarWidget*_thisScrollbar to operate on
leButtonWidget_ReleasedEventcbCallback function

Returns LE_SUCCESS or LE_FAILURE.

Back to Top