<doc>
  <legacy_id>1906</legacy_id>
  <name>modal</name>
  <type>command</type>
  <syntax>
    <example>modal <i>stack</i></example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>Windows &amp; Dialog Boxes</category>
  </classification>
  <references>
    <command tag="ask">ask Command</command>
    <command tag="ask file with type">ask file with type Command</command>
    <command tag="modeless">modeless Command</command>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
  </classes>
  <security>
  </security>
  <summary>Opens a <object tag="stack">stack</object> as a <glossary tag="modal dialog box">modal dialog box</glossary>.</summary>
  <examples>
    <example>modal stack "Custom Answer Dialog"</example>
    <example>modal stack x of stacksToPresent</example>
  </examples>
  <description>
    <p>Use the <b>modal</b> <glossary tag="command">command</glossary> to display a <object tag="stack">stack</object> as a custom <glossary tag="modal dialog box">modal dialog box</glossary>.</p><p/><p><b>Parameters:</b></p><p>The <i>stack</i> is any <href tag="reference/object_reference.rev">stack reference</href>.</p><p/><p><b>Comments:</b></p><p>The <b>modal</b> <glossary tag="command">command</glossary> opens the <object tag="stack">stack</object> centered over the <property tag="defaultStack">defaultStack</property>, regardless of the <glossary tag="stack">stack's</glossary> <keyword tag="rectangle">rectangle</keyword> and <property tag="location">location</property> <property tag="properties">properties</property>.</p><p/><p>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.</p><p/><p>If the stack is already open, the <b>modal</b> <glossary tag="command">command</glossary> closes the <object tag="stack">stack</object> and reopens it as a <glossary tag="modal dialog box">modal dialog box</glossary>, so <message tag="closeStack">closeStack</message> and <message tag="openStack">openStack</message>, <message tag="closeCard">closeCard</message> and <message tag="openCard">openCard</message>, and (if applicable) <message tag="closeBackground">closeBackground</message> and <message tag="openBackground">openBackground</message> <glossary tag="message">messages</glossary> are sent to the <glossary tag="current card">current card</glossary> as a result of <glossary tag="execute">executing</glossary> this <glossary tag="command">command</glossary>. Use the <command tag="lock messages">lock messages</command> <glossary tag="command">command</glossary> before <glossary tag="execute">executing</glossary> <b>modal</b> if you want to prevent the close <glossary tag="message">messages</glossary> from being sent; the open <glossary tag="message">messages</glossary> are sent regardless of the setting of the <property tag="lockMessages">lockMessages</property> <glossary tag="property">property</glossary>.</p><p/><p>If the stack is already displayed as a modal dialog box, the <b>modal</b> <glossary tag="command">command</glossary> does not close and reopen it.</p><p/><p>The <b>modal</b> <glossary tag="command">command</glossary> pauses the running <glossary tag="handler">handler</glossary> until the <glossary tag="modal dialog box">modal dialog box</glossary> is dismissed (usually by clicking a button in the <glossary tag="modal dialog box">modal dialog box</glossary>). To <constant tag="return">return</constant> information to the <glossary tag="handler">handler</glossary> about which <keyword tag="button">button</keyword> was clicked, in the <glossary tag="button">button's</glossary> <property tag="script">script</property>, set a <glossary tag="global">global variable</glossary> or <property tag="customProperties">custom property</property>. After the <glossary tag="dialog box">dialog box</glossary> is dismissed, the <glossary tag="handler">handler</glossary> can query this <glossary tag="variable">variable</glossary> or <glossary tag="property">property</glossary> and act accordingly.</p><p/><p>Modal dialog boxes cannot be resized or edited. To edit a modal dialog box, use the <b>topLevel</b> <glossary tag="command">command</glossary> to display it in an <glossary tag="editable window">editable window</glossary>. The <glossary tag="Browse tool">Browse tool</glossary> is used in <glossary tag="modal dialog box">modal dialog boxes</glossary>, regardless of the current setting of the <function tag="tool">tool</function> <glossary tag="property">property</glossary>.</p>
  </description>
</doc>