Name: modal

Type: command

Syntax: modal <stack>

Summary:
Opens a <stack> as a <modal dialog box>.

Introduced: 1.0

OS: mac, windows, linux

Platforms: desktop, server

Example:
modal stack "Custom Answer Dialog"

Example:
modal stack x of stacksToPresent

Parameters:
stack:
Any stack reference.

Description:
Use the <modal> <command> to display a <stack> as a custom 
<modal dialog box>. 

>*Important:*  When a <stack> is opened as <modal> its <location> is set
> to the center of the <defaultStack> if the <defaultStack> is open and
> <visible>. If not then its <location> is set to the center of the
> <topStack> if there is one and it is <visible>. If not then the
> <stack|stack's> own <location> and <rectangle> <property|properties>
> are used to place the window. To override this behavior set the
> <location> of the <stack> in its <preOpenStack> <handler>.

While a modal dialog box is open, other windows cannot be edited or
brought to the front. Because of this, you should use modal dialog boxes
only when a stack must obtain feedback from the user before it can
continue. This can be problematic if no means of dismissing the stack is
provided. To remedy this situation select "stack mode" -&gt; "Toplevel"
from the stack's context menu. The context menu can be accessed by
using, Shift-Control-Right--Click on Windows or
Shift-Command-Right-Click/Command-Control-Shift-Click on Mac.

If the stack is already open, the <modal> <command> closes the <stack>
and reopens it as a <modal dialog box>, so <closeStack> and <openStack>,
<closeCard> and <openCard>, and (if applicable) <closeBackground> and
<openBackground> <message|messages> are sent to the <current card> as a
result of <execute|executing> this <command>. Use the <lock messages>
<command> before <execute|executing> <modal> if you want to prevent the
close <message|messages> from being sent; the open <message|messages>
are sent regardless of the setting of the <lockMessages> <property>.

If the stack is already displayed as a modal dialog box, the <modal>
<command> does not close and reopen it.

The <modal> <command> pauses the running <handler> until the 
<modal dialog box> is dismissed (usually by clicking a button in the 
<modal dialog box>). To <return> information to the <handler> about 
which <button(keyword)> was clicked, in the <button(object)|button's>
<script>, set a <global|global variable> or <custom property>. After the
<dialog box> is dismissed, the <handler> can query this <variable> or
<property> and act accordingly.

Modal dialog boxes cannot be resized or edited. To edit a modal dialog
box, use the topLevel <command> to display it in an <editable window>.
The <Browse tool> is used in <modal dialog box|modal dialog boxes>,
regardless of the current setting of the <tool> <property>.

References: lock messages (command), ask (command),
ask file with type (command), modeless (command), return (constant),
tool (function), variable (glossary), editable window (glossary),
property (glossary), dialog box (glossary), location (property),
execute (glossary), modal dialog box (glossary), command (glossary),
global (glossary), Browse tool (glossary), custom property (glossary),
message (glossary), current card (glossary), handler (glossary),
rectangle (property), button (keyword), openCard (message),
closeStack (message), closeCard (message), closeBackground (message),
openStack (message), openBackground (message), stack (object),
button (object), defaultStack (property), script (property),
properties (property), lockMessages (property), visible (property),
preOpenStack (message), topStack (function)

Tags: windowing
