List Widget Documentation
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:
- Creating and customizing list widgets using Microchip Graphics Suite (MGS) Harmony Composer.
- List properties.
- Handling list widget properties and events through application code.
- List widget example project.
- Application Program Interfaces (APIs) specific to list widgets.
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:
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:
In the Configure List Items window, click in the green + icon:
For Item 0, click on the button for String property and from the Select String window, choose the desired string:
Here is an example of list with just string entries:
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:
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:
Here are examples of lists containing both string and image entries with icons to the left and right of the string:
Set the rest of the list properties using the Object Editor. An example is shown in the accompanying image:
Managing List Widget Schemes
Schemes control the look and feel of a widget.
To learn how to set the scheme for a list, click on the ? button next to the Scheme Property editor of the Object Editor.
This launches the List Scheme Helper window containing tips on how different sections of the scheme color table manipulate various elements of the widget.
Below is an example color scheme and the resulting appearance of the list:
The information from the List Scheme Helper and the example color scheme is summarized in the table below:
List Properties
You can set the following properties of the list using the Object Editor:
| Name | This will be used to reference the list by the application. Example- Screen0_ListWidget_Static. |
| Selection Mode | Controls how many list entries can be selected at a time - single, multiple or contiguous. |
| Allow Empty | Allows list to be empty. |
| Image Position | When 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 Margin | When 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 Items | Using 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 Changed | This will generate an event when the selected list item is changed. |
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:
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->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:
- 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:
* 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:
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:
Option 2: You can get the count of items on the list and multiply this by a multiplier:
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:
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:
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:
- How to create a static List. All strings for this list are pre-populated and added to the list before displaying the list.
- How to create a Dynamic list. All strings are dynamically created using an array of leDynamicString and added to the list.
- An example of how a selection change can be handled in application task is shown.
- How to set the scrollbar thumb size, location, and setting its visibility, is shown.
MGS Harmony Web Simulator Output
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.
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.
{
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).
{
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.
{
[..]
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.
{
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.
{
[..]
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;
}
[..]
}
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()
leListWidget_SelectionMode mode)
Controls how many list entries can be selected at a time.
Parameters
| leListWidget* | _this | List widget pointer to operate on |
| leListWidget_SelectionMode | mode | 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()
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()
Sets the property to allow an empty List.
Parameters
| leListWidget* | _this | List widget pointer to operate on |
| leBool | allow | LE_FALSE or LE_TRUE |
Returns LE_SUCCESS or LE_FAILURE
getAllowEmptySelection()
Gets the allow empty setting value for the list.
Returns LE_FALSE or LE_TRUE.
setIconPosition()
leRelativePosition pos)
Sets the image icon position with respect to the string.
Parameters
| leListWidget* | _this | List 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()
Gets the image icon position.
Returns LE_RELATIVE_POSITION_LEFTOF or LE_RELATIVE_POSITION_RIGHTOF or LE_RELATIVE_POSITION_BEHIND
setIconMargin()
Sets the space between the icon image and string for the string entry.
Parameters
| leListWidget* | _this | List widget pointer to operate on |
| uint32 | mg | The margin value |
Returns LE_SUCCESS or LE_FAILURE.
getIconMargin()
Gets the space between the icon image and string for the string entry.
Returns margin value.
getItemCount()
Gets the number of items in the list.
Returns item count.
appendItem()
Appends an item to the list.
Returns index value of the new item added.
insertItem()
Inserts an item into the list.
Returns index value of the new item added.
removeItem()
Removes an item from the list.
Parameters
| leListWidget* | _this | List widget pointer to operate on |
| uint32 | idx | The index of entry to be removed |
Returns LE_SUCCESS or LE_FAILURE.
removeAllItems()
Removes all items from the list.
Returns LE_SUCCESS or LE_FAILURE.
setItemSelected()
int32_t idx,
leBool selected)
Sets the currently selected item.
Parameters
| leListWidget* | _this | List widget pointer to operate on |
| uint32 | idx | The index of entry to be selected |
| leBool | selected | LE_FALSE or LE_TRUE |
Returns LE_SUCCESS or LE_FAILURE.
getItemSelected()
Gets the state of the entry at the given index.
Returns LE_FALSE or LE_TRUE.
toggleItemSelected()
Toggles the state of the item at given index.
Parameters
| leListWidget* | _this | List widget pointer to operate on |
| uint32 | idx | The index of entry whose state should be toggled |
Returns LE_SUCCESS or LE_FAILURE.
selectAll()
Selects all items in the list.
Returns LE_SUCCESS or LE_FAILURE.
deselectAll()
Deselects all items in the list.
Returns LE_FALSE or LE_TRUE.
getFirstSelectedItem()
Gets the first selected item.
Returns selected item index.
getLastSelectedItem()
Gets the last selected item.
Returns selected item index.
getSelectionCount()
Gets the number of selected items.
Returns number of selected items.
setItemString()
int32_t idx,
const leString* str)
Sets the string pointer for an item at the given index.
Parameters
| leListWidget* | _this | List widget pointer to operate on |
| uint32 | idx | The index of entry |
| leString* | str | The string pointer |
Returns LE_SUCCESS or LE_FAILURE.
getItemString()
Gets the string pointer associated with the entry at the given index.
Returns string pointer.
setItemIcon()
int32_t idx,
const leImage* img)
Sets the image pointer for an item at the given index.
Parameters
| leListWidget* | _this | List widget pointer to operate on |
| uint32 | idx | The index of entry |
| leImage* | ing | The image pointer |
Returns LE_SUCCESS or LE_FAILURE.
getItemIcon()
Gets the image pointer associated with the entry at the given index.
Returns image pointer.
setItemEnable()
int32_t idx,
leBool b)
Enables/Disables the state of an entry at the given index.
Parameters
| leListWidget* | _this | List widget pointer to operate on |
| uint32 | idx | The index of entry |
| leBool | b | LE_FALSE or LE_TRUE |
Returns LE_SUCCESS or LE_FAILURE.
getItemEnable()
Gets the state of the item, whether it is enabled or disabled, at the given index.
Returns LE_FALSE or LE_TRUE.
setSelectedItemChangedEventCallback()
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* | _this | List widget pointer to operate on |
| leListWidget_SelectedItemChangedEvent | cb | Callback function |
Returns LE_SUCCESS or LE_FAILURE.
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 | _this | List widget pointer to operate on |
| leOrientation | align | Orientation value: LE_ORIENTATION_HORIZONTAL or LE_ORIENTATION_VERTICAL |
| leBool | swapDimensions | Swap 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 | _this | List widget pointer to operate on |
| uint32 | val | Maximum 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 | _this | List widget pointer to operate on |
| uint32 | val | Extent 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 | _this | List widget pointer to operate on |
| uint32 | val | Scroll 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 | _this | List widget pointer to operate on |
| uint32 | val | Scroll 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 | _this | List widget pointer to operate on |
| uint32 | val | Step 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()
Sets the callback function to handle the event generated when user changes the selected list entry.
Parameters
| leScrollBarWidget* | _this | Scrollbar to operate on |
| leButtonWidget_ReleasedEvent | cb | Callback function |
Returns LE_SUCCESS or LE_FAILURE.