Overlays

Overlays sit above the normal layout: drawers, dialogs, modals, toast messages, and tooltips.

Controls And Services

Control/helper	Use it for	Emits events
`MuiDrawer`	Slide-in settings or side panel.	`MUI_EVENT_DRAWER_STATE`
`MuiDialog`	Modal dialog content.	`MUI_EVENT_DIALOG_RESULT`, `MUI_EVENT_CONFIRM`
`MuiModal`	Static modal service for showing dialogs.	Through contained dialog
`MuiToast`	Toast visual element.	None by default
`MuiToastService`	Static toast service.	None by default
`MuiTooltip`	Tooltip visual element.	None by default
`MuiTooltipService`	Static tooltip service.	None by default
`MuiOverlayLayer`	Root overlay host for floating UI.	None by default
`MuiAlertBanner`	Inline alert with optional action and dismiss.	`MUI_EVENT_ALERT_ACTION`, `MUI_EVENT_ALERT_DISMISSED`

Overlay Lifecycle (Dialogs, Drawers, Menus)

Several overlay types are heap-allocated and registered on MuiRoot::Overlay() when shown. They are not normal children of your page column.

Pattern	Typical API	Ownership / lifetime notes
Drawer	`Mui::Drawer()` then `drawer->Open(root)`	Create with `new` / `Mui::Drawer`. Add content as drawer children. Do not also add the same drawer to a page container. Backdrop and overlay registration happen on first `Open`.
Dialog	`new MuiDialog` then `MuiModal::Show(root, dlg, ...)`	Dialog + scrim live on the overlay layer. Prefer assigning `dlg.Id(...)` before show for event bus routing.
Quick alert	`Mui::ModalAlert(root, title, body)`	Allocates `MuiDialog`, calls `BuildOk()`, shows modally.
Confirm	`MuiModal::Confirm` or custom `SetupConfirm`	Confirm flow emits both `MUI_EVENT_DIALOG_RESULT` and `MUI_EVENT_CONFIRM` (see `MuiDialog`).
Context menu	`MuiContextMenu::Show` or `Mui::ContextMenuAt`	Menu + backdrop allocated per show. Pass `owner` and `controlId` for app-level `MUI_EVENT_MENU_ITEM` routing.
Toast / tooltip	`MuiToastService` / `MuiTooltipService`	Service reuses one overlay child; no app-level events by default.

App-level events require .Id(...) ≥ 0 on the emitting control (or explicit controlId for context menus). See Event Bus.

Event Fields

Event	Useful fields
`MUI_EVENT_DRAWER_STATE`	`Expanded()`, `Value()`
`MUI_EVENT_DIALOG_RESULT`	`Text()`
`MUI_EVENT_CONFIRM`	`Checked()`, `Value()`
`MUI_EVENT_ALERT_ACTION`	`Text()` (action button label)
`MUI_EVENT_ALERT_DISMISSED`	`Text()` (banner title)

MuiDrawer

Purpose

Slide-in side panel with full-viewport scrim. Use for settings, filters, or secondary workflows that should sit above the main UI.

Source: Controls/Overlays/Drawer.mqh.

Create It

MuiDrawer *drawer=Mui::Drawer(300.0,true);
drawer.Id(APP_DRAWER_SETTINGS);
Mui::DrawerSection((MuiContainer*)drawer,"Settings","");
drawer.Open(root);

Mui::Drawer(width, fromLeft) — heap-only; do not parent.Add(drawer).

Add children to the drawer container, then call Open(root) once when showing.

Events

Event	When it fires	Useful fields
`MUI_EVENT_DRAWER_STATE`	`Open` when becoming visible; `Close` when was visible	`ControlId()`, `Expanded()` (true = open), `Value()` (1 open / 0 closed)

Text() is not set on drawer state events.

Common Setters

Setter	Purpose
`.Open(root)` / `.Close(root, fromUser)`	Show/hide on overlay; registers backdrop first time.
`.Width(logical)`, `.FromLeft(bool)`	Panel width and side.
`.IsOpen()`	Same as visible state.
`.Pad(...)`, `.Radius(...)`	Inner chrome.
`.Id(...)`	Event bus ID.
`.SetStateChangedHandler(...)`	Non-owned intent handler.

Notes

Overlay is modal while open (ov.Modal(true)).
Backdrop click closes via MuiDrawerCloseHandler.
Mui::ActionDrawer wires legacy action-sink handlers.

Example

if(event.EventId()==MUI_EVENT_DRAWER_STATE && event.ControlId()==APP_DRAWER_SETTINGS)
  {
   if(!event.Expanded())
      PersistSettings();
  }

Drawer, dialogs, and menus guide

MuiDialog

Purpose

Centered modal panel with title/body/footer patterns: informational OK dialog, custom content, or Yes/Cancel confirm.

Source: Controls/Overlays/Dialog.mqh.

