Name: getProp

Type: control structure

Syntax:
getProp <propertyName>
   <statementList>
end <propertyName>

Summary:
<handle|Handles> the <message> sent to an <object(glossary)> when you
access one of its <custom property|custom properties>.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Parameters:
propertyName:
The name of a custom property.

statementList:
The statementList consists of one or more LiveCode statements, and can
also include if, switch, try, or repeat control structures.

Description:
Use the <getProp> <control structure> to perform a transformation on a
<custom property> before its <value> is <return|returned> to the
<handler> that requested it, or to implement a virtual <property> (one
that is implemented only in a <handler>). 

**Form:** The first line of a <getProp> <handler> consists of the <word>
"getProp" followed by the <property|property's> name.

The last line of a <getProp> <handler> consists of the <word> "end"
followed by the <property|property's> name.

The property's value is returned to the calling handler by a return
<control structure> within the <getProp> <handler>. (A <getProp>
<handler> works much like a <custom function> <handler>, in the sense
that it exists to <return> a <value>.)

The <getProp> <call(command)> passes through the <message path>, so a
<getProp> <handler> for an <object(glossary)> can be located in the
<object|object's> <script> or in the <script> of any <object(glossary)>
further in the <message path>. For example, a <getProp> <handler> for a
<card> <property> may be located in the <script> of the <stack> that the
<card> belongs to.

If you use a custom property of an object within a <getProp> 
<control structure> for the <custom property> in the <object|object's>
own <script>, no <getProp> <call(command)> is sent to the
<object(glossary)>. (This is to avoid runaway <recursion>, where the
<getProp> <handler> <call(glossary)|calls> itself.) This is only the
case for the <custom property> that the current <getProp> <handler>
applies to. Setting a different <custom property> does send a <getProp>
<call(command)>. So does setting the same <custom property> for an
<object(glossary)> other than the one whose script contains the
<getProp> <handler>.

>*Warning:*  If a <getProp> <handler> in one <object|object's> <script>
> uses the <value> of the <custom property> for a different
> <object(glossary)>, and the first <object(glossary)> is in the second
> <object|object's> <message path>, a runaway <recursion> will result.
> For example, if the following <handler> is in a <stack> <script>, and
> you get the "myCustomProperty" of a <card> in that <stack>, runaway
> <recursion> will result:

    getProp myCustomProperty
        put the myCustomProperty of the target into myVariable
        -- Because the target is the card, and this handler is in
        -- the stack, the above statement sends another getProp call
        -- to the card.
    end myCustomProperty


To avoid this problem, set the lockMessages property to true before
checking the custom property.

You can include as many <getProp> <handler|handlers> in a <script> as
you need. The <property> that a <getProp> <handler> controls is
determined by the <propertyName> <parameter> in the first line of the
<handler>. (If a <script> contains two <getProp> <handler|handlers> for
the same <property>, the first one is used.)

>*Note:* You cannot use a <getProp> <handler> to intercept a
> <call(command)> for the <value> of a built-in <property>. The
> <getProp> <control structure> can be used only for <custom
> property|custom properties>.

A getProp <handler> can be used to implement virtual
<property|properties> for an <object(glossary)>. A virtual <property>
does not exist in the list of the <object|object's> <custom
property|custom properties>. Instead, when a <statement>
<call(glossary)|calls> for the <property|property's> <value>, the
<getProp> <handler> computes that <value>.

For example, the following <getProp> <handler> implements a virtual
<property> of a <field> that contains a list of numbers:

    getProp columnAverage
        repeat for each line thisNumber of me
            add thisNumber to fieldTotal
        end repeat
        return fieldTotal/the number of lines of me
    end columnAverage


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:

    put the columnAverage of field "Numbers" into field "Average"


References: get (command), call (command), return (constant),
getProp (control structure), exit (control structure),
paramCount (function), value (function), object (glossary),
script (glossary), return (glossary), call (glossary),
property (glossary), recursion (glossary), custom function (glossary),
control structure (glossary), custom property (glossary),
handle (glossary), message path (glossary), message (glossary),
parameter (glossary), statement (glossary), handler (glossary),
end (keyword), word (keyword), field (keyword), card (keyword),
stack (object), customPropertySets (property)

