💬 Message Box

The Message Box (msgbox) is a modal overlay used to display important information, warnings, or confirmation prompts. It automatically darkens the background and captures user focus, ensuring critical messages are not missed.

---

⚙️ Properties (Props)

The Message Box configuration is defined by the MsgBoxWidget interface. It is designed to be a self-contained dialog with a title, body, and action buttons.

Property	Type	Description
Title	string	The heading text displayed at the top of the box.
Text	string	The main message or description body.
Button Texts	string[]	An array of labels for the action buttons (e.g., ["OK", "Cancel"]).
Close Button	boolean	Adds an "X" icon in the top-right corner to dismiss the box.

---

🛠 Modal Behavior

A Message Box is "modal" by default, meaning:

• Background Dimming: The rest of the UI is covered by a semi-transparent "overlay" style.
• Focus Trap: Users cannot interact with widgets behind the box until it is dismissed.
• Auto-Layout: The box automatically adjusts its height based on the length of the text and the number of buttons provided.

---

🎨 Styling the Overlay

In the Inspector Panel, you can customize three distinct areas:

1. Main: Styles the box container (border-radius, background color, shadow).
2. Buttons: Styles the action buttons at the bottom.
3. Content: Styles the typography for the Title and the Body text.

---

⚡ Runtime API (Lua)

Message Boxes are usually created or shown dynamically via the Logic and Events system when an error or specific event occurs.

-- Update the content of an existing message box
msg_alert:set_text("Connection lost. Please check the cable.")

-- React to button clicks
-- The 'index' corresponds to the order in the 'Button Texts' array
function on_msg_click(index)
    if index == 0 then
        print("User clicked OK")
        msg_alert:close()
    else
        print("User clicked Cancel")
    end
end

-- Programmatically open the box
msg_alert:set_hidden(false)

---

UI DESIGN

Avoid using long paragraphs inside a Message Box. Keep the Title to under 5 words and the Text to under 20 words for maximum readability on small embedded screens.

---

🚀 Next Steps

• Container — Use a container if you need a fully custom pop-up layout.
• Button — Learn how to trigger a message box from a simple button click.
• Logic and Events — Learn how to pass data back to the main screen after a box is closed.