Create It

Custom dialog on the event bus:

MuiDialog *dlg=new MuiDialog();
dlg.Id(APP_DLG_CONFIRM);
dlg.Title("Close panel?");
dlg.Body("Unsaved changes will be lost.");
dlg.SetupConfirm(NULL,"Yes","No");
MuiModal::Show(root,dlg,false,new MuiConfirmScrimHandler(dlg));

Informational OK:

dlg.BuildOk();
MuiModal::Show(root,dlg,false);

Quick helper (allocates dialog internally): Mui::ModalAlert(root, title, body, panelWidth).

Events

Event	When it fires	Useful fields
`MUI_EVENT_DIALOG_RESULT`	OK, Yes, Cancel, scrim/header close	`ControlId()`, `Text()` — `"ok"`, `"yes"`, or `"cancel"`
`MUI_EVENT_CONFIRM`	Confirm-mode only: Yes (`true`) or cancel path (`false`)	`ControlId()`, `Checked()`, `Value()` (1 / 0)

On Yes, confirm dialogs emit both events: Text()=="yes" plus MUI_EVENT_CONFIRM with Checked()==true.

On Cancel, scrim, Esc, or header close: Text()=="cancel" and MUI_EVENT_CONFIRM with Checked()==false when in confirm mode.

BuildOk() dismiss emits MUI_EVENT_DIALOG_RESULT with Text()=="ok" only (no MUI_EVENT_CONFIRM).

Common Setters

Setter	Purpose
`.Title(...)`, `.Body(...)`	Simple text content before `BuildOk` / `SetupConfirm`.
`.BuildOk()`	Single OK footer.
`.SetupConfirm(handler, yesText, cancelText)`	Yes/Cancel footer; `handler` may be `NULL` if using only the event bus.
`.Width(w)`, `.AutoHeight(...)`, `.Pad(...)`, `.HeaderFilled(...)`, `.ShowCloseButton(...)`, `.Icon(...)`	Layout and chrome (set before build).
`.Id(...)`	Required for `OnMuiEvent` routing.
`.EmitDialogResultIntent(resultId)` / `.EmitConfirmIntent(root, confirmed)`	Advanced manual result emission.

Notes

Allocate with new; show through MuiModal::Show.
Dialog attaches scrim via AttachShell; hides on close (overlay lifetime pattern).
CloseAsCancel standardizes cancel behaviour for Esc/scrim/header X.

Example

if(event.EventId()==MUI_EVENT_CONFIRM && event.ControlId()==APP_DLG_CONFIRM)
  {
   if(event.Checked())
      ClosePanel();
  }
else if(event.EventId()==MUI_EVENT_DIALOG_RESULT && event.ControlId()==APP_DLG_CONFIRM)
  {
   // event.Text() is "yes", "cancel", etc.
  }

MuiModal

Purpose

Static service that places a MuiDialog on the root overlay with scrim and modal focus. Not a visual control — the API surface for showing dialogs.

Source: Controls/Overlays/Dialog.mqh (MuiModal class).

Create It

MuiModal::Show(root, dlg, dismissOnScrim, scrimHandlerOverride);

Parameter	Meaning
`dismissOnScrim`	`true` = clicking dim area closes (default handler or override).
`scrimHandlerOverride`	Custom scrim click handler; confirm flow uses `MuiConfirmScrimHandler(dlg)`.

Built-in confirm:

MuiModal::Confirm(root, title, body, handler, yesText, cancelText, panelWidth);

Requires non-NULL MuiConfirmHandler (legacy callback). For event-bus-only confirms, use new MuiDialog + SetupConfirm(NULL, ...) + Show as above.

Events

Emits whatever the contained MuiDialog emits (MUI_EVENT_DIALOG_RESULT, MUI_EVENT_CONFIRM). Assign .Id(...) on the dialog before Show.

Notes

Sets overlay.Modal(true) and focuses the dialog.
Mui::Confirm / Mui::ActionConfirm are factory wrappers around MuiModal::Confirm.

MuiDialog (above)

MuiToast and MuiToastService

Purpose

Short non-modal notification overlay. MuiToast is the visual element; MuiToastService owns the singleton toast on the overlay layer.

Source: Controls/Overlays/Toast.mqh.

Create It

Prefer service helpers (no manual new):

Mui::ToastSuccess(root,"Saved");
Mui::ToastWarning(root,"Connection unstable");
Mui::ToastError(root,"Order rejected");
Mui::Toast(root,"Copied",2200);
Mui::ToastBR(root,"Done");

Lower level: MuiToastService::Show(root, text, durationMs, icon, semanticTone, corner, marginLogical).

Events

None by default. Toasts are display-only feedback.

Common API

