Checkbox Widget Documentation
Introduction
Checkbox widgets are interactive elements within a Graphical User Interface (GUI) that enables users to control variables or Boolean values present on a touchscreen display. When activated, a checkbox widget will change the Boolean value on a given function, such as metric vs. imperial units, or a variable present such as removal/inclusion of certain data. The widget plays a crucial role in creating a more interactive and flexible environment for utilization.
The Checkbox Widget document covers:
- Creating and customizing Checkbox widgets using Microchip Graphics Suite (MGS) Harmony Composer.
- Checkbox widget Properties.
- Handling Checkbox widget properties and events through application code.
- Checkbox widget example project.
- APIs specific to Checkbox widgets.
Designing Checkbox Widgets Using MGS Harmony Composer
Follow these steps to add a Checkbox Widget to your design:
Select and drag the Checkbox from the Tool Box to your screen designer workspace as shown in the accompanying image:
To customize the checkbox, select checkbox widget from the screen design and modify its properties using the Object Editor.
To set the String property of the checkbox, click on the button beside it and from the Select String window, choose the desired string as shown in the accompanying image. Note that string must first be added to the project using the string manager:
To set the Checked/Unchecked Image property of the checkbox, click on the button beside it and from the Select Image window, choose the desired image as in the accompanying image. Note that images must first be added to the project using:
To set an event handler function when the checkbox widget is checked/unchecked, select the corresponding checkboxes as shown in the accompanying image:
Set the rest of the checkbox properties using the Object Editor. An example is shown in the accompanying image:
Managing Checkbox Widget Schemes
Schemes control the look and feel of a widget.
To learn how to set the scheme for a checkbox, click on the 
button next to the Scheme Property editor of the Object Editor.
This launches the Checkbox Scheme Helper window containing tips on how different sections of the scheme color table manipulates various elements of the widget.
The following is an example color scheme and the resulting checkbox appearance in checked and unchecked states:
Figure 8: Checkbox scheme settings
The information from the checkbox scheme helper and the example color scheme is summarized in the following table.
Table 1: Checkbox scheme color table
Checkbox Properties
You can set the following properties of the checkbox using the Object Editor:
Name | This will be used to reference the checkbox by the application. Example- Screen0_CheckboxWidget_0. | ||||||||||||
| Checkbox |
| ||||||||||||
| Events |
|
Managing Checkbox Widget Through Programming
Once the graphical design is completed using MGS Harmony Composer, MPLAB® Code Configurator (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 new checkbox widget is created with the following properties in MGS Harmony Composer.
For the Checkbox widget with the properties shown in the figure above, MCC will automatically generate the following lines of code in src\confg\default\gfx\legato\generated\screen\le_gen_screen_Screen0.c
- A new Checkbox widget is created by the variable name Screen0_CheckBox_0
Screen0_CheckBoxWidget_0 = leCheckboxWidget_New();
- Its position is set to pixel location 407x134.
Screen0_CheckBoxWidget_0->fn->setPosition(Screen0_CheckboxWidget_0, 407, 134);
- The checkbox size is set to have a width of 120 pixels and a height of 20.
Screen0_CheckBoxWidget_0->fn->setSize(Screen0_Checkbox_0, 120, 20);
- Its background value is set to fill which gives it its gray color. The background can be set to blank.
Screen0_CheckBoxWidget_0->fn->setBackgroundType(Screen0_Checkbox_0, LE_WIDGET_BACKGROUND_FILL);
- The checkbox is set to have a bevel border in this example. However, you can have a line border or no border.
Screen0_CheckBoxWidget_0->fn->setBorderType(Screen0_Checkbox_0, LE_WIDGET_BORDER_BEVEL);
- If you selected the checked/unchecked checkbox event in the MGS Harmony Composer Object Editor, then the following code is added, else, it is skipped.
Screen0_CheckBoxWidget_0->fn->setChecked(Screen0_Checkbox_0, LE_TRUE);
- If you set a string value to the checkbox in the MGS Harmony Composer Object Editor, then the following code is added, otherwise, it is skipped.
Screen0_CheckBoxWidget_0->fn->setString(Screen0_Checkbox_0, (leString*)&String_1);
- If you set a string and image property for the checkbox, 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_CheckBoxWidget_0->fn->setImagePosition(Screen0_Checkbox_Toggle, LE_RELATIVE_POSITION_LEFTOF);
Using "LE_RELATIVE_POSITION_RIGHTOF" sets the toggle image to the right of the string as shown: 
The setCheckedImage/setUncheckedImage API sets images from the asset manger for the checkbox checked and unchecked state.
Screen0_CheckBoxWidget_0->fn->setCheckedImage(Screen0_CheckboxWidget_0, LE_FALSE);
Screen0_CheckBoxWidget_0->fn->setUncheckedImage(Screen0_CheckboxWidget_0, LE_FALSE);
- The setCheckedEventCallback/setUncheckedEventCallback API adds callback function when the Checkbox is checked or unchecked. These callback functions are implemented in the application code.
Screen0_CheckBoxWidget_0>fn->setCheckedEventCallback(Screen0_CheckboxWidget_0, event_Screen0_CheckboxWidget_0_OnChecked);
Screen0_CheckBoxWidget_0->fn->setUncheckedEventCallback(Screen0_CheckboxWidget_0, event_Screen0_CheckboxWidget_0_OnUnchecked);
- Finally, the checkbox is added to the screen.
root0->fn->addChild(root0, (leWidget*)Screen0_CheckboxWidget_0);
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 checkbox widget is presented below.
Here is an example of the checked and unchecked callback functions that can be added to the application code (in app.c):
/* When the checkbox widget is in a checked state, the image widget will show the corresponding image, when
When the checkbox widget is in unchecked state, the image widget will be invisible. */
bool checkStateOrange = false;
bool checkStateBanana = false;
bool checkStateApple = false;
void event_Screen0_CheckBoxWidget_0_OnChecked(leCheckBoxWidget* btn)
{
//uncheck other checkbox
checkStateOrange = true;
Screen0_ImageWidget_0->fn->setVisible(Screen0_ImageWidget_0, true);
Screen0_CheckBoxWidget_1->fn->setChecked(Screen0_CheckBoxWidget_1, false);
Screen0_CheckBoxWidget_2->fn->setChecked(Screen0_CheckBoxWidget_2, false);
//set image
Screen0_ImageWidget_0->fn->setImage(Screen0_ImageWidget_0, &orange);
}
void event_Screen0_CheckBoxWidget_0_OnUnChecked(leCheckBoxWidget* btn)
{
checkStateOrange = false;
if(!(checkStateOrange) && !(checkStateBanana) && !(checkStateApple))
{
Screen0_ImageWidget_0->fn->setVisible(Screen0_ImageWidget_0, false);
}
}
Checkbox Widget Example Project
Refer to the CheckBox widget example project in GitHub.
In this example, we show:
- How to create an example with checkboxes and handle events for checked and unchecked states.
- How to add strings to the checkbox.
- How to ensure the design works smoothly.
MGS Simulator Output
The callback functions for handling the screen events are defined in the app.c file
- Clicking on the checkbox individually will cause a different image to appear on the ImageWidget. This is a checkbox that will cause the ImageWidget to display the image of an orange:
bool checkStateOrange = false;
bool checkStateBanana = false;
bool checkStateApple = false;
void event_Screen0_CheckboxWidget_0_OnChecked(leCheckboxWidget* btn)
{
//uncheck other checkbox
checkStateOrange = true;
Screen0_ImageWidget_0->fn->setVisible(Screen0_ImageWidget_0, true);
Screen0_CheckBoxWidget_1->fn->setChecked(Screen0_CheckBoxWidget_1, false);
Screen0_CheckBoxWidget_2->fn->setChecked(Screen0_CheckBoxWidget_2, false);
//set image
Screen0_ImageWidget_0->fn->setImage(Screen0_ImageWidget_0, &orange);
}
void event_Screen0_CheckboxWidget_0_OnUnchecked(leCheckboxWidget* btn)
{
checkStateOrange = false;
if(!(checkStateOrange) && !(checkStateBanana) && !(checkStateApple))
{
Screen0_ImageWidget_0->fn->setVisible(Screen0_ImageWidget0, false);
}
}
/* Similar setup to CheckBoxWidget_1 and CheckBoxWidget_2 */
- The boolean variables declared allow the checked state of each individual checkbox to be stored. When a checkbox is unchecked if all three boolean variables are false which corresponds to all three checkboxes being unchecked, the ImageWidget doesn't display an image provides a fluent code structure.
Checkbox Widget APIs Description
This section describes the APIs specific to the Checkbox widget. For a description of APIs common to all widgets, refer to the "Base Widget Documentation" page.
getChecked()
lebool getChecked(const leCheckBoxWidget* _this);
Gets the checked state using the widget pointer.
Parameters
| leCheckBoxWidget* | _this | The widget pointer to query |
Returns LE_TRUE if set, otherwise LE_FALSE.
setChecked()
leResult setChecked(const leCheckBoxWidget* _this, leBool toggleable);;
Sets a checkbox to be checked.
Parameters
| leCheckBoxWidget* | _this | The widget pointer to query |
Returns LE_TRUE if set, otherwise LE_FALSE.
getCheckedImage()
leImage* getcheckedImage(const THIS_TYPE* _this);
Gets the pointer to checkbox's checked image.
Returns Image pointer.
setCheckedImage()
leResult setCheckedImage(const leCheckBoxWidget* _this, leBool toggleable);
Sets the image to the checkbox's checked image.
Parameters
| leCheckBoxWidget* | _this | The widget pointer to query |
| leResult* | img | Image Pointer |
Returns LE_SUCCESS or LE_FAILURE.
getUncheckedImage()
leImage* getUncheckedImage(const THIS_TYPE* _this);
Gets the pointer to checkbox's unchecked image.
Returns Image pointer.
setUncheckedImage()
leResult setUnchecked(const leCheckBoxWidget* _this, leBool toggleable);
Sets the image to the checkbox's unchecked image.
Parameters
| leCheckBoxWidget* | _this | The widget pointer to query |
| leResult* | img | Image Pointer |
Returns LE_SUCCESS or LE_FAILURE.
getImagePosition()
leRelativePosition* getImagePosition(const THIS_TYPE* _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_BEHIND.
setImagePosition()
leResult setImagePosition(THIS_TYPE* _this, leRelativePosition pos);
Sets the position of the image relative to the text.
Parameters
| leCheckBoxWidget* | _this | The widget pointer to query |
| leRelativePosition* | pos | The relative position: LE_RELATIVE_POSITION_ABOVE LE_RELATIVE_POSITION_BELOW LE_RELATIVE_POSITION_LEFTOF LE_RELATIVE_POSITION_RIGHTOF LE_RELATIVE_POSITION_BEHIND |
Returns LE_SUCCESS or LE_FAILURE.
setImageMargin()
leResult setImageMargin(THIS_TYPE* _this, uint32_t mg);
Sets the space between the checkbox string (if set) and checkbox image. If the image position is set to "Behind", then this setting has no effect.
Parameters
| leCheckBoxWidget* | _this | The widget pointer to query |
| uint32_t | mg | The margin value |
Returns LE_SUCCESS or LE_FAILURE.
getImageMargin()
uint32_t getImageMargin(const lTHIS_TYPE* _this);
Gets the space between the Checkbox string (if set) and checkbox image.
Returns margin value.
getString()
leString* getString(const THIS_TYPE* _this);
Gets string assigned to the checkbox.
Returns string pointer.
setString()
leResult setString(THIS_TYPE* _this, const leString* str);
Sets the string associated with the checkbox.
Parameters
| leCheckBoxWidget* | _this | The widget pointer to query |
| leString* | const | Pointer to the checkbox widget string |
getCheckedEventCallback()
leCheckBoxWidget_CheckedEvent getCheckedEventCallback(const THIS_TYPE* _this);
Gets the checked event callback function.
Returns checked event callback function.
setCheckedEventCallback()
leResult setCheckedEventCallback(THIS_TYPE* _this,leCheckBoxWidget_CheckedEvent cb);
Sets a callback function for the checkbox checked event.
Parameters
| leCheckBoxWidget* | _this | The widget pointer to query |
| leCheckBoxWidget_CheckedEvent | cb | Callback function |
Returns LE_SUCCESS or LE_FAILURE.
getUncheckedEventCallback()
leCheckBoxWidget_UncheckedEvent getUncheckedEventCallback(const THIS_TYPE* _this);
Gets the unchecked event callback function.
Returns unchecked event callback function.
setUncheckedEventCallback()
leResult setUncheckedEventCallback(THIS_TYPE* _this,leCheckboxWidget_UncheckedEvent cb);
Sets a callback function for the checkbox unchecked event.
Parameters
| leCheckBoxWidget* | _this | The widget pointer to query |
| leCheckBoxWidget_UncheckedEvent | cb | Callback function |
Returns LE_SUCCESS or LE_FAILURE.