Circular Slider Widget Documentation

Last modified by Microchip on 2024/08/01 12:18

Introduction

A circular slider widget is a graphical user interface component that allows you to input or select a value by rotating a knob or handle along a circular path. This type of slider is often used when there is a natural circular range of values, such as selecting a time, setting a temperature on a thermostat, adjusting volume, or choosing a color hue in a color picker.

This Circular Slider Widget document covers the following topics:

  1. Creating and customizing circular slider widget using Microchip Graphics Suite (MGS) Harmony Composer
  2. Circular slider properties
  3. Handling circular slider widget properties and events through application code
  4. Circular slider example project
  5. Application Program Interfaces (APIs) specific to circular slider 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 Circular Slider Widget

Follow these steps to add a circular slider widget to your design:

Select and drag the circular slider from the Tool Box to your screen designer workspace as shown in Figure 1:

drag Circle Slider

Figure 1: Adding circular slider widget to the design

Back to Top

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

The radius of the circular slider, the start and end angle, and the initial value for the circular slider widget can be set using the object editor. These are shown in Figure 2.

circle slider widget Properties

Figure 2: Circular slider widget properties

The outer and inner borders visibility and their thickness can be set as shown in Figure 3. If the border visibility is turned off, the widget looks as shown in Figure 4.

Inner Outer Arc properties

Figure 3: Inner and outer arc properties

arc border turned off

Figure 4: Inner and outer border visibility off

 

The active and inactive arc thickness and visibility can be set as shown in Figure 5.

Active and Inactive Arc

Figure 5: Active and inactive arc

If the Round Edges property for the Active Arc is unchecked, the circular slider active arc will look as shown in Figure 6.

RoundEdge off

Figure 6: Round edge unchecked for active arc

 

The circular slider has a button that you can maneuver to set the input value. The button visibility, radius, and thickness can be set as shown in Figure 7.

slider Button

Figure 7: Circular slider button properties

Back to Top

Managing Circular Slider Widget Schemes

Schemes control the look and feel of a widget. For the circular slider, we can set two schemes to define a unique look for the active/inactive arc and the button.

To learn more about Schemes, 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 a circular slider, click on the questionMark button next to the scheme property editor of the Object Editor.

Circle Slider Scheme helper

Figure 8: Launching circular slider widget scheme helper

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

Scheme helper

Figure 9: Circular slider scheme helper

Figure 10 shows an example color scheme and the resulting appearance of the circular slider:

scheme example

Figure 10: Circular slider arc and button schemes and their effect

The information from the circular slider scheme helper and the example color scheme is summarized in the following table:

table for arc

Table 1: Circular slider arc color table example

table for button

Table 2: Circular slider button color table example

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

Back to Top

Circular Slider Properties

You can set the following properties of the circular slider using the Object Editor.

NameThis will be used to reference the Circular Slider by the application. Example- Screen0_CircularSliderWidget_0.
RadiusRadius of the circular slider (Refer to Figure 2).
Start AngleStarting value for the circular slider (Refer to Figure 2).
Span AngleEndling value for the circular slider (Refer to Figure 2).
ValueInitial value for the circular slider (Refer to Figure 2).
Outside Border Arc VisibleSets the visibility of the outer border of the widget (Refer to Figure 3).
Outside Border Arc Thickness Sets the thickness of the outer border of the widget (Refer to Figure 3).
Inside Border Arc VisibleSets the visibility of the inner border of the widget (Refer to Figure 3).
Inside Border Arc Thickness Set the thickness of the inner border of the widget (Refer to Figure 3).
Active Arc  VisibleSets the visibility of the active region, if the widget spans less than a value of 360 (Refer to Figure 5).
Active Arc Round EdgesSets the active region Arc to have a rounded edge (Refer to Figures 5 & 6).
Active Arc ThicknessSets the thickness of the active region (Refer to Figure 5).
Inactive Arc VisibleSets the visibility of the inactive region (Refer to Figure 5).
Button VisibleSets the visibility of the circular slider button.
Button RadiusSets the radius of the circular slider button (Refer to Figure 7).
Button ThicknessSets the thickness of the border of the circular slider button (Refer to Figure 7).
Value Changed EventWill generate an event when the button is moved.
Pressed EventWill generate an event when the button is pressed.
Released EventWill generate an event when the button is released.

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

Back to Top

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

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

circle slider widget Properties

Figure 11: Circular slider properties

For the circular 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 Circular Slider widget is created by the variable name Screen0_CircularSliderWidget_0.
Screen0_CircularSliderWidget_0 = leCircularSliderWidget_New();
  • Its position is set to pixel location 227x210.
