Keypad Widget Documentation

Last modified by Microchip on 2025/01/03 10:39

Introduction

The Keypad widget is an interactive interface element designed to facilitate user input through a virtual keypad, providing a seamless and intuitive method for data entry and command execution.

This widget is an essential component for applications requiring user interaction, such as password entry, numerical input, and command selection, offering a customizable and user-friendly interface.

This Keypad widget document covers the following topics:

Creating and customizing Keypad widgets using Microchip Graphics Suite (MGS) Harmony Composer.
Keypad widget properties.
Handling Keypad widget properties and changing its data through application code.
Keypad widget example project.
APIs specific to the Keypad widget.

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 Keypad Widget using MGS Harmony Composer

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

In the Graphic Composer, select and drag the Keypad from the Tool Box to your screen designer workspace as shown in the accompanying image:

Figure 1. Drag "Keypad" widget from Tool Box to your screen

To customize the keypad, select it on the screen designer or from the Screen Tree and modify its properties using the Object Editor:

Click on the Configure button next to Configure Cells property:

Figure 3. Click the Configure button to configure cell properties

In this property, every cell of the keypad can be modified. On the left-side fields, you can modify the dimensions and the number of cells, while on the right-side fields, you can add different assets to a cell, such as strings or images, depending on the cell's state - pressed or released.

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

Each cell of the keypad widget can function as a button and trigger an event whenever it is pressed or released, by checking the Key Clicked feature in the Object Editor:

Managing Keypad Widget Schemes

Schemes control the look and feel of a widget.

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 keypad, click on the ? (question mark) button next to the Scheme Property editor of the Object Editor.

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

The information about the Keypad scheme adjustments and the example color scheme are summarized in Figure 9:

Note: Understanding how the various segments of the color table influence the appearance of the list assists you in selecting the appropriate colors.

Keypad Properties

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

Name	This will be used to reference the Keypad by the application. Example - Screen0_KeypadWidget_0.
Row count	This will be used to set the number of rows for the Keypad widget.
Column Count	This will be used to set the number of columns for the Keypad widget.
Trigger Mode	This property determines whether an event is activated when a keypad cell is pressed or released.
Configure Cells	This will open the cell configuration page, where additional properties will be displayed.
String	This will insert the selected string into the designated cell.
Edit Action	This will determine what edit action is sent to the active Edit widget when the cell is triggered (such as None, Append, Set, Clear, Backspace, Accept).
Edit Value	This value will be sent to the active Edit widget if the Edit Action property is Set.
Pressed Icon	This will be used to set an image that will be displayed in the cell when the specific cell is pressed.
Released Icon	This will be used to set an image that will be displayed in the cell when the specific cell is released.
Image Position	This will set the position of the image relative to the text (such as left of, right of, behind, above, below).
Image Margin	This will set the distance between the cell text and the icon.
Key Clicked	This will set the event that is generated every time a keypad cell is triggered.

Table 1: Keypad Widget Properties

Note: Widget properties specific to Keypad widget were discussed. For the properties common to all widgets, refer to the "Base Widget Documentation" page.

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

Assume a Keypad widget is created with the following properties in MGS Composer:

For the Keypad 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 keypad widget with 3 columns and 3 rows is created by the variable name Screen0_KeyPadWidget_0:
Screen0_KeyPadWidget_0 = leKeyPadWidget_New(3, 3);
Its position is set to pixel location 298x148:
Screen0_KeyPadWidget_0->fn->setPosition(Screen0_KeyPadWidget_0, 298, 148);
If the scheme is changed from default to custom scheme, the following code is added:
Screen0_KeyPadWidget_0->fn->setScheme(Screen0_KeyPadWidget_0, &RedScheme);
Finally, the label is added to the screen:
root0->fn->addChild(root0, (leWidget*)Screen0_KeyPadWidget_0);

Application Code

The default code generated by MCC establishes the initial state of the widget. You can modify the properties or behavior of the widgets using the APIs mentioned earlier in the application code. Further discussion on application code related to the Keypad widget is provided below.

Here is an example of activating the event when a keypad cell is triggered, setting a string asset in a cell, modifying the size of the keypad widget and setting an action on a keypad cell:

Screen0_KeyPadWidget_0->fn->setKeyClickEventCallback(Screen0_KeyPadWidget_0, event_Screen0_KeyPadWidget_0_OnKeyClick);

leButtonWidget* cell_0_0 = Screen0_KeyPadWidget_0->fn->getCellButton(Screen0_KeyPadWidget_0, 0, 0);

cell_0_0->fn->setString(cell_0_0, (leString*)&string_No1);

Screen0_KeyPadWidget_0->fn->setSize(Screen0_KeyPadWidget_0, 280, 221);

leButtonWidget* cell_0_1 = Screen0_KeyPadWidget_0->fn->getCellButton(Screen0_KeyPadWidget_0, 0, 1);

Screen0_KeyPadWidget_0->fn->setKeyAction(Screen0_KeyPadWidget_0, 0, 1, LE_KEYPAD_CELL_ACTION_CLEAR);

Keypad Widget Example Project

An example project for the Keypad widget is provided.

In this example, we show:

How to create a Keypad widget and generate random Microchip logos on the screen.
How to insert the number of the cell in a Text Field widget by using Keypad's actions.
How to create a Tic-Tac-Toe game using the Keypad widget.

MGS Simulator Output

Draw Surface Example

Each keypad cell is capable of generating an event upon activation. The callback functions responsible for handling the Key Clicked event are declared in le_gen_screen_Logo_Screen.h and implemented in the app_scrn_logo.c file. This event callback subsequently invokes the randLogoPosition(cell) function, which randomizes the visibility of logos when a cell is pressed.

Key Clicked Event Callback

void event_Logo_Screen_KeyPadWidget_OnKeyClick(leKeyPadWidget* wgt, leButtonWidget* cell, uint32_t row, uint32_t col)
{
randLogoPosition(cell);
}

In the randLogoPosition() function, the application determines which cell has been selected to ascertain the required number of logos to display, and then makes that number of logos visible

void randLogoPosition(leButtonWidget* cell)
{
   uint8_t randPosition[NUMBER_OF_LOGOS_CELLS - 1];
   uint8_t pressedCellNr;

    setLogosOff();

   // Check which Cell was pressed
   for(int i = 0; i < NUMBER_OF_LOGOS_CELLS; i++)
    {
       if(cell == LogoKeypadButton[i])
        {
            pressedCellNr = i + 1;
           break;
        }
    }

   // if button 6 was pressed, then show all logos
   if(pressedCellNr == NUMBER_OF_LOGOS_CELLS)
    {
        setLogosOn();
    }
   else
    {
       for(int j = 0; j < pressedCellNr; j++)
        {
           bool randOk = false;
           while (randOk == false)
            {
                randPosition[j] = rand() % NUMBER_OF_LOGOS_CELLS;
                randOk = true;
               // Check if the logo was already selected
               for(int k = 0; k < j; k++)
                {
                   if(randPosition[j] == randPosition[k])
                    {
                        randOk = false;
                    }
                }
            }
        }

       for (int j = 0; j < pressedCellNr; j++)
        {
            LogoImage[randPosition[j]]->fn->setVisible(LogoImage[randPosition[j]], LE_TRUE);
        }
    }
}

The user can insert the number of a cell into a designated text box next to the Pressed Key Label. To do that, you need to click on the textbox, which is a Text Field widget, to bring focus on it. To achieve this functionality, add the Text Field widget and the Keypad widget. Each cell of the keypad must have the Edit Action field set to Set to ensure that the action is transmitted to the active Edit widget when the cell is activated.

Figure 11. Edit Action Field in the Configure KeyPad Menu

The complete code can be found in le_gen_screen_Logo_Screen.c file for the text field and keypad widgets declarations and in the app_scrn_logo.c file for the random logo generator.

Logo_Screen_TextFieldWidget = leTextFieldWidget_New();

Logo_Screen_KeyPadWidget = leKeyPadWidget_New(3, 2);

Logo_Screen_KeyPadWidget->fn->setKeyPadActionTrigger(Logo_Screen_KeyPadWidget, LE_KEYPAD_TRIGGER_KEYPRESSED);
Logo_Screen_KeyPadWidget->fn->setKeyAction(Logo_Screen_KeyPadWidget, 0, 0, LE_KEYPAD_CELL_ACTION_SET);
Logo_Screen_KeyPadWidget->fn->setKeyValue(Logo_Screen_KeyPadWidget, 0, 0, (leString*)&string_No1);

