<doc>
  <legacy_id>1635</legacy_id>
  <name>getProp</name>
  <type>control structure</type>
  <syntax>
    <example>getProp <i>propertyName</i><i>  statementList</i>end <i>propertyName</i></example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>Writing LiveCode</category>
  </classification>
  <references>
    <command tag="get">get Command</command>
    <control_st tag="exit">exit Control Structure</control_st>
    <function tag="paramCount">paramCount Function</function>
    <keyword tag="end">end Keyword</keyword>
    <property tag="customPropertySets">customPropertySets 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><glossary tag="handle">Handles</glossary> the <keyword tag="message box">message</keyword> sent to an <glossary tag="object">object</glossary> when you access one of its <property tag="customProperties">custom properties</property>.</summary>
  <examples>
  </examples>
  <description>
    <p>Use the <b>getProp</b> <glossary tag="control structure">control structure</glossary> to perform a transformation on a <property tag="customProperties">custom property</property> before its <function tag="value">value</function> is <glossary tag="return">returned</glossary> to the <glossary tag="handler">handler</glossary> that requested it, or to implement a virtual <glossary tag="property">property</glossary> (one that is implemented only in a <glossary tag="handler">handler</glossary>).</p><p/><p><b>Form:</b></p><p>The first line of a <b>getProp</b> <glossary tag="handler">handler</glossary> consists of the <keyword tag="word">word</keyword> "getProp" followed by the <glossary tag="property">property's</glossary> name.</p><p/><p>The last line of a <b>getProp</b> <glossary tag="handler">handler</glossary> consists of the <keyword tag="word">word</keyword> "end" followed by the <glossary tag="property">property's</glossary> name.</p><p/><p><b>Parameters:</b></p><p>The <i>propertyName</i> is the name of a <property tag="customProperties">custom property</property>.</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>The property's value is returned to the calling handler by a <b>return</b> <glossary tag="control structure">control structure</glossary> within the <b>getProp</b> <glossary tag="handler">handler</glossary>. (A <b>getProp</b> <glossary tag="handler">handler</glossary> works much like a <href tag="dictionary/property/2381.xml">custom function</href> <glossary tag="handler">handler</glossary>, in the sense that it exists to <constant tag="return">return</constant> a <function tag="value">value</function>.)</p><p/><p>The <b>getProp</b> <command tag="call">call</command> passes through the <glossary tag="message path">message path</glossary>, so a <b>getProp</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>getProp</b> <glossary tag="handler">handler</glossary> for a <keyword tag="card">card</keyword> <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 a custom property of an object within a <b>getProp</b> <glossary tag="control structure">control structure</glossary> for the <property tag="customProperties">custom property</property> in the <glossary tag="object">object's</glossary> own <property tag="script">script</property>, no <b>getProp</b> <command tag="call">call</command> is sent to the <glossary tag="object">object</glossary>. (This is to avoid runaway <glossary tag="recursion">recursion</glossary>, where the <b>getProp</b> <glossary tag="handler">handler</glossary> <glossary tag="call">calls</glossary> itself.) This is only the case for the <property tag="customProperties">custom property</property> that the current <b>getProp</b> <glossary tag="handler">handler</glossary> applies to. Setting a different <property tag="customProperties">custom property</property> does send a <b>getProp</b> <command tag="call">call</command>. So does setting the same <property tag="customProperties">custom property</property> for an <glossary tag="object">object</glossary> other than the one whose script contains the <b>getProp</b> <glossary tag="handler">handler</glossary>.</p><p/><p><code/><img src="202650"/> <b>Caution!</b><code/> If a <control_st tag="getProp">getProp</control_st> <glossary tag="handler">handler</glossary> in one <glossary tag="object">object's</glossary> <property tag="script">script</property> uses the <function tag="value">value</function> of 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 <object tag="stack">stack</object> <property tag="script">script</property>, and you get the "myCustomProperty" of a <keyword tag="card">card</keyword> in that <object tag="stack">stack</object>, runaway <glossary tag="recursion">recursion</glossary> will result:</p><p/><p><code>  getProp myCustomProperty</code></p><p><code>    put the myCustomProperty of the target into myVariable</code></p><p><code><i>    -- Because the target is the card, and this handler is in</i></code></p><p><code><i>    -- the stack, the above statement sends another getProp call</i></code></p><p><code><i>    -- to the card.</i></code></p><p><code>  end myCustomProperty</code></p><p/><p>To avoid this problem, set the <b>lockMessages</b> property to true before checking the custom property.</p><p/><p>You can include as many <b>getProp</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>getProp</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>getProp</b> <glossary tag="handler">handlers</glossary> for the same <glossary tag="property">property</glossary>, the first one is used.)</p><p/><p><code/><b>Note:</b><code/> You cannot use a <b>getProp</b> <glossary tag="handler">handler</glossary> to intercept a <command tag="call">call</command> for the <function tag="value">value</function> of a built-in <glossary tag="property">property</glossary>. The <b>getProp</b> <glossary tag="control structure">control structure</glossary> can be used only for <property tag="customProperties">custom properties</property>.</p><p/><p>A<b> getProp</b> <glossary tag="handler">handler</glossary> can be used to implement virtual <property tag="properties">properties</property> for an <glossary tag="object">object</glossary>. A virtual <glossary tag="property">property</glossary> does not exist in the list of the <glossary tag="object">object's</glossary> <property tag="customProperties">custom properties</property>. Instead, when a <glossary tag="statement">statement</glossary> <glossary tag="call">calls</glossary> for the <glossary tag="property">property's</glossary> <function tag="value">value</function>, the <b>getProp</b> <glossary tag="handler">handler</glossary> computes that <function tag="value">value</function>.</p><p/><p>For example, the following <b>getProp</b> <glossary tag="handler">handler</glossary> implements a virtual <glossary tag="property">property</glossary> of a <keyword tag="field">field</keyword> that contains a list of numbers:</p><p/><p><code>  getProp columnAverage</code></p><p><code>    repeat for each line thisNumber of me</code></p><p><code>      add thisNumber to fieldTotal</code></p><p><code>    end repeat</code></p><p><code>    return fieldTotal/the number of lines of me</code></p><p><code>  end columnAverage</code></p><p/><p>The "columnAverage" property of the field does not exist in the list of the field's custom properties. Instead, it is evaluated when a statement requests it:</p><p/><p><code>  put the columnAverage of field "Numbers" into field "Average"</code></p>
  </description>
</doc>