Screen0_CircularSliderWidget_0->fn->setPosition(Screen0_CircularSliderWidget_0, 227, 210);
  • The widget size is set to have a width of 276 pixels and a height of 260.
Screen0_CircularSliderWidget_0->fn->setSize(Screen0_CircularSliderWidget_0, 276, 260);
  • The widget is set to a specific color scheme.
Screen0_CircularSliderWidget_0->fn->setScheme(Screen0_CircularSliderWidget_0, &CircularSliderScheme);
  • The button of the widget is set to a unique scheme.
Screen0_CircularSliderWidget_0->fn->setArcScheme(Screen0_CircularSliderWidget_0, CIRCLE_BUTTON, &SliderButtonScheme);
  • The radius of the circular slider is set to 80 pixels.
Screen0_CircularSliderWidget_0->fn->setRadius(Screen0_CircularSliderWidget_0, 80);
  • The outer border visibility is set to false (therefore its thickness is not relevant).
Screen0_CircularSliderWidget_0->fn->setArcVisible(Screen0_CircularSliderWidget_0, OUTSIDE_CIRCLE_BORDER, LE_FALSE);
  • The inner border visibility is set to false (therefore its thickness is not relevant).
Screen0_CircularSliderWidget_0->fn->setArcVisible(Screen0_CircularSliderWidget_0, INSIDE_CIRCLE_BORDER, LE_FALSE);
  • The arc thickness is set to 32 pixels (refer to Figure 5).
Screen0_CircularSliderWidget_0->fn->setArcThickness(Screen0_CircularSliderWidget_0, ACTIVE_AREA, 32);
  • The button radius is set to 20 pixels.
Screen0_CircularSliderWidget_0->fn->setArcRadius(Screen0_CircularSliderWidget_0, CIRCLE_BUTTON, 20);
  • The button border thickness is set to 5 pixels.
Screen0_CircularSliderWidget_0->fn->setSnapDivisions(Screen0_CircularSliderWidget_0, 5);
  • The circular slider button is set to a different scheme.
Screen0_CircularSliderWidget_0->fn->setArcScheme(Screen0_CircularSliderWidget_0, CIRCLE_BUTTON, &SliderButtonScheme);
  • The setValueChangedEventCallback API adds a callback function when the button is moved. These callback functions are implemented in the application code.
Screen0_CircularSliderWidget_0->fn->setValueChangedEventCallback(Screen0_CircularSliderWidget_0, event_Screen0_CircularSliderWidget_0_OnValueChanged);
  • Finally, the circular slider is added to the screen:
root0->fn->addChild(root0, (leWidget*)Screen0_CircularSliderWidget_0);

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

Here is an example of the onValueChanged callback function that can be added to the application code (in app.c):

/* When the button on the circle slider is moved, the Screen0_LabelSliderVal
 * label displays the current value of the circle slider widget passed by the
 * val parameter */
void event_Screen0_CircularSliderWidget_0_OnValueChanged(leCircularSliderWidget* sld, int32_t val)
{
    memset(cSliderCharBuffer, 0, sizeof(cSliderCharBuffer));
    sprintf(cSliderCharBuffer, "%ld", val);
    p_SliderValstring.fn->setFromCStr(&p_SliderValstring, cSliderCharBuffer);
    Screen0_LabelSliderVal->fn->setString(Screen0_LabelSliderVal, (leString*)&p_SliderValstring);
    printf("%ld\r\n", val);
}

Back to Top

Circular Slider Widget Example Project

Refer to the Circular Slider widget example project in GitHub.

In this example, we show:

  1. How to create a circular slider widget and set its properties as mentioned in the "Circular Slider Properties" section. 
  2. How to handle an onValueChanged event for the circular slider widget. A label is updated based on the value of the circular slider widget.

Back to Top

MGS Simulator Output

Circular slider widget example

The callback function for handling the screen event when the button is moved along the active arc is defined in app.c.

The OnValueChanged function accepts a parameter called 'val', representing the widget's current value. This value is set as a string to the Screen0_LabelSliderVal label. Thus the label value changes when you move the circular slider button along the active arc.

Back to Top

Circular Slider APIs Description

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

getRadius()

uint32_t getRadius(const leCircularSliderWidget* _this)

Gets radius the radius of the circular slider widget. Refer to Figure 2.

Returns radius.

setRadius()

leResult setRadius(leCircularSliderWidget* _this, uint32_t rad)

Sets the circular slider widget radius. Refer to Figure 2.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
uint32radThe circle radius

