MessageBox

Wire name messagebox

A modal dialog carrying a message and a row of answer buttons. It sizes itself to its text, cannot be resized, and reports which button closed it.

dlg=new messagebox title="Confirm" text="Save changes?" yes no cancel icon=question
sub dlg finish

---

Properties

Property	Type	Default	Meaning
abort	flag	false	Include the abort button
apply	flag	false	Include the apply button
cancel	flag	false	Include the cancel button
discard	flag	false	Include the discard button
help	flag	false	Include the help button
icon	none | information | warning | error | question	none	Icon shown beside the message
ignore	flag	false	Include the ignore button
no	flag	false	Include the no button
ok	flag	false	Include the ok button
retry	flag	false	Include the retry button
save	flag	false	Include the save button
text	string	—	Message body text
title	string	—	Dialog title bar text
yes	flag	false	Include the yes button

Plus the common properties.

Events

finish — The message box was dismissed.

Field	Type	Meaning
trinket	uint	The message box's object ID.
result	word	Which answer closed it.

It is top-level

A message box is not placed inside a window's children, and it is not a child of the window that raised it. It is built as its own top-level object, and the display adopts it the way it adopts a Window:

new messagebox title="Saved" text="Your changes are on disk." ok icon=information

It is a modal window that does not resize, so it takes neither width nor height — asking for one is an error:

new messagebox title="x" width=300
  ->  property "width" is not supported by this type

The size comes from the text and the buttons.

Buttons are flags, one per name

There is no bitfield on the wire. Each button is its own flag, written bare to include it:

new messagebox title="Confirm" text="Save changes?" yes no cancel
new messagebox title="Error" text="Could not open the file." retry ignore abort
new messagebox title="Quit" text="Save before closing?" save discard cancel

The eleven, in the order they are drawn, are ok cancel yes no retry ignore abort save discard apply help. That order is fixed: writing cancel ok lays them out OK first, the same as ok cancel. The row's arrangement is the toolkit's business, not the script's.

!name removes one, which is only useful when something earlier put it there — a template, or an earlier set:

new messagebox ok !cancel
  ->  ok alone

?name is an error rather than a third state:

new messagebox ?ok
  ->  ok: indeterminate is not meaningful for this property

A message box with no buttons is legal and cannot be answered. new messagebox title="x" builds a dialog with an empty button row that neither Return nor Escape will close — see the table below. Always name at least one.

finish and the sub that makes it arrive

Nothing is delivered until you subscribe. This is not particular to message boxes — it is how events work everywhere — but it bites hardest here, because a dialog you never hear back from looks like a dialog that is broken:

d=new messagebox title="x" ok
  ->  the user clicks OK, and nothing reaches the client

d=new messagebox title="x" ok
sub d finish
  ->  event finish trinket=<id> result=ok

result is the button's own word — ok, cancel, yes, no, and so on.

destroy does not raise finish. Closing the dialog from the client closes it silently, which is right: finish reports the user's answer, and there was not one.

Return and Escape

Both keys are always swallowed by the dialog, but what they answer depends on which buttons exist:

Key	Answers	Otherwise
Return	ok	yes, if there is no ok
Escape	cancel	no, if there is no cancel

If neither candidate is present the key does nothing at all — it is still consumed, so it does not reach anything behind the dialog:

new messagebox title="x" text="y" save discard cancel
  ->  Escape answers cancel; Return does nothing

new messagebox title="x" text="y" ok
  ->  Return answers ok; Escape does nothing

A save discard cancel dialog having no Return answer is deliberate — there is no safe default between saving and discarding. An ok-only dialog swallowing Escape is worth knowing about before a user meets it.

There is no letter shortcut. y and n are not bound; the buttons are reached with Tab and answered with Return.

Icons

icon puts a glyph beside the message and takes none information warning error question. The default is none.

new messagebox title="Delete" text="Delete 3 files?" yes no icon=question
new messagebox title="Failed" text="Disk full." ok icon=error

An unknown name is rejected rather than ignored:

new messagebox icon=nosuch
  ->  icon: unknown value "nosuch"

Match the icon to the buttons — a question with an ok-only button row is asking something the user cannot answer.

It takes no children

The body is the text property, not a subtree:

new messagebox title="x" children={ new label caption="hi" }
  ->  this type does not accept children

A dialog that needs real content — fields, a list, a form — is a Window with a Panel in it, not a message box.

The usual shapes

# Tell the user something.
new messagebox title="Saved" text="Your changes are on disk." ok icon=information

# Ask a yes/no question.
new messagebox title="Delete" text="Delete 3 files?" yes no icon=question

# Ask, and let them back out.
new messagebox title="Quit" text="Save before closing?" save discard cancel icon=warning

# Report a failure they may be able to retry.
new messagebox title="Failed" text="Could not reach the server." retry cancel icon=error

See also

Window — for a dialog with real content in it · Button · Events · Common Properties