Slider Widget Documentation

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

Introduction

A slider widget is a graphical control element that allows users to adjust a value within a specific range by sliding a handle along a track. Sliders can be oriented horizontally or vertically and typically represent a continuous or discrete range of values. Users interact with the slider by clicking and dragging the handle or by clicking on the track to move the handle to that position. It is commonly used in Graphical User Interfaces (GUIs) to enable users to set values such as volume, brightness, or any numerical parameter that can vary within a bounded range.

This Slider Widget document covers the following topics:

Creating and customizing slider widgets using Microchip Graphics Suite (MGS) Harmony Composer.
Slider properties.
Handling slider widget properties and events through application code.
Slider widget example project.
Application Programming Interfaces (APIs) specific to the slider widget.

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 guide here.

Designing Slider Widget Using MGS Harmony Composer

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

Select and drag the slider widget from the Tool Box to your screen designer workspace as shown in the accompanying image:

To customize the slider widget, select it on the screen designer and modify its properties using the Object Editor.

Set the Slider properties [Orientation, Minimum, Maximum, Value and Grip Size] using the Object Editor. An example of this is shown in the accompanying image.

Managing Slider Widget Schemes

Schemes control the look and feel of a widget.

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

To learn how to set the Scheme for a slider widget, click on the button next to the Scheme property editor of the Object Editor.

This launches the Slider 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 Slider widget:

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

Understanding how the various segments of the color table influence the slider's appearance, assists you in selecting the appropriate colors.

Slider Properties

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

Name	This will be used to reference the Slider used by the application. Example - Screen0_SliderWidget1.
Orientation	This is used to set horizontal or vertical orientation of the slider.
Minimum	This is used to set the minimum value of the slider.
Maximum	This is used to set the maximum value of the slider.
Value	Will set the initial value of the slider when displayed.
Grip Size	This is used to modify the size of the handle displayed in this widget.
Value Changed	This will generate an event when the slider value is changed.

Widget properties specific to Slider Widget were discussed. For the properties common to all widgets, refer to the link here.

Managing Slider Widget through programming

Once the graphical design is completed using MGS Harmony Composer, MCC generates the required code for all the widgets based on the properties set in the Object Editor. To learn more about the process flow between designing a User Interface (UI) and developing application code, refer to the "Designing an Application with Microchip Graphics Suite (MGS)" page.

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

For the slider 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 slider widget is created by the name Screen0_SliderWidget1.

Screen0_SliderWidget1= leSliderWidget_New();

The position of the slider is set to the pixel location 96x105.

Screen0_SliderWidget1->fn->setPosition(Screen0_SliderWidget1, 96, 105);

The dimensions of the slider are width - 125 pixels and height - 50 pixels.

Screen0_SliderWidget1->fn->setSize(Screen0_SliderWidget1, 125, 50);

The scheme of the slider is changed from a default scheme to a custom slider scheme.

Screen0_SliderWidget1->fn->setScheme(Screen0_SliderWidget1, &SLiderScheme);

The background value of the slider widget is set to none. Hence, it will not take the color decided by its scheme.

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

The Slider is set to have no border in this example. However, you can have a line border or a beveled border.

Screen0_SliderWidget1->fn->setBorderType(Screen0_SliderWidget1, LE_WIDGET_BORDER_NONE);

The orientation of the slider is set to horizontal in this example.

Screen0_SliderWidget1->fn->setOrientation(Screen0_SliderWidget1, LE_ORIENTATION_HORIZONTAL, LE_FALSE);

The grip size of the slider is set to 20 in this example.

Screen0_SliderWidget1->fn->setGripSize(Screen0_SliderWidget1, 20);

The 'Value Changed Event' is used to attach a callback function when the slider value is altered.

Screen0_SliderWidget1->fn->setValueChangedEventCallback(Screen0_SliderWidget1, event_Screen0_SliderWidget1_OnValueChanged);

Finally, the slider widget is added to the screen.

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

The user must define the callback function in the application code.

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 slider widget is presented below.

Here is an example of the callback function that can be added to the application code (in app.c) to handle the event generated when the slider handle is moved:

/* When the slider handle is moved, the Screen0_valueLabel label
* widget displays the new value of the slider appended to the sliderStr string */
void event_Screen0_SliderWidget2_OnValueChanged(leSliderWidget* scr)
{
    sprintf(valueBuffer , "%ld", scr->fn->getValue(scr)); //valueBuffer is a global char buffer
    sliderStr.fn->setFromCStr(&sliderStr, valueBuffer); //sliderStr is a global legato String object
    Screen0_ValueLabel->fn->setString(Screen0_ValueLabel, (leString*)&sliderStr);
}

Slider Widget Example Project

An example slider widget project is available on GitHub.

In this example, we show:

How to create a slider widget.
How to handle events for the slider widget.

MGS Harmony Web Simulator Output

Simple Slider widget example

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

The above example demonstrates a pair of interdependent sliders.
Clicking along the slider bar or dragging the handle will display the updated value of the slider in the label widget located beneath the slider pairs. The OnValueChanged events for the both the sliders are implemented through the callback functions as shown below :

/* When the slider handle is moved, the Screen0_valueLabel label
* widget displays the new value of the slider appended to the sliderStr string */

leResult setValue(leSliderWidget* _this, int32_t val)

Sets the slider value.

Parameters

leSliderWidget*	_this	Slider widget pointer to operate on
uint32_t	val	Slider value

Returns LE_SUCCESS or LE_FAILURE.

step()

leResult step(leSliderWidget* _this, int32_t amount)

Steps the slider by an amount.

Parameters

leSliderWidget*	_this	Slider widget pointer to operate on
int32_t	amount	Step amount

Returns LE_SUCCESS or LE_FAILURE.

getValueChangedEventCallback()

leSliderWidget_ValueChangedEvent getValueChangedEventCallback(const leSliderWidget* _this)

Gets the value changed event callback pointer.

Parameters

leSliderWidget*

_this

Slider widget pointer to operate on

Returns the value changed event callback function.

setValueChangedEventCallback()

leResult setValueChangedEventCallback(leSliderWidget* _this, leSliderWidget_ValueChangedEvent cb)

Sets the value changed event callback pointer.

Parameters

leSliderWidget*	_this	Slider widget pointer to operate on
leSliderWidget_ValueChangedEvent	cb	Callback function

Returns LE_SUCCESS or LE_FAILURE.

Slider Widget Documentation

Introduction

Designing Slider Widget Using MGS Harmony Composer

Managing Slider Widget Schemes

Slider Properties

Managing Slider Widget through programming

Application Code

Slider Widget Example Project

MGS Harmony Web Simulator Output

Slider Widget API Documentation

getOrientation()

setOrientation()

getGripSize()

setGripSize()

getMininumValue()

setMinimumValue()

getMaximumValue()

setMaximumValue()

getPercentage()

setPercentage()

getValue()

setValue()

step()

getValueChangedEventCallback()

setValueChangedEventCallback()

Menu

On This Page

Microchip Support