back to Table of Contents

MessageBox$ (function)

Will display a short message to the user and wait for acknowledgment. The MessageBox will popup in its own detached window but is aware of its parent program window, hence closing the parent window will also close the MessageBox too. The message can consist of one or more short text lines incl. empty lines and/or horizontal rulers. Also one or more buttons can be defined for acknowledgment. If only one button is defined, then its keyboard shortcut will be <Enter>. If multiple buttons exist, then the first ten buttons (from left to right) get the number keys <1>, <2>, <3> ... <0> assigned as their keyboard shortcuts.

SYNTAX:

button$ = MessageBox$ (winIcon$, winTitle$, bodyText$, buttonText$)

INPUTS:

winIcon$ (STRING)

• The filename of any image to use as the MessageBox's window header icon, you don't need to specify a path for images located in the ImageClass search tree. Give an empty string to use the default icon as set in SetupScreen().

winTitle$ (STRING)

• The title for the MessageBox window, this defaults to "App Message" if an empty string is given.

bodyText$ (STRING)

• This is the message to display, use a vertical bar (|) as line separator, || will create an empty line, |~ creates a ruler instead. Line indention will be preserved and a leading dash (-) can be used to denote list items, they are replaced by a list bullet.

buttonText$ (STRING)

• The text for the button(s), use | again for button separation, the double bar || adds more space between buttons. You can also place a Image or Symbol specification right in front of each button's text using the following syntax:

{IMG imagefile clear}

imagefile

• The filename of the image to use (if it has spaces in its path/name, then enclose it in 'single' quotes). If the image file is located within the ImageClass search tree, then you may omit the path.

clear

• Here you may specify a _CLEARCOLOR number (0-255), which shall be transparent, or a star (*) placeholder for none. For images with clear black alpha transparency (such as the provided icons) use number 39, which is black in the GuiTools Framework's palette.

{SYM which back shadow shine border}

which

• The name of the symbol to use (see dev_framework\classes\SymbolClass.bm).

back, shadow, shine, border

• The respective color pens to use as number (0-255), or a star (*) placeholder to keep the symbol's default for the respective pen(s).

Use only a single space for option separation, eg.:

{IMG 'Error Icon.png' *} -> quoted name, no _CLEARCOLOR

{SYM Checkmark * 7 * *} -> SHADOWPEN=7, all other default

All given images and symbols will be KEEPASPECT scaled to fit for the used button height.

RESULT:

button$ (STRING)

• The user's response, which is the text of the pressed button as specified in buttonText$ or empty, if the user did ignore the message by simply pressing <Esc> or closing the MessageBox window via the "X" button.

back to Table of Contents