<doc>
  <legacy_id>2052</legacy_id>
  <name>destroyStack</name>
  <type>property</type>
  <syntax>
    <example>set the destroyStack of <i>stack</i> to {true | false}</example>
  </syntax>
  <library></library>
  <objects>
    <stack/>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>Objects &amp; Messages</category>
    <category>Windows &amp; Dialog Boxes</category>
  </classification>
  <references>
    <message tag="reloadStack">reloadStack Message</message>
    <command tag="close">close Command</command>
    <function tag="hasMemory">hasMemory Function</function>
    <function tag="heapSpace">heapSpace Function</function>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
    <ios/>
    <android/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
    <mobile/>
  </classes>
  <security>
  </security>
  <summary>Specifies whether a <object tag="stack">stack</object> is purged from memory when it's closed, or whether it remains in memory.</summary>
  <examples>
    <example>set the destroyStack of this stack to true</example>
  </examples>
  <description>
    <p>Use the <b>destroyStack</b> <glossary tag="property">property</glossary> to leave a <object tag="stack">stack</object> in memory after it is closed.</p><p/><p><b>Value:</b></p><p>The <b>destroyStack</b> of a <object tag="stack">stack</object> is true or false.</p><p/><p>By default, the <b>destroyStack</b> <glossary tag="property">property</glossary> of newly created <function tag="stacks">stacks</function> is set to false.</p><p/><p><b>Comments:</b></p><p>If a stack's <b>destroyStack</b> <glossary tag="property">property</glossary> is set to true, closing all <function tag="stacks">stacks</function> in its <glossary tag="stack file">stack file</glossary> removes it from memory space, cleaning up after the <object tag="stack">stack</object> and freeing memory for use by the <glossary tag="application">application</glossary>. If any <glossary tag="handler">handlers</glossary> in the stack are running, the stack is not purged from memory until all <glossary tag="handler">handlers</glossary> have completed. (The <object tag="stack">stack</object> is not removed from memory until all <function tag="stacks">stacks</function> in the same <glossary tag="stack file">stack file</glossary> are also closed.)</p><p/><p>If the <b>destroyStack</b> is false, closing a <glossary tag="stack window">stack's window</glossary> leaves it in memory. If you open and close many <function tag="stacks">stacks</function> in a session, and the <b>destroyStack</b> of all these <function tag="stacks">stacks</function> is false, the memory used by these <function tag="stacks">stacks</function> will continue growing until you quit the <glossary tag="application">application</glossary>. If you reopen the <object tag="stack">stack</object> during the same session, a warning message appears cautioning you that the <object tag="stack">stack</object> is already open.</p><p/><p>If you close a stack whose <b>destroyStack</b> is true while a <glossary tag="handler">handler</glossary> is running, the <object tag="stack">stack</object> is removed from memory after all running <glossary tag="handler">handlers</glossary> finish <glossary tag="execute">executing</glossary>. This means that if you close and re-open a <object tag="stack">stack</object> during a <glossary tag="handler">handler</glossary>, and the <glossary tag="stack">stack's</glossary> <property tag="destroyStack">destroyStack</property> is true, the stack is removed from memory (and closed again) after the <glossary tag="handler">handler</glossary> finishes.</p><p/><p><code/><b>Note:</b><code/> Despite its alarming name, the <b>destroyStack</b> <glossary tag="property">property</glossary> does not destroy or damage a <object tag="stack">stack</object>. It simply allows it to be automatically removed from memory.</p>
  </description>
</doc>