Button Widget Documentation

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

Contents

Introduction

Button widgets are interactive elements within a Graphical User Interface (GUI) that enable users to execute specific actions on a touchscreen display. When activated, button widgets typically carry out a set function or command, such as sending information, changing screens, or altering settings. They play a crucial role in creating an intuitive user experience by providing straightforward and accessible controls for interacting with an application.

This Button Widget document covers the following topics:

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

Before following this tutorial, 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 Button Widget Using MGS Harmony Composer

Follow these steps to add a button widget to your design:

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

Button from the Tool Box

Back to Top

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

To set the String property of the button, click on the button beside it and from the Select String window, choose the desired string as shown in the accompanying image:

Object Editor and Select String windows

To set the Pressed Image property of the button, click on the button beside it and from the Select Image window, and then choose the desired image as in the accompanying image:

Object Editor and Select String windows Pressed Image Button

Similarly, set the Released Image property of the button.

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

Back to Top

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

Object Editor Window Properties

Back to Top

Managing Button Widget Schemes

Schemes control the look and feel of a widget.

To learn more about Schemes and 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 button, click on the questionMark button next to the Scheme Property editor of the Object Editor.

Object Editor Scheme Helper

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

button Scheme Helper window  

The following is an example color scheme and the resulting button appearance in pressed and released states:

color scheme example

The information from the button scheme helper and the example color scheme is summarized in the following table.

button scheme helper and the example color scheme information

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

Back to Top

Button Properties

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

Name

This will be used to reference the button by the application. Example- Screen0_ButtonWidget_0.
ToggleableWill make the button toggleable.
StringWill add a String asset to the button. The effects of the settings is previewed within the MGS Harmony Composer.
Pressed ImageThis image is displayed when the button is in pressed state. 
Released ImageThis image is displayed when the button is in released state. The effect of the setting is previewed within the MGS Harmony Composer.
Image PositionWhen both string and image are used for the button, this property decides where the image is placed with respect to the string- left, right, behind, above or below. The effect of the setting is previewed within the MGS Harmony Composer.
Image MarginWhen both string and image are used for the button, this property decides how much space should be set between the string and the image. If the image position is set to "Behind", then the image margin has no effect. The effect of the settings is previewed within the MGS Harmony Composer.
Press OffsetControls how much the image moves between the pressed and released state to simulate the pressed action.
Pressed EventWill generate an event when the button is pressed.
Released EventWill generate an event when the button is released.

Widget properties specific to Button Widget were discussed. For the properties common to all widgets, refer to the "List of Properties" section.

Back to Top

Managing Button 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 button widget is created with the following properties in MGS Harmony Composer:

Object Editor window toggle Button Properties

For the Button 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 Button widget is created by the variable name Screen0_ButtonWidget_Toggle.

 Screen0_ButtonWidget_Toggle = leButtonWidget_New();

  • Its position is set to pixel location 550x288.

Screen0_ButtonWidget_Toggle->fn->setPosition(Screen0_ButtonWidget_Toggle, 550, 288);

  • The button size is set to have a width of 200 pixels and a height of 75.

 Screen0_ButtonWidget_Toggle->fn->setSize(Screen0_ButtonWidget_Toggle, 200, 75);

  • Its background value is set to none so that it's not filled with any color decided by its scheme. This is advisable when using an image for the button.

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

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

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

  • If you selected the Toggleable checkbox in the MGS Harmony Composer Object Editor, then the following code is added, else, it is skipped.

 Screen0_ButtonWidget_Toggle->fn->setToggleable(Screen0_ButtonWidget_Toggle, LE_TRUE);

  • If you set a string value to the button in the MGS Harmony Composer Object Editor, then the following code is added, otherwise, it is skipped.

  Screen0_ButtonWidget_Toggle->fn->setString(Screen0_ButtonWidget_Toggle, (leString*)&string_toggle);

  • If you set a string and image property for the button, then you must set the position of the image relative to the string. With the following code, the image is set behind the string:

Screen0_ButtonWidget_Toggle->fn->setImagePosition(Screen0_ButtonWidget_Toggle, LE_RELATIVE_POSITION_BEHIND);

Using "LE_RELATIVE_POSITION_BEHIND" sets the image behind the "Press Me" string as shown:

Press Me button

If you have a button with a string and icon image you can chose to set the LE_RELATIVE_POSITION_LEFTOF or LE_RELATIVE_POSITION_RIGHTOF position. Here is an example of such a button:

warm button

  • The setPressedImage/setReleasedImage API sets images from the asset manger for the button pressed and released state.

Screen0_ButtonWidget_Toggle->fn->setPressedImage(Screen0_ButtonWidget_Toggle, (leImage*)&buttonTDwn);
Screen0_ButtonWidget_Toggle->fn->setReleasedImage(Screen0_ButtonWidget_Toggle, (leImage*)&buttonT);

  • The setPressedEventCallback/setReleasedEventCallback API adds callback function when the button is pressed or released. These callback functions are implemented in the application code.

Screen0_ButtonWidget_Toggle->fn->setPressedEventCallback(Screen0_ButtonWidget_Toggle, event_Screen0_ButtonWidget_Toggle_OnPressed);
Screen0_ButtonWidget_Toggle->fn->setReleasedEventCallback(Screen0_ButtonWidget_Toggle, event_Screen0_ButtonWidget_Toggle_OnReleased);

Since this is a toggleable button, there could be a need for both pressed and released state callback function. If the button is not toggleable, you may only need a callback function for the pressed or released state.

  • Finally, the button is added to the screen.

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

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

Here is an example of the pressed and released callback functions that can be added to the application code (in app.c):

/* When the toggle button is in pressed state, the Screen0_LabelWidget_1 label
 * widget displays string_toggleOn */
void event_Screen0_ButtonWidget_Toggle_OnPressed(leButtonWidget* btn)
{
    Screen0_LabelWidget_1->fn->setString(Screen0_LabelWidget_1, (leString*)&string_toggleOn);

}
/* When the toggle button is in un-pressed state, the Screen0_LabelWidget_1 label
 * widget displays string_toggleOff */
void event_Screen0_ButtonWidget_Toggle_OnReleased(leButtonWidget* btn)
{
    Screen0_LabelWidget_1->fn->setString(Screen0_LabelWidget_1, (leString*)&string_toggleOff);
}

Back to Top

Button Widget Example Project

Refer to the Button widget example project in GitHub.

In this example, we show:

  1. How to create a regular button and a toggleable button. 
  2. How to handle event for both types of buttons. 
  3. How to add images and strings to the button. 

MGS Harmony Web Simulator Output

Simple & Toggleable Button Widget Example

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

  • Clicking on the button with string property Press Me will toggle the display of a label widget whose string property is set to "Hello World!". This is a simple button (not toggleable) and only the release event is  implemented as shown in the callback function below:
bool label0_visible=false;
void event_Screen0_ButtonWidget_0_OnReleased(leButtonWidget* btn)
{
   if(label0_visible)
    {
        Screen0_LabelWidget_0->fn->setVisible(Screen0_LabelWidget_0, LE_FALSE);
        label0_visible = false;
    }
   else
    {
        Screen0_LabelWidget_0->fn->setVisible(Screen0_LabelWidget_0, LE_TRUE);
        label0_visible = true;
    }
}
  • The second button with the string property Toggle is a toggleable button. In its On state a second label widget is displayed whose string property is set to Button Toggle On!. In its Off state, the label widget's string property is changed to Button Toggle Off!. Both pressed and released events are implemented in the callback functions as shown below:
void event_Screen0_ButtonWidget_Toggle_OnPressed(leButtonWidget* btn)
{
    Screen0_LabelWidget_1->fn->setString(Screen0_LabelWidget_1, (leString*)&string_toggleOn);
   
}
void event_Screen0_ButtonWidget_Toggle_OnReleased(leButtonWidget* btn)
{
    Screen0_LabelWidget_1->fn->setString(Screen0_LabelWidget_1, (leString*)&string_toggleOff);
}

Notice how the button image changes for the pressed state and released state for both these buttons.

Back to Top

Button Widget APIs Description

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

setToggleable()

leResult setToggleable(leButtonWidget* _this,                                
                       leBool toggleable)

Sets the togglable property of the button.

Parameters

leButtonWidget*_thisButton widget pointer to operate on
leBooltoggleableLE_FALSE or LE_TRUE

Returns LE_SUCCESS or LE_FAILURE.

getToggleable()

leBool getToggleable(const leButtonWidget* _this)

Gets the togglable property of the button.

Returns LE_FALSE or LE_TRUE.

setPressed()

leResult setPressed(leButtonWidget* _this, leBool pressed)

Sets the pressed state of the button to LE_FALSE or LE_TRUE.

Parameters

leButtonWidget*_thisButton widget pointer to operate on
leBoolpressedLE_FALSE or LE_TRUE

Returns LE_SUCCESS or LE_FAILURE.

