<doc>
  <legacy_id>2248</legacy_id>
  <name>setProp</name>
  <type>control structure</type>
  <syntax>
    <example>setProp <i>propertyName newValue</i><i>  statementList</i>end<i> propertyName</i></example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>Writing LiveCode</category>
  </classification>
  <references>
    <control_st tag="exit">exit Control Structure</control_st>
    <function tag="propertyNames">propertyNames Function</function>
    <function tag="paramCount">paramCount Function</function>
    <keyword tag="$">$ Keyword</keyword>
    <property tag="customPropertySets">customPropertySets Property</property>
    <property tag="customProperties">customProperties Property</property>
    <property tag="properties">properties Property</property>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
    <changed version="2.0"></changed>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
    <ios/>
    <android/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
    <mobile/>
  </classes>
  <security>
  </security>
  <summary><glossary tag="handle">Handles</glossary> the <glossary tag="trigger">trigger</glossary> sent to an <glossary tag="object">object</glossary> when you change one of its <property tag="customProperties">custom properties</property>.</summary>
  <examples>
  </examples>
  <description>
    <p>Use the <b>setProp</b> <glossary tag="control structure">control structure</glossary> to check the range of a <property tag="customProperties">custom property</property> that is being set, or to change other <property tag="properties">properties</property> or do other tasks at the same time a <property tag="customProperties">custom property</property> is set.</p><p/><p><b>Form:</b></p><p>The first line of a <b>setProp</b> <glossary tag="handler">handler</glossary> consists of the word "setProp" followed by the name of the <property tag="customProperties">custom property</property>.</p><p/><p>The last line of a <b>setProp</b> <glossary tag="handler">handler</glossary> consists of the word "end" followed by the <glossary tag="property">property's</glossary> name.</p><p/><p><b>Parameters:</b></p><p>The <i>propertyName</i> is a <keyword tag="string">string</keyword> up to 65,535 characters in length.</p><p/><p>The <i>newValue</i> is a <keyword tag="string">string</keyword>.</p><p/><p>The <i>statementList</i> consists of one or more <glossary tag="LiveCode">LiveCode</glossary> <glossary tag="statement">statements</glossary>, and can also include <control_st tag="if">if</control_st>, <control_st tag="switch">switch</control_st>, <control_st tag="try">try</control_st>, or <control_st tag="repeat">repeat</control_st> <glossary tag="control structure">control structures</glossary>.</p><p/><p><b>Comments:</b></p><p>A <b>setProp</b> <glossary tag="handler">handler</glossary> can contain any set of <glossary tag="LiveCode">LiveCode</glossary> <glossary tag="statement">statements</glossary>.</p><p/><p>The <i>propertyName</i> is the name of the <property tag="customProperties">custom property</property> whose <function tag="value">value</function> is being changed with the <command tag="set">set</command> <glossary tag="command">command</glossary>. </p><p/><p><code/><b>Note:</b><code/> You cannot use a <b>setProp</b> <glossary tag="handler">handler</glossary> to intercept a built-in <glossary tag="property">property</glossary>. The <b>setProp</b> <glossary tag="control structure">control structure</glossary> can be used only for <property tag="customProperties">custom properties</property>.</p><p/><p>The <b>setProp</b> <glossary tag="trigger">trigger</glossary> passes through the <glossary tag="message path">message path</glossary>, the same as any other <keyword tag="message box">message</keyword>, so a <b>setProp</b> <glossary tag="handler">handler</glossary> for an <glossary tag="object">object</glossary> can be located in the <glossary tag="object">object's</glossary> <property tag="script">script</property> or in the <property tag="script">script</property> of any <glossary tag="object">object</glossary> further in the <glossary tag="message path">message path</glossary>. For example, a <b>setProp</b> <glossary tag="handler">handler</glossary> for a card <glossary tag="property">property</glossary> may be located in the <property tag="script">script</property> of the <object tag="stack">stack</object> that the <keyword tag="card">card</keyword> belongs to.</p><p/><p>If you use the <b>set</b> <glossary tag="command">command</glossary> within a <b>setProp</b> <glossary tag="control structure">control structure</glossary> to set the same <property tag="customProperties">custom property</property> for the current <glossary tag="object">object</glossary>, no <b>setProp</b> <glossary tag="trigger">trigger</glossary> is sent to the <glossary tag="object">object</glossary>. (This is to avoid runaway <glossary tag="recursion">recursion</glossary>, where the <b>setProp</b> <glossary tag="handler">handler</glossary> <glossary tag="trigger">triggers</glossary> itself.)</p><p/><p>This is only the case for the custom property that the current <b>setProp</b> <glossary tag="handler">handler</glossary> applies to. Setting a different <property tag="customProperties">custom property</property> sends a <b>setProp</b> <glossary tag="trigger">trigger</glossary>. So does setting the <glossary tag="handler">handler's</glossary> <property tag="customProperties">custom property</property> for an <glossary tag="object">object</glossary> other than the one whose script contains the <b>setProp</b> <glossary tag="handler">handler</glossary>.</p><p/><p><code/><img src="202650"/> <b>Caution!</b><code/> If a <control_st tag="setProp">setProp</control_st> <glossary tag="handler">handler</glossary> in one <glossary tag="object">object's</glossary> <property tag="script">script</property> sets the <property tag="customProperties">custom property</property> for a different <glossary tag="object">object</glossary>, and the first <glossary tag="object">object</glossary> is in the second <glossary tag="object">object's</glossary> <glossary tag="message path">message path</glossary>, a runaway <glossary tag="recursion">recursion</glossary> will result. For example, if the following <glossary tag="handler">handler</glossary> is in a <keyword tag="card">card</keyword> <property tag="script">script</property>, and you set the "myCustomProperty" of a <keyword tag="button">button</keyword> on the <keyword tag="card">card</keyword>, runaway <glossary tag="recursion">recursion</glossary> will result:</p><p/><p><code>  setProp myCustomProperty newValue</code></p><p><code>    set the myCustomProperty of the target to newValue + 1</code></p><p><code><i>    -- Because the target is the button, and this handler is in</i></code></p><p><code><i>    -- the card, the above statement sends another setProp trigger</i></code></p><p><code><i>    -- to the button.</i></code></p><p><code>  end myCustomProperty</code></p><p/><p>To avoid this problem, set the <b>lockMessages</b> property to true before setting the custom property. </p><p/><p>You can include as many <b>setProp</b> <glossary tag="handler">handlers</glossary> in a <property tag="script">script</property> as you need. The <glossary tag="property">property</glossary> that a <b>setProp</b> <glossary tag="handler">handler</glossary> controls is determined by the <i>propertyName</i> <glossary tag="parameter">parameter</glossary> in the first line of the <glossary tag="handler">handler</glossary>. (If a <property tag="script">script</property> contains two <b>setProp</b> <glossary tag="handler">handlers</glossary> for the same <glossary tag="property">property</glossary>, the first one is used.)</p><p/><p>If the custom property you want to control is in a custom property set, use array notation in the first line of the <b>setProp</b> <glossary tag="handler">handler</glossary>, as in the following example:</p><p/><p><code>  setProp mySet[thisProperty] newValue</code></p><p><code>    if thisProperty is "that" then put newValue into me</code></p><p><code>  end setProp</code></p><p/><p>The above <b>setProp</b> <glossary tag="handler">handler</glossary> responds to changes in the <property tag="customProperties">custom property</property> named "that", which is a member of the custom <glossary tag="custom property set">property set</glossary> named "mySet".</p><p/><p><code/><b><img src="202653"/> Important!</b><code/> You must either include the <control_st tag="pass">pass</control_st> <glossary tag="control structure">control structure</glossary> or set the <glossary tag="property">property</glossary> explicitly in a <b>setProp</b> <glossary tag="handler">handler</glossary>, if you want LiveCode to set the <property tag="customProperties">custom property</property>. Otherwise, the <b>setProp</b> <glossary tag="handler">handler</glossary> <glossary tag="trap">traps</glossary> the <command tag="call">call</command> to set the <glossary tag="property">property</glossary>, and its <function tag="value">value</function> is not changed.</p><p/><p><b>Changes:</b></p><p>In version 2.0 and later, setting a custom property (other than the one that the current <b>setProp</b> <glossary tag="handler">handler</glossary> applies to) inside a <b>setProp</b> <glossary tag="handler">handler</glossary> sends a <b>setProp</b> <glossary tag="trigger">trigger</glossary>. In previous versions, setting a <property tag="customProperties">custom property</property> within a <b>setProp</b> <glossary tag="handler">handler</glossary> never sent a <b>setProp</b> <glossary tag="trigger">trigger</glossary>, regardless of which <property tag="customProperties">custom property</property> you set.</p>
  </description>
</doc>