API	Purpose
`MuiToastService::Show`	Message, duration, optional icon/semantic tone, corner.
`ShowTopLeft` / `ShowTopRight` / `ShowBottomLeft` / `ShowBottomRight`	Corner shortcuts.
`Mui::ToastMargin(logicalPx)`	Default inset from viewport edges.
`MuiToast::Text`, `.SemanticTone`, `.Show(text, durationMs)`	Direct control if you manage the instance.

Notes

Does not block interaction with the main UI (overlay not modal).
Service reuses one MuiToast child on root.Overlay().

Labels, badges, and toasts guide

MuiTooltip and MuiTooltipService

Purpose

Hover tooltip overlay. Most EAs set .Tooltip(text) on controls and rely on MuiTooltipSyncHover from the root event path.

Source: Controls/Overlays/Tooltip.mqh.

Create It

Automatic (recommended):

m_bSave.Tooltip("Save settings to disk");

Manual placement:

MuiTooltipService::ShowAt(root,"Line 1\nLine 2",cx,cy,anchorElement);
MuiTooltipService::Hide(root);

MuiTooltipService::Ensure(root) returns the shared overlay tooltip instance.

Events

None by default.

Notes

Tooltip text may contain line breaks (\n).
Pointer-anchored vs element-anchored placement is handled inside ShowAt.
Does not participate in the event bus.

Root and events

MuiOverlayLayer

Purpose

Root-owned container for all floating UI: drawers, dialogs, menus, toasts, tooltips. Painted and hit-tested after normal page content.

Source: Controls/Overlays/OverlayLayer.mqh.

Create It

You do not construct this in EA code under normal use. MuiRoot exposes it via root.Overlay().

Events

None by default.

Common API

API	Purpose
`.Modal(true/false)`	When true, only overlay children receive input.
`.IsModal()`	Current modal flag.
`.AllowMainTreeNatives(true)`	Lets main-tree `OBJ_EDIT` hosts stay usable while a menu is open (combo/dropdown case).
`.BringToFront(child)`	Raise an overlay child.
`.Add(child)`	Used internally by modal/menu/drawer helpers.

Notes

Advanced/custom overlay UIs may add children directly; most EAs use MuiModal, MuiContextMenu, MuiToastService, etc.
Hit-test walks children back-to-front.

Root and events
Native input hosts — modal overlay suppresses native edits

MuiAlertBanner

Purpose

Persistent inline alert in normal layout (not overlay). Use for validation, connection status, risk warnings, or actions that should stay visible until dismissed.

Source: Controls/Display/AlertBanner.mqh (documented here because it emits overlay-style feedback events).

Create It

MuiAlertBanner *alert=MuiCreate::Alert(parent,0,0,400,0,MUI_ALERT_WARNING,"Warning","Check inputs");
alert.Id(APP_ALERT_VALIDATION);
alert.Dismissible(true);
alert.ActionText("Details");

Events

Event	When it fires	Useful fields
`MUI_EVENT_ALERT_ACTION`	User clicks the optional action button	`ControlId()`, `Text()` (action label)
`MUI_EVENT_ALERT_DISMISSED`	User clicks dismiss	`ControlId()`, `Text()` (banner title)

Common Setters

Setter	Purpose
`.Title(...)`, `.Text(...)`	Title and body copy.
`.Tone(MuiAlertTone)`	`MUI_ALERT_INFO`, `SUCCESS`, `WARNING`, `DANGER`, `NEUTRAL`.
`.Dismissible(...)`, `.ActionText(...)`	Optional dismiss and action buttons.
`.Compact(...)`, `.ShowIcon(...)`, colour overrides	Visual tuning.
`.Id(...)`, `.Visible(...)`	Routing; banner hides itself after dismiss.

Common Reads

Getter	Purpose
`.Title()`, `.Text()`, `.Tone()`, `.Dismissible()`, `.ActionText()`	Current copy and options.

Notes

Participates in layout (unlike toast).
UserDismiss sets m_dismissed and hides the banner.

Example

if(event.EventId()==MUI_EVENT_ALERT_ACTION && event.ControlId()==APP_ALERT_VALIDATION)
  {
   ShowDetails();
  }

Labels, badges, and toasts guide
Display — other display controls (Phase 6)

Overlays

Controls And Services

Overlay Lifecycle (Dialogs, Drawers, Menus)

Event Fields

MuiDrawer

Purpose

Create It

Events

Common Setters

Notes

Example

Related

MuiDialog

Purpose

Create It

Events

Common Setters

Notes

Example

Related

MuiModal

Purpose

Create It

Events

Notes

Related

MuiToast and MuiToastService

Purpose

Create It

Events

Common API

Notes

Related

MuiTooltip and MuiTooltipService

Purpose

Create It

Events

Notes

Related

MuiOverlayLayer

Purpose

Create It

Events

Common API

Notes

Related

MuiAlertBanner

Purpose

Create It

Events

Common Setters

Common Reads

Notes

Example

Related

Related Pages