Name: getProp

Type: control structure

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

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

Introduced: 1.0

OS: mac,windows,linux,ios,android

Platforms: desktop,server,web,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> can be located in the <object|object's> <script> or in the <script> of any <object> 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>. (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> 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>, and the first <object> 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>. 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: customPropertySets (property), stack (object), object (object), return (constant), end (keyword), word (keyword), field (keyword), card (keyword), getProp (control_st), exit (control_st), paramCount (function), value (function), get (command), call (command), 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)
