<doc>
	<legacy_id></legacy_id>
	<name>layerMode</name>
	<type>property</type>

	<syntax>
		<example>set the layerMode of <i>object</i> to <i>mode</i></example>
		<example>get the [effective] layerMode of <i>object</i></example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Specifies whether an object is dynamic or static.</summary>

	<examples>
<example>set the layerMode of button 1 to &quot;static&quot;</example>
<example><p>set the layerMode of image &quot;background&quot; to &quot;static&quot;</p><p>set the layerMode of image &quot;bouncing_ball&quot; to &quot;dynamic&quot;</p></example>
<example><p>set the layerMode of group &quot;scroller&quot; to &quot;scrolling&quot;</p><p>get the effective layerMode of group &quot;scroller&quot;</p><p>if it is &quot;dynamic&quot; then</p><p>   answer &quot;group needs updated for fast scrolling&quot;</p><p>end if</p></example>
	</examples>

	<history>
		<introduced version="5.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		
	</history>

	<objects>
		<group/>
		<field/>
		<button/>
		<graphic/>
		<scrollbar/>
		<player/>
		<image/>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<mobile/>
	</classes>

	<security>
	</security>


	<classification>
		<category>Objects &amp; Messages</category>
		<category>Windows &amp; Dialog Boxes</category>
		<concept>display</concept>
	</classification>

	<references>
		<property tag="compositorCacheLimit">compositorCacheLimit Property</property>
		<property tag="compositorTileSize">compositorTileSize Property</property>
		<property tag="compositorType">compositorType Property</property>
	</references>

	<description>
	<overview>Use the <b>layerMode </b>property to specify if an object is static or dynamic. The LiveCode engine uses this to optimize rendering performance by caching objects that are moving or changing regularly.</overview>

		<parameters>
  <parameter>
    <name>object</name>
    <description>The name or ID of the object.</description>
  </parameter>
  <parameter>
    <name>mode</name>
    <description>A string specifying the mode of the object. One of the following:</description>
    <options title="">
      <option>
        <item>static</item>
        <description>(default) The object is static and does not move or change.</description>
      </option>
      <option>
        <item>dynamic</item>
        <description>The object is dynamic and subject to change and/or movement.</description>
      </option>
      <option>
        <item>scrolling</item>
        <description>Applies to groups only and is used where the group contains contents to scroll. The group must be unadorned or the layerMode is set to 'dynamic' (no borders, no scrollbars).</description>
      </option>
    </options>
  </parameter>		</parameters>

	<value>Getting the <b>layerMode</b> property of the target object returns the value in the <b>it</b> variable.</value>
	<comments>If you specify the <b>effective</b> keyword, getting the <b>layerMode</b> returns how the engine is actually treating the layer, rather than what you requested it to be. There can be a difference for a number of reasons:<p></p><p>1) You are not using a compositor (set using <property tag="compositorType">compositorType property</property>) - <b>effective</b> <b>layerMode</b> is set to 'static'. </p><p>2) You have a static <b>layerMode</b> object with a non-copy/blendSrcOver ink set - <b>effective</b> <b>layerMode</b> is set to 'dynamic'.</p><p>3) You have a scrolling <b>layerMode</b> on a non-group or an adorned group - <b>effective</b> <b>layerMode</b> is set to 'dynamic'.</p><p></p><p>Scrolling</p><p>The scrolling layerMode is pertinent to groups. It means that the engine caches the content of the group unclipped, and then renders the cached copies clipped; instead of caching the visible portion of the group. This results in fast updates when setting the scroll properties of a group.</p><p></p><p>Static vs Dynamic</p><p>There are various contexts where setting the <b>layerMode</b> can have a big impact on the performance of an application, in particular games or interfaces with moving/changing elements. In these cases, the <b>layerMode</b> should be set to 'dynamic'.</p><p></p><p>A PLATFORM GAME EXAMPLE</p><p>Take a platform game as an example. The main character, any animated elements and scrolling platform components should all have a <b>layerMode</b> of 'dynamic'. However, the background image should have a <b>layerMode</b> of 'static'.</p><p></p><p>NON-GAME DRAG EXAMPLE</p><p>Consider a drag-drop interface where a user can 'pick' something up and drop it elsewhere. While the object is being dragged across the stack the <b>layerMode</b> can be set to 'dynamic' (particularly important if it has graphic effects applied). Once in its final location the <b>layerMode</b> can be returned to 'static'</p><p></p><p></p><warning>The <b>layerMode</b> only has an effect if the <property tag="compositorType">compositorType property</property> of the stack is not empty.</warning></comments>
	</description>
</doc>