getPressed()

Gets the pressed state of the button.

leBool getPressed(const leButtonWidget* _this)

Returns LE_FALSE or LE_TRUE.

setString()

leResult setString(leButtonWidget* _this, const leString* str)

Sets the string associated with the button.

Parameters

leButtonWidget*_thisButton widget pointer to operate on
const leString*strPointer to the button widget string 

Returns LE_SUCCESS or LE_FAILURE.

getString()

leString* getString(const leButtonWidget* _this)

Gets string assigned to the button.

Returns string pointer.

setPressedImage()

leResult setPressedImage(leButtonWidget* _this, leImage* img)

Sets the image for button pressed state.

Parameters

leButtonWidget*_thisButton widget pointer to operate on
leImage*imgImage Pointer

Returns LE_SUCCESS or LE_FAILURE.

getPressedImage()

leImage* getReleasedImage(const leButtonWidget* _this)

Gets the pointer to button pressed image.

Returns image pointer.

setReleasedImage()

leResult setReleasedImage(leButtonWidget* _this, leImage* img

Sets the image for button released state.

Parameters

leButtonWidget*_thisButton widget pointer to operate on
leImage*imgImage Pointer

Returns LE_SUCCESS or LE_FAILURE.

getReleasedImage()

leImage* getReleasedImage(const leButtonWidget* _this)

Gets the pointer to button released image.

Returns image pointer.

setImagePosition()

leResult setImagePosition(leButtonWidget* _this,
                          leRelativePosition pos)

Sets the position of the image relative to the text.

Parameters

leButtonWidget*_thisButton widget pointer to operate on
leRelativePositionpos

The relative position:

LE_RELATIVE_POSITION_LEFTOF

LE_RELATIVE_POSITION_ABOVE

LE_RELATIVE_POSITION_BELOW

LE_RELATIVE_POSITION_RIGHTOF

LE_RELATIVE_POSITION_BEHIND

Returns LE_SUCCESS or LE_FAILURE.

getImagePosition()

leRelativePosition getImagePosition(const leButtonWidget* _this)

Gets the position of the image relative to the text.

Returns LE_RELATIVE_POSITION_LEFTOF or LE_RELATIVE_POSITION_ABOVE or LE_RELATIVE_POSITION_BELOW

               or LE_RELATIVE_POSITION_RIGHTOF or LE_RELATIVE_POSITION_BEHIND.

setImageMargin()

leResult setImageMargin(leButtonWidget* _this,                            
uint32_t mg)

Sets the space between the button string (if set) and button image. If the image position is set to "Behind", then this setting has no effect.

Parameters

leButtonWidget*_thisButton widget pointer to operate on
uint32mgThe margin value

Returns LE_SUCCESS or LE_FAILURE.

getImageMargin()

uint32_t getImageMargin(const leButtonWidget* _this)

Gets the space between the button string (if set) and button image.

Returns margin value.

setPressedOffset()

leResult setPressedOffset(leButtonWidget* _this,
int32_t offs)

Sets offset value of the button which controls how much the button appears pressed on a pressed event. 

Parameters

leButtonWidget*_thisButton widget pointer to operate on
uint32offsThe offset value

Returns LE_SUCCESS or LE_FAILURE.

getPressedOffset()

int32_t getPressedOffset(const leButtonWidget* _this)

Gets the pressed offset value of the button.

Returns pressed offset value.

setPressedEventCallback()

leResult setPressedEventCallback(leButtonWidget* _this,
                                 leButtonWidget_PressedEvent cb)

Sets a callback function for the button press event.

Parameters

leButtonWidget*_thisButton widget pointer to operate on
leButtonWidget_PressedEventcbCallback function

Returns LE_SUCCESS or LE_FAILURE.

getPressedEventCallback()

leButtonWidget_PressedEvent getPressedEventCallback(const leButtonWidget* _this)

Gets the pressed event callback function.

Returns pressed event callback function.

setReleasedEventCallback()

leResult setReleasedEventCallback(leButtonWidget* _this,
                                  leButtonWidget_ReleasedEvent cb)

Sets a callback function for the button release event.

Parameters

leButtonWidget*_thisButton widget pointer to operate on
leButtonWidget_ReleasedEventcbCallback function

Returns LE_SUCCESS or LE_FAILURE.

getReleasedEventCallback()

leButtonWidget_ReleasedEvent getReleasedEventCallback(const leButtonWidget* _this)

Gets the released event callback function.

Returns released event callback function.

Back to Top