Returns LE_SUCCESS or LE_FAILURE.

getStartAngle()

uint32_t getStartAngle(const leCircularSliderWidget* _this)

Gets the start angle. Refer to Figure 2. 

Returns start angle.

setStartAngle()

leResult setStartAngle(leCircularSliderWidget* _this, int32_t ang)

Sets the start angle. Refer to Figure 2. 

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
int32angThe start angle

Returns LE_SUCCESS or LE_FAILURE.

getSpanAngle()

int32_t getSpanAngle(const leCircularSliderWidget* _this)

Gets the span angle of the circular slider. Refer to Figure 2.

Returns span angle.

setSpanAngle()

leResult setSpanAngle(leCircularSliderWidget* _this, int32_t angle)

Sets the span angle of the circular slider. Refer to Figure 2.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
int32angleThe span angle

Returns LE_SUCCESS or LE_FAILURE.

getArcThickness()

uint32_t getArcThickness(const leCircularSliderWidget* _this, leCircularSliderWidgetArcType type)

Get the arc thickness value. Refer to Figure 5. 

Returns arc thickness.

setArcThickness()

leResult setArcThickness(leCircularSliderWidget* _this, leCircularSliderWidgetArcType type, uint32_t thck)

Sets the arc thickness value. Refer to Figure 5. 

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
uint32thckArc thickness value

Returns LE_SUCCESS or LE_FAILURE.

getArcRadius()

uint32_t getArcRadius(const leCircularSliderWidget* _this, leCircularSliderWidgetArcType type)

When the leCircularSliderWidgetArcType is set to CIRCLE_BUTTON, getArcRadius gets the radius of the circular slider button. Refer to Figure 7; else returns the radius based on the leCircularSliderWidgetArcType parameter, which could be -  OUTSIDE_CIRCLE_BORDER, INSIDE_CIRCLE_BORDER, ACTIVE_AREA, INACTIVE_AREA, CIRCLE_BUTTON.

Returns radius.

setArcRadius()

leResult setArcRadius(leCircularSliderWidget* _this, leCircularSliderWidgetArcType type, uint32_t rad)

When the leCircularSliderWidgetArcType is set to CIRCLE_BUTTON, setArcRadius sets the radius of the circular slider button. Refer to Figure 7.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
leCircularSliderWidgetArcTypetypeType (part of the circular slider widget) -  OUTSIDE_CIRCLE_BORDER,
    INSIDE_CIRCLE_BORDER,
    ACTIVE_AREA,
    INACTIVE_AREA,
    CIRCLE_BUTTON
uint32_tradRadius to be set

Returns LE_SUCCESS or LE_FAILURE.

getArcScheme()

leScheme* getArcScheme(const leCircularSliderWidget* _this, leCircularSliderWidgetArcType type)

Gets the scheme of the circular slider button if the leCircularSliderWidgetArcType is set to CIRCLE_BUTTON.

Returns scheme.

setArcScheme()

leResult setArcScheme(leCircularSliderWidget* _this,
                      leCircularSliderWidgetArcType type, const leScheme* schm)

Sets the scheme of the circular slider button if the leCircularSliderWidgetArcType is set to CIRCLE_BUTTON.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
leCircularSliderWidgetArcType typeType (part of the circular slider widget) -  OUTSIDE_CIRCLE_BORDER,
    INSIDE_CIRCLE_BORDER,
    ACTIVE_AREA,
    INACTIVE_AREA,
    CIRCLE_BUTTON
leScheme*schmScheme

Returns LE_SUCCESS or LE_FAILURE.

getArcVisible()

leBool getArcVisible(const leCircularSliderWidget* _this,
                             leCircularSliderWidgetArcType type)

Gets the visibility of the part of the circular slider widget based on the leCircularSliderWidgetArcType parameter, which could be -  OUTSIDE_CIRCLE_BORDER, INSIDE_CIRCLE_BORDER, ACTIVE_AREA, INACTIVE_AREA, CIRCLE_BUTTON.

Returns LE_TRUE or LE_FALSE.

setArcVisible()

leResult setArcVisible(leCircularSliderWidget* _this,
                              leCircularSliderWidgetArcType type,
                              leBool visible)

Sets the visibility based on the leCircularSliderWidgetArcType parameter, which could be -  OUTSIDE_CIRCLE_BORDER, INSIDE_CIRCLE_BORDER, ACTIVE_AREA, INACTIVE_AREA, CIRCLE_BUTTON.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
leCircularSliderWidgetArcType typeType (part of the circle slider widget) -  OUTSIDE_CIRCLE_BORDER,
    INSIDE_CIRCLE_BORDER,
    ACTIVE_AREA,
    INACTIVE_AREA,
    CIRCLE_BUTTON
