<doc>
  <legacy_id>1721</legacy_id>
  <name>stackFiles</name>
  <type>property</type>
  <syntax>
    <example>set the stackFiles of <i>stack</i> to <i>stackFileList</i></example>
  </syntax>
  <library></library>
  <objects>
    <stack/>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>Objects &amp; Messages</category>
    <category>Files, Folders, &amp; Resources</category>
  </classification>
  <references>
    <property tag="mainStack">mainStack Property</property>
    <property tag="filename of stack">filename of stack Property</property>
    <function tag="mainStacks">mainStacks 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 a list of <function tag="stacks">stacks</function> and their file names, to be used when a <object tag="stack">stack</object> that's not open is referenced in a <glossary tag="handler">handler</glossary>.</summary>
  <examples>
    <example>set the stackFiles of this stack to "My Dialog,Custom Dialogs.rev"</example>
  </examples>
  <description>
    <p>Use the <b>stackFiles</b> <glossary tag="property">property</glossary> to make one or more <function tag="stacks">stacks</function> accessible to <glossary tag="handler">handlers</glossary>, even if the <object tag="stack">stack</object> is not already open or in memory.</p>
<p>&nbsp;</p>
<p><b>Value:</b></p>
<p>The <b>stackFiles</b> of a <object tag="stack">stack</object> is a list of <href tag="">stack references</href>, one per <keyword tag="line">line</keyword>.</p>
<p>&nbsp;</p>
<p>Each stack reference consists of the short <b>name</b> of a <object tag="stack">stack</object>, a comma, and the name of the <keyword tag="file">file</keyword> that contains that <object tag="stack">stack</object>. (Do not put a space after the comma, unless the <keyword tag="file">file</keyword> name starts with a space.)</p>
<p>&nbsp;</p>
<p>By default, the <b>stackFiles</b> <glossary tag="property">property</glossary> of newly created <function tag="stacks">stacks</function> is set to empty.</p>
<p>&nbsp;</p>
<p><b>Comments:</b></p>
<p>When a handler or object refers to an object in a stack other than the current stack, LiveCode checks all stacks that are loaded into memory (and their substacks) to find the referenced stack. If the stack cannot be found, LiveCode checks the current stack's <b>stackFiles</b> <glossary tag="property">property</glossary> to locate the <object tag="stack">stack</object> being referenced, and <glossary tag="loaded into memory">loads it into memory</glossary> so that its <property tag="properties">properties</property> and the <glossary tag="object">objects</glossary> in it can be used.</p>
<p>&nbsp;</p>
<p>For example, if your stack contains a statement like this, the stack "Customers" must either be loaded into memory, or be listed in the <b>stackFiles</b>, in order for LiveCode to know where it is:</p>
<p>&nbsp;</p>
<p><code> get the width of field "Text" of card "Data" of stack "Customers"</code></p>
<p>&nbsp;</p>
<p>In this example, if the "Customers" stack is not open and isn't in the <b>stackFiles</b>, the <glossary tag="statement">statement</glossary> must refer to it by its full <keyword tag="long">long</keyword> <property tag="name">name</property>, including its <glossary tag="file path">file path</glossary>:</p>
<p>&nbsp;</p>
<p><code> get the width of field "Text" of card "Data" of stack "Customers" \</code></p>
<p><code> of stack "/Volumes/Data/Business.rev"</code></p>
<p>&nbsp;</p>
<p>Using the <b>stackFiles</b> lets you simply specify the <glossary tag="stack">stack's</glossary> name, instead of including its <glossary tag="file path">file path</glossary> everywhere you refer to an <glossary tag="object">object</glossary> in the <object tag="stack">stack</object>.</p>
<p>&nbsp;</p>
<p>The <b>stackFiles</b> of a <glossary tag="main stack">main stack</glossary> is inherited by its <property tag="substacks">substacks</property>: if a <glossary tag="handler">handler</glossary> in a <glossary tag="substack">substack</glossary> refers to a <object tag="stack">stack</object> that's not <glossary tag="load">loaded</glossary>, LiveCode checks the <b>stackFiles</b> of both the <glossary tag="substack">substack</glossary> and its <glossary tag="main stack">main stack</glossary>.</p>
<p>&nbsp;</p>
<p><code><img src="202653"/> <b>Important!</b><code> <glossary tag="relative file path">Relative file paths</glossary> in the <b>stackFiles</b> start from the <property tag="defaultFolder">folder</property> that the <i>stack</i> is in, rather than starting from the <property tag="defaultFolder">defaultFolder</property> as with other <glossary tag="relative file path">relative paths</glossary> in <glossary tag="LiveCode">LiveCode</glossary>.</code></code></p>
<p>&nbsp;</p>
<p>Placing a stack in the <b>stackFiles</b> lets <glossary tag="handler">handlers</glossary> in your <object tag="stack">stack</object> refer to <glossary tag="object">objects</glossary> in the referenced <object tag="stack">stack</object>, but does not automatically allow <glossary tag="handler">handlers</glossary> in your <object tag="stack">stack</object> to <command tag="call">call</command> <glossary tag="handler">handlers</glossary> in the referenced <glossary tag="stack">stack's</glossary> <glossary tag="script">scripts</glossary>. To use a <object tag="stack">stack</object> as a <command tag="start using">library</command>, allowing your <glossary tag="handler">handlers</glossary> to call the <glossary tag="stack">stack's</glossary> <glossary tag="handler">handlers</glossary>, use the <command tag="start using">start using</command> or <command tag="insert script">insert script</command> <glossary tag="command">command</glossary>.</p>
  </description>
</doc>