Slider Widget Documentation

Last modified by Microchip on 2024/03/29 13:37

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:

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

Drag "Slider" widget from Tool Box to your screen

Back to Top


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.

Select Slider Widget and modify it's properties

Back to Top

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

Press the question mark to see detailed information about the effect of schemes on slider widget

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

Slider scheme helper

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

Slider scheme example

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

Slider scheme helper table

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

Back to Top

Slider Properties

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

NameThis will be used to reference the Slider used by the application. Example - Screen0_SliderWidget1.
OrientationThis is used to set horizontal or vertical orientation of the slider.
MinimumThis is used to set the minimum value of the slider.
MaximumThis is used to set the maximum value of the slider.
ValueWill set the initial value of the slider when displayed.
Grip SizeThis is used to modify the size of the handle displayed in this widget.
Value ChangedThis 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.

Back to Top

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:

Slider Object Editor

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.

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

Back to Top

Slider Widget Example Project

An example slider widget project is available on GitHub.

In this example, we show:

  1. How to create a slider widget.
  2. 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 *
/

void event_Screen0_SliderWidget1_OnValueChanged(leSliderWidget* scr)
{

    //The revised value from slider1 will become the current value for slider2
    Screen0_SliderWidget2->fn->setValue(Screen0_SliderWidget2, scr->fn->getValue(scr));
    sprintf(valueBuffer , "%ld", scr->fn->getValue(scr));
    sliderStr.fn->setFromCStr(&sliderStr, valueBuffer);
    Screen0_ValueLabel->fn->setString(Screen0_ValueLabel, (leString*)&sliderStr);
}
void event_Screen0_SliderWidget2_OnValueChanged(leSliderWidget* scr)
{

    //The revised value from slider2 will become the current value for slider1
    Screen0_SliderWidget1->fn->setValue(Screen0_SliderWidget1, scr->fn->getValue(scr));
    sprintf(valueBuffer , "%ld", scr->fn->getValue(scr));
    sliderStr.fn->setFromCStr(&sliderStr, valueBuffer);
    Screen0_ValueLabel->fn->setString(Screen0_ValueLabel, (leString*)&sliderStr);
}

Slider Widget API Documentation

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

getOrientation()

leOrientation getOrientation(const leSliderWidget* _this)

Gets the slider orientation.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on

Returns LE_ORIENTATION_HORIZONTAL or LE_ORIENTATION_VERTICAL.

setOrientation()

leResult setOrientation(leSliderWidget* _this, leOrientation align, leBool swapDimensions);

Sets the slider orientation.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on

leOrientation

align

orientation value

leBool

swapDimensions

To swap the width and height values

Returns LE_SUCCESS or LE_FAILURE.

getGripSize()

uint32_t getGripSize(const leSliderWidget* _this)

Gets the grip size of the slider handle.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on

Returns the grip size value.

setGripSize()

leResult setGripSize(leSliderWidget* _this, uint32_t size)

Sets the grip size of the slider handle.

Parameters.

leSliderWidget* _thisSlider widget pointer to operate on
uint32_tsizeThe grip size value of the handle

Returns LE_SUCCESS or LE_FAILURE.

getMininumValue()

uint32_t getMininumValue(const leSliderWidget* _this)

Gets the minimum value of the slider.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on

Returns the minimum value of the slider.

setMinimumValue()

leResult setMinimumValue(const leSliderWidget* _this, uint32_t val)

Sets the minimum value of the slider.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on

uint32_t

valSlider minimum value

Returns LE_SUCCESS or LE_FAILURE.

getMaximumValue()

uint32_t getMaximumValue(const leSliderWidget* _this)

Gets the maximum value of the slider.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on

Returns the maximum value of the slider.

setMaximumValue()

leResult setMaximumValue(leSliderWidget* _this, uint32_t val)

Sets the maximum value of the slider.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on
uint32_tvalSlider maximum value

Returns LE_SUCCESS or LE_FAILURE.

getPercentage()

uint32_t getPercentage(const leSliderWidget* _this)

Gets the slider value as percentage.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on

Returns the percentage value of the slider.

setPercentage()

leResult setPercentage(leSliderWidget* _this, uint32_t val)

Sets the value using a percentage.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on
uint32_tvalpercentage value

Returns LE_SUCCESS or LE_FAILURE.

getValue()

int32_t getValue(const leSliderWidget* _this)

Gets the slider value.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on

Returns the value of the slider.

setValue()

leResult setValue(leSliderWidget* _this, int32_t val)

Sets the slider value.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on
uint32_tvalSlider value

Returns LE_SUCCESS or LE_FAILURE.

step()

leResult step(leSliderWidget* _this, int32_t amount)

Steps the slider by an amount.

Parameters

leSliderWidget* _thisSlider widget pointer to operate on
int32_tamountStep amount

Returns LE_SUCCESS or LE_FAILURE.

getValueChangedEventCallback()

leSliderWidget_ValueChangedEvent getValueChangedEventCallback(const leSliderWidget* _this)

Gets the value changed event callback pointer.

Parameters

leSliderWidget* _thisSlider 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* _thisSlider widget pointer to operate on

leSliderWidget_ValueChangedEvent

cbCallback function

Returns LE_SUCCESS or LE_FAILURE.

Back to Top