<doc>
  <legacy_id>1484</legacy_id>
  <name>layer</name>
  <type>property</type>
  <syntax>
    <example>set the layer of <i>object</i> to {<i>layerNumber</i> | top | bottom}</example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
    <synonym>partNumber</synonym>
  </synonyms>
  <classification>
    <category>Appearance &amp; Positioning</category>
  </classification>
  <references>
    <function tag="number">number Function</function>
    <keyword tag="control">control Keyword</keyword>
    <command tag="ungroup">ungroup Command</command>
    <command tag="group">group Command</command>
    <function tag="mouseControl">mouseControl Function</function>
    <function tag="intersect">intersect Function</function>
    <property tag="tabGroupBehavior">tabGroupBehavior Property</property>
    <property tag="relayerGroupedControls">relayerGroupedControls Property</property>
  </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 the back-to-front order of <glossary tag="object">objects</glossary> on a <keyword tag="card">card</keyword> or the order of <glossary tag="card">cards</glossary> in a <object tag="stack">stack</object>.</summary>
  <examples>
    <example>set the layer of the mouseControl to top <code><i>-- bring to front</i></code></example>
    <example>set the layer of last card button to 10</example>
    <example>set the layer of player "Splash" to (the number of controls)</example>
  </examples>
  <description>
    <p>Use the <b>layer</b> <glossary tag="property">property</glossary> to change the tab order of <glossary tag="control">controls</glossary>, or to change the order of <glossary tag="card">cards</glossary> within a <object tag="stack">stack</object>.</p><p/><p><b>Value:</b></p><p>The <b>layer</b> <glossary tag="property">property</glossary> of a control or <keyword tag="card">card</keyword> is an <keyword tag="integer">integer</keyword>.</p><p/><p><b>Comments:</b></p><p>If the <i>object</i> is a <keyword tag="control">control</keyword>, it must appear on the <glossary tag="current card">current card</glossary> in order for its <b>layer</b> to be changed; you can't set the <b>layer</b> of a <keyword tag="control">control</keyword> on another <keyword tag="card">card</keyword>.</p><p/><p>The <b>layer</b> of a <keyword tag="control">control</keyword> is its order (from back to front) on the <keyword tag="card">card</keyword>. If two <glossary tag="control">controls</glossary> overlap, the one that covers the other has a higher <b>layer</b>. Each control is on a different <b>layer</b>.</p><p/><p>To bring a control forward, set its <b>layer</b> to a higher number. To send it back, set its <b>layer</b> to a lower number. You use the form</p><p><code>  set the layer of <i>object</i> to top</code></p><p>to bring the control all the way to the front, an<code>d</code></p><p><code>  set the layer of <i>object</i> to bottom</code></p><p>to send it all the way to the back.</p><p/><p>If you set the <b>layer</b> of a <keyword tag="control">control</keyword> to a number greater than the number of <glossary tag="control">controls</glossary> on the card, its <b>layer</b> is set equal to the number of <glossary tag="control">controls</glossary>.</p><p/><p>The <b>layer</b> of <glossary tag="control">controls</glossary> also determines the tab order. When you press the Tab key, the next <keyword tag="control">control</keyword> whose <property tag="traversalOn">traversalOn</property> <glossary tag="property">property</glossary> is true becomes the <glossary tag="active control">active (focused) control</glossary>. For example, to set the tab order of <glossary tag="field">fields</glossary> in a data entry form, set the <b>layer</b> of each <keyword tag="field">field</keyword> so that they are in order.</p><p/><p>The <b>layer</b> of a <command tag="group">group</command> determines the back-to-front position of all the <glossary tag="control">controls</glossary> in the group at once. The <command tag="group">group</command> behaves as a single <keyword tag="control">control</keyword>, as far as its <b>layer</b> is concerned. When you group or ungroup a <command tag="group">group</command>, its <glossary tag="control">controls</glossary> retain the same back-to-front placement relative to each other, but the <command tag="group">group</command> as a whole moves to the front. The <property tag="layer">layer</property> of a <command tag="group">group</command> is one less than the <property tag="layer">layer</property> of the lowest-layered <glossary tag="object">object</glossary> in the <command tag="group">group</command>.</p><p/><p>It is not possible for other controls to be interspersed between the controls in a single group. If the <b>relayerGroupedControls</b> <glossary tag="property">property</glossary> is set to true, and you set the <b>layer</b> of a <glossary tag="grouped control">grouped control</glossary> to a number greater than the topmost <keyword tag="control">control</keyword> in the <command tag="group">group</command>, or lower than the bottom-most <keyword tag="control">control</keyword> in the <command tag="group">group</command>, the <keyword tag="control">control</keyword> is moved out of the <command tag="group">group</command>. If the <property tag="relayerGroupedControls">relayerGroupedControls</property> is false, you cannot set the <b>layer</b> of a <glossary tag="grouped control">grouped control</glossary> without being in <href tag="../glossary/groupdashediting_mode.xml">group-editing mode</href>.</p><p/><p>The <b>layer</b> of a <keyword tag="card">card</keyword> specifies its position in the <object tag="stack">stack</object>. Setting the <b>layer</b> of a <keyword tag="card">card</keyword> moves it to the specified position in the <object tag="stack">stack</object>.</p><p/><p>Changing the <b>layer</b> of an <glossary tag="object">object</glossary> also changes its <function tag="number">number</function> <glossary tag="property">property</glossary>.</p>
  </description>
</doc>