How-To: Create Dialog Boxes

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

Introduction

A dialog box (or a pop-up box) is a small window that pops up on the screen, providing users with options to choose from or requiring them to enter information. It is a common user interface element in most modern operating systems and software applications.

Dialog boxes are typically used for tasks that need specific user input, such as setting options, entering data, or confirming actions. They can contain various elements like buttons, text fields, checkboxes, radio buttons, drop-down lists, etc.

The example project shows how to create a couple of dialog boxes using a Panel Widget as the container or as a parent to the widgets inside a dialog box and demonstrates a couple of ways to hide/show the dialog box on the screen.

Microchip Graphics Suite (MGS) Example Project

Refer to the project in GitHub for the example.

MGS Harmony Web Simulator Output

The application runs as follows:

Pressing the Start Scan button will show the Scanning dialog box.

Pressing the Stop button will close the Scanning dialog box and show another dialog box Scan Stopped.

Pressing OK will hide the Stopped dialog box.

Dialog Box Example

MGS Harmony Composer Design

Here’s the design in MGS Harmony Composer:

The example shows a couple of ways to hide or show the dialog box. Refer to app_Screen.c in the example project for the source code snippets.

Scanning Dialog Box: Using the Widget setVisible Application Programming Interface (API)

This is what the Scanning dialog box looks like. This dialog box is hidden at boot and shown when the Start Scan button is touched.

The Scanning dialog box consists of the ScanningDialogBox panel widget which is used as a parent to the CancelButton (Stop) button widget and a label widget.

Tip: Widgets can be parented to another widget by dragging them in the Composer Screen Tree.

When designing in Composer, the dialog box can be hidden from view by checking the Hidden Editor Option. This enables the user to select and edit the widgets underneath the dialog box.

Hiding/Showing the Dialog Box by Setting the Widget Visible Property

The setVisible API can be used to hide or show the dialog box. In this example, the Scanning dialog box is hidden or shown by calling the setVisible widget API.

This API is called in the ScanButton button widget OnReleased event handler to show the Scanning dialog box when the Scan Button is touched.

void event_Screen0_ScanButton_OnReleased(leButtonWidget* btn)
{
//Show scanning dialog box
Screen0_ScanningDialogBox->fn->setVisible(Screen0_ScanningDialogBox, LE_TRUE);
}

This API is also called to hide the Scanning dialog box when the Stop or Cancel button is touched.

void event_Screen0_CancelButton_OnReleased(leButtonWidget* btn)
{
   //Hide scanning dialog box
   Screen0_ScanningDialogBox->fn->setVisible(Screen0_ScanningDialogBox, LE_FALSE);
   //Show Stopped Dialog Box
   Screen0_StoppedDialogBox->fn->setX(Screen0_StoppedDialogBox, 128);
}

Stopped Dialog Box: Using the Widget Position

This is what the Stopped dialog box looks like. This dialog box is hidden at the boot and shown when the Stop button in the Scanning dialog box is touched.

The Stopped dialog box consists of the StoppedDialogBox panel widget which is used as a parent to the OkButton button widget and a label widget.

Stopped Dialog Box Widget in Screen Tree

Using a panel widget as a parent or container to the elements of the dialog box lets the application hide and show the dialog box by just hiding or showing the parent panel widget. This eliminates the need for managing the individual widgets in the dialog box, as the MGS library will hide and show the child widgets with the parent.

Hiding/Showing the Dialog Box by Setting the Widget Position

A widget that is positioned outside the frame is not drawn or shown on the screen. Thus, by setting the parent panel widget position in or out of the frame, the dialog box can be hidden or shown on the screen.

This method is used for the Stopped dialog box.

To show the dialog box, its X position is set to 128, which places the panel inside the frame. This is done by calling the setX widget API when the CancelButton button widget is touched.

To hide the dialog box, its X position is set to 480, which is outside the frame width. This is done by calling the setX widget API when the OkButton button widget is touched.

void event_Screen0_OkButton_OnReleased(leButtonWidget* btn)
{
//Hide Stopped Dialog Box
Screen0_StoppedDialogBox->fn->setX(Screen0_StoppedDialogBox, 480);
}

In the same manner, the setY or setPosition widget APIs can also be used to hide or show the dialog box.

The setVisible and setX APIs are called in the screen onShow() event callback function to hide the dialog boxes when the screen is first shown.

void Screen0_OnShow(void)
{
   //Hide the dialog boxes when screen is first shown
   Screen0_ScanningDialogBox->fn->setVisible(Screen0_ScanningDialogBox, LE_FALSE);
    Screen0_StoppedDialogBox->fn->setX(Screen0_StoppedDialogBox, 480);
}

Note that the dialog box will obscure any widget that overlaps with the dialog box area. This means that those widgets that are fully obscured will not receive touch events.

On the other hand, any widget that is not covered by the dialog box may still receive touch inputs. This may result in unintended behavior if the user touches these 'un-covered' widgets.

To prevent these widgets from receiving touch input, use the setEnabled API to disable the widgets when the dialog box is shown, and enable the widgets when the dialog box is hidden.

Choosing the Best Method

Either method works for hiding/showing a dialog box. The following table shows the advantages and disadvantages of each method that should be considered based on the application.

Method	Advantages	Disadvantages
Set Visible property	The dialog box is already in position at design time	The dialog box may obscure the frame in Composer. Use the Hidden Editor Option to hide from view
Set Position, X/Y	Keeps the dialog box out of frame, yet still visible in Composer	Need to keep the dialog box position in the application code