MessageBox Widget

Overview

The MessageBox widget is a modal dialog overlay with a title, body text, and OK / Cancel buttons. It blocks interaction with the underlying screen until dismissed and fires events to a callback indicating which button was pressed.

Enable

#define MGUI_WIDGET_ENABLE_MESSAGEBOX

Creation

#ifdef MGUI_WIDGET_ENABLE_MESSAGEBOX
mgui_widget_t* msgbox = mgui_allocate_widget(
    parent,
    MGUI_WIDGET_MESSAGEBOX,
    (mgui_area_t){x, y, width, height},
    MGUI_COLOR_ELEM_DARK_SLATE
);
#endif

Create once at screen init and call mgui_widget_messagebox_show() whenever it needs to appear.

API Reference

Content

mgui_widget_messagebox_set_text(msgbox, "Title", "Body message text.");

Colors

// caption bar color, OK button color, Cancel button color
mgui_widget_messagebox_set_colors(msgbox,
    MGUI_COLOR_PURPLE,
    MGUI_COLOR_EMERALD,
    MGUI_COLOR_CRIMSON);

Display

mgui_widget_messagebox_show(msgbox);

Events

static void msgbox_cb(mgui_widget_t* obj, mgui_event_t event) {
    if (event == MGUI_EVENT_OK) {
        // user pressed OK
    } else if (event == MGUI_EVENT_CANCEL) {
        // user pressed Cancel
    }
}
mgui_widget_click_handler(msgbox, msgbox_cb);

Event Constants

Event	Meaning
MGUI_EVENT_OK	User confirmed / pressed OK
MGUI_EVENT_CANCEL	User cancelled / pressed Cancel

Common Combinations

Use Case	Trigger
Delete confirmation	Danger button → show_messagebox connection
Unsaved changes warning	Screen-exit button → show_messagebox connection
Low battery alert	Timer fires → mgui_widget_messagebox_show()

---

Examples

Confirmation Dialog (Button → MessageBox)

A delete button on a light-gray screen triggers a confirmation dialog — covers creation, custom colors, the show_messagebox connection, and the response callback.

ui.json (Live Simulator)C Code

{
  "elements": [
    {
      "type": "box",
      "name": "Screen",
      "x": 0, "y": 0, "w": 320, "h": 240,
      "color": "0xC6C6C6",
      "children": [
        {
          "type": "button",
          "name": "DeleteBtn",
          "x": 0, "y": 0, "w": 140, "h": 44,
          "color": "0xEF3F2E",
          "btn_text": "Delete",
          "btn_text_color": "0xFFFFFF",
          "corner": { "radius": 6, "filled": true }
        },
        {
          "type": "messagebox",
          "name": "ConfirmMB",
          "x": 40, "y": 45, "w": 240, "h": 160,
          "color": "0xFFFFFF",
          "caption": "Confirm Delete",
          "message": "This cannot be undone.\nAre you sure?",
          "mb_colors": {
            "caption": "0xFFFFFF",
            "ok":      "0x2DA852",
            "cancel":  "0xEF3F2E"
          }
        }
      ]
    }
  ],
  "connections": [
    { "from": "DeleteBtn", "to": "ConfirmMB", "action": "show_messagebox" }
  ]
}

mgui_widget_t* screen = mgui_allocate_widget(
    NULL, MGUI_WIDGET_BOX,
    (mgui_area_t){0, 0, 320, 240},
    MGUI_COLOR_LIGHT_GRAY);

mgui_widget_t* del_btn = mgui_allocate_widget(
    screen, MGUI_WIDGET_BUTTON,
    (mgui_area_t){0, 0, 140, 44},
    MGUI_COLOR_CRIMSON);
mgui_widget_align(del_btn, MGUI_ALIGN_CENTER);
mgui_widget_button_text(del_btn, "Delete");
mgui_widget_button_text_color(del_btn, MGUI_COLOR_WHITE);
mgui_widget_button_set_radius(del_btn, 6);

#ifdef MGUI_WIDGET_ENABLE_MESSAGEBOX
mgui_widget_t* msgbox = mgui_allocate_widget(
    screen, MGUI_WIDGET_MESSAGEBOX,
    (mgui_area_t){40, 40, 240, 160},
    MGUI_COLOR_ELEM_DARK_SLATE);
mgui_widget_messagebox_set_text(msgbox,
    "Confirm Delete",
    "This cannot be undone.\nAre you sure?");
mgui_widget_messagebox_set_colors(msgbox,
    MGUI_COLOR_PURPLE,
    MGUI_COLOR_EMERALD,
    MGUI_COLOR_CRIMSON);

static void on_confirm(mgui_widget_t* obj, mgui_event_t event) {
    if (event == MGUI_EVENT_OK) {
        perform_delete();
    }
}
mgui_widget_click_handler(msgbox, on_confirm);

static void on_delete_btn(mgui_widget_t* obj, mgui_event_t event) {
    if (event == MGUI_EVENT_CLICKED) {
        mgui_widget_messagebox_show(msgbox);
    }
}
mgui_widget_click_handler(del_btn, on_delete_btn);
#endif /* MGUI_WIDGET_ENABLE_MESSAGEBOX */

---