for (int j = 0; j < pressedCellNr; j++)
        {
            LogoImage[randPosition[j]]->fn->setVisible(LogoImage[randPosition[j]], LE_TRUE);
        }

By pressing the ButtonWidget_TicTacToe Button widget, the user can navigate to the Tic-Tac-Toe game screen. This button triggers an event, which is implemented in the app_scrn_logo.c file. To facilitate screen transitions, the legato_showScreen() function must be invoked. Each screen has an OnShow event implemented, which initializes various functionalities whenever the screen is changed. Once the ButtonWidget_TicTacToe is pressed and the screen is changed, the respective functions for the widgets found in the new screen will be found in app_scrn_game.c.

Logo_Screen_ButtonWidget_TicTacToe = leButtonWidget_New();
Logo_Screen_ButtonWidget_TicTacToe->fn->setPressedEventCallback(Logo_Screen_ButtonWidget_TicTacToe, event_Logo_Screen_ButtonWidget_TicTacToe_OnPressed);

void event_Logo_Screen_ButtonWidget_TicTacToe_OnPressed(leButtonWidget* btn)
{
    legato_showScreen(screenID_Game_Screen);
}

void Game_Screen_OnShow(void)
{
    Game_SetWidgetMargins();
    Game_VariablesInitialize();
    setGameKeypadButtons();
}

Upon navigating to the Game_Screen, the user will encounter two buttons, one label, and a new keypad. Pressing the ButtonWidget_Logo will generate an event that returns the user to the initial screen, featuring the random logo generation demo. The second button, labeled ButtonWidget_Game_Rst, will reinitialize the screen, allowing the game to be restarted and played anew. Regarding the Keypad widget functionality, each cell press generates an event that inserts the respective player's symbol, either 'X' or 'O', into the cell. The LabelWidget_Player displays the name of the next player whose turn it is to make a move in the game

Game_Screen_ButtonWidget_Logo = leButtonWidget_New();

Game_Screen_ButtonWidget_Game_Rst = leButtonWidget_New();

Game_Screen_LabelWidget_Player = leLabelWidget_New();

Game_Screen_KeyPadWidget = leKeyPadWidget_New(3, 3);

void event_Game_Screen_ButtonWidget_Logo_OnPressed(leButtonWidget* btn)
{
    legato_showScreen(screenID_Logo_Screen);
}

void event_Game_Screen_ButtonWidget_Game_Rst_OnPressed(leButtonWidget* btn)
{
    Game_Screen_LabelWidget_Winner->fn->setVisible(Game_Screen_LabelWidget_Winner, LE_FALSE);
    Game_VariablesInitialize();
}

void event_Game_Screen_KeyPadWidget_OnKeyClick(leKeyPadWidget* wgt, leButtonWidget* cell, uint32_t row, uint32_t col)
{
    TicTacToeGame(cell, row, col);
}

The TicTacToeGame(cell, row, col) function determines which cell was selected and checks if it has been previously pressed. If the cell is unpressed, it records the cell number, updates the cell with 'X' or 'O', and updates the Label widget with the next player's name. The setPositionsMatrix(oldPlayerState, row, col) function stores the current state of the keypad, and the checkWinningPositions() function subsequently verifies if there is a winning player.

Keypad Widget APIs Description

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

setCellArraySize()

leResult setCellArraySize(leKeyPadWidget* _this, uint32_t rows, uint32_t cols)
Sets the size of the keypad.

Parameters

leKeyPadWidget*	_this	Keypad widget pointer to operate on
uint32_t	rows	Number of rows
uint32_t	cols	Number of columns

Returns LE_SUCCESS or LE_FAILURE.

getKeyPadActionTrigger()

leKeyPadActionTrigger getKeyPadActionTrigger(const leKeyPadWidget* _this)
Gets the keypad action trigger.

Parameters

const leKeyPadWidget*

_this

Keypad widget pointer to operate on

Returns the trigger action.

setKeyPadActionTrigger()