leBoolvisibleLE_TRUE or LE_FALSE

Returns LE_SUCCESS or LE_FAILURE.

getValue()

uint32_t getValue(const leCircularSliderWidget* _this)

Gets the current value of the circular slider widget.

Returns current value.

setValue()

leResult setValue(leCircularSliderWidget* _this, uint32_t value)

Sets the current value of the circular slider widget.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
int32valueThe current value

Returns LE_SUCCESS or LE_FAILURE.

getStartValue()

uint32_t getStartValue(const leCircularSliderWidget* _this)

Gets the start value.

Returns start value.

setStartValue()

leResult setStartValue(leCircularSliderWidget* _this, uint32_t val)                            

Sets the start value.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
uint32_tvalStart value

Returns LE_SUCCESS or LE_FAILURE.

getEndValue()

uint32_t getEndValue(const leCircularSliderWidget* _this)

Gets the end value.

Returns end value.

setEndValue()

leResult setEndValue(leCircularSliderWidget* _this, uint32_t val)

Sets the end value.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
uint32_tvalEnd value

Returns LE_SUCCESS or LE_FAILURE.

getRoundEdges()

leBool getRoundEdges(const leCircularSliderWidget* _this)

Gets the rounded edge setting for the active arc.

Returns LE_TRUE or LE_FALSE.

setRoundEdges()

leResult setRoundEdges(leCircularSliderWidget* _this, leBool rnd)

Sets rounded edge setting for the active arc.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
leBoolrndLE_FALSE or LE_TRUE

Returns LE_SUCCESS or LE_FAILURE.

getStickyButton()

leBool getStickyButton(const leCircularSliderWidget* _this)

 Gets the sticky button setting.

Returns LE_TRUE or LE_FALSE.

setStickyButton()

leResult setStickyButton(leCircularSliderWidget* _this, leBool stk)

Sets the sticky button setting.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
leBoolstkLE_FALSE or LE_TRUE

Returns LE_SUCCESS or LE_FAILURE.

getSnapDivisions()

uint32_t getSnapDivisions(const leCircularSliderWidget* _this)

Gets the snap division for the widget.

Returns snap division.

setSnapDivisions()

leResult setSnapDivisions(leCircularSliderWidget* _this, uint32_t div)

Sets the snap division for the widget.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
uint32_tdivSnap division

Returns LE_SUCCESS or LE_FAILURE.

getTouchOnButtonOnly()

leBool getTouchOnButtonOnly(const leCircularSliderWidget* _this)

Gets the touch on button setting.

Returns LE_TRUE or LE_FALSE.

setTouchOnButtonOnly()

 leResult setTouchOnButtonOnly(leCircularSliderWidget* _this, leBool tch)

Sets the touch on button setting.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
leBooltchLE_FALSE or LE_TRUE

Returns LE_SUCCESS or LE_FAILURE.

getDirection()

leRotationDirection getDirection(const leCircularSliderWidget* _this)

Gets the current direction.

Returns LE_COUNTER_CLOCKWISE or LE_CLOCKWISE.

setDirection()

leResult setDirection(leCircularSliderWidget* _this, leRotationDirection dir)

Sets the current direction.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
leRotationDirectiondirLE_COUNTER_CLOCKWISE or LE_CLOCKWISE

Returns LE_SUCCESS or LE_FAILURE.

setPressedEventCallback()

leResult setPressedEventCallback(leCircularSliderWidget* _this,
                                         leCircularSliderWidget_PressedEvent cb)

Sets the pressed event callback function.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
leCircularSliderWidget_PressedEventcbCallback function

Returns LE_SUCCESS or LE_FAILURE.

setValueChangedEventCallback()

leResult setValueChangedEventCallback(leCircularSliderWidget* _this,
 leCircularSliderWidget_ValueChangedEvent cb)

Sets the value changed event callback function.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
leCircularSliderWidget_ValueChangedEventcbCallback function

Returns LE_SUCCESS or LE_FAILURE.

setReleasedEventCallback()

 leResult setReleasedEventCallback(leCircularSliderWidget* _this,
                                          leCircularSliderWidget_ReleasedEvent cb)

Sets the released event callback function.

Parameters

leCircularSliderWidget*_thisCircular Slider widget pointer to operate on
leCircularSliderWidget_ReleasededEventcbCallback function

Returns LE_SUCCESS or LE_FAILURE.

Back to Top