How-To: Create Dialog Boxes

Last modified by Microchip on 2024/03/29 13:32

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 scan-start.PNG will show the Scanning dialog box.
  • Pressing the Stop button scan-stop.PNG will close the Scanning dialog box and show another dialog box Stopped.
  • Pressing OK Okbutton.png will hide the Stopped dialog box.
Dialog Box Example

Back to Top

MGS Harmony Composer Design

Here’s the design in MGS Harmony Composer:

MGS Composer Design

MGS Composer Design

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.

Back to Top

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.

Scanning Dialog Box Preview

Scanning Dialog Box Preview

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.

How to parent widgets

Parenting Widgets

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.

Editor Options for Hiding Widgets

Editor Options for Hiding Widgets

Back to Top

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);
}

Back to Top

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.

Scan Stopped Dialog Box Preview

Scan Stopped Dialog Box Preview

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

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.

Back to Top

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.

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);
}

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.

Back to Top

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.

MethodAdvantagesDisadvantages
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

Back to Top