leResult setKeyPadActionTrigger(leKeyPadWidget* _this, leKeyPadActionTrigger trigger)
Sets the keypad trigger action.

Parameters

leKeyPadWidget*	_this	Keypad widget pointer to operate on
leKeyPadActionTrigger	trigger	The trigger action (LE_KEYPAD_TRIGGER_KEYRELEASED, LE_KEYPAD_TRIGGER_KEYPRESSED)

Returns LE_SUCCESS.

getKeyClickEventCallback()

leKeyPadWidget_KeyClickEvent getKeyClickEventCallback(const leKeyPadWidget* _this)
Gets the key click event callback.

Parameters

const leKeyPadWidget*

_this

Keypad widget pointer to operate on

Returns the callback pointer.

setKeyClickEventCallback()

leResult setKeyClickEventCallback(leKeyPadWidget* _this, leKeyPadWidget_KeyClickEvent cb)
Sets the key click event callback.

Parameters

leKeyPadWidget*	_this	Keypad widget pointer to operate on
leKeyPadWidget_KeyClickEvent	cb	The callback pointer

Returns LE_SUCCESS.

setKeyVisible()

leResult setKeyVisible(leKeyPadWidget* _this, uint32_t row, uint32_t col, leBool enabled)
Sets the enabled state of a key.

Parameters

leKeyPadWidget*	_this	Keypad widget pointer to operate on
uint32_t	row	The row index
uint32_t	col	The column index
leBool	enabled	LE_FALSE or LE_TRUE

Returns the result of the operation.

getKeyAction()

leKeyPadCellAction getKeyAction(const leKeyPadWidget* _this, uint32_t row, uint32_t col)
Gets the key action setting.

Parameters

const leKeyPadWidget*	_this	Keypad widget pointer to operate on
uint32_t	row	The row index
uint32_t	col	The column index

Returns the cell action value.

setKeyAction()

leResult setKeyAction(leKeyPadWidget* _this, uint32_t row, uint32_t col, leKeyPadCellAction action)
Sets the key action setting.

Parameters

leKeyPadWidget*	_this	Keypad widget pointer to operate on
uint32_t	row	The row index
uint32_t	col	The column index
leKeyPadCellAction	action	The cell action value

Returns LE_SUCCESS or LE_FAILURE.

getKeyValue()

leString* getKeyValue(const leKeyPadWidget* _this, uint32_t row, uint32_t col)
Gets the key value.

Parameters

const leKeyPadWidget*	_this	Keypad widget pointer to operate on
uint32_t	row	The row index
uint32_t	col	The column index

Returns the string pointer.

setKeyValue()

leResult setKeyValue(leKeyPadWidget* _this, uint32_t row, uint32_t col, const leString* val)
Sets the key value.

Parameters

leKeyPadWidget*	_this	Keypad widget pointer to operate on
uint32_t	row	The row index
uint32_t	col	The column index
const leString*	val	The string pointer

Returns LE_SUCCESS or LE_FAILURE.

getCellButton()

leButtonWidget* getCellButton(const leKeyPadWidget* _this, uint32_t row, uint32_t col)
Get a button widget pointer from the keypad.

Parameters

const leKeyPadWidget*	_this	Keypad widget pointer to operate on
uint32_t	row	The row index
uint32_t	col	The column index

Returns the pointer to the Button widget.

Note: To learn more about the Keypad widget, please refer to the "How-To Create a Numeric Keypad" page.

Keypad Widget Documentation

Introduction

Designing Keypad Widget using MGS Harmony Composer

Managing Keypad Widget Schemes

Keypad Properties

Managing Keypad Widget through Programming

Application Code

Keypad Widget Example Project

MGS Simulator Output

Keypad Widget APIs Description

setCellArraySize()

Parameters

getKeyPadActionTrigger()

Parameters

setKeyPadActionTrigger()

Parameters

getKeyClickEventCallback()

Parameters

setKeyClickEventCallback()

Parameters

setKeyVisible()

Parameters

getKeyAction()

Parameters

setKeyAction()

Parameters

getKeyValue()

Parameters

setKeyValue()

Parameters

getCellButton()

Parameters

Menu

On This Page

Microchip Support