getProp

Typecontrol structure
DictionaryLCS
LibraryLiveCode Script
Syntax
getProp <propertyName>
   <statementList>
end <propertyName>
Summary

Handles the message sent to an object when you access one of its custom properties.

Introduced1.0
OSmac, windows, linux, ios, android
Platformsdesktop, server, mobile
Parameters
NameTypeDescription
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.

RelatedProperty: customPropertySets
Command: get, call
Control Structure: getProp, exit
Keyword: end, word, field, card
Constant: return
Object: stack
Glossary: object, script, return, call, property, recursion, custom function, control structure, custom property, handle, message path, message, parameter, statement, handler
Function: paramCount, value
Description

Use the getProp control structure to perform a transformation on a custom property before its value is 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's name.

The last line of a getProp handler consists of the word "end" followed by the 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 passes through the message path, so a getProp handler for an object can be located in the 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's own script, no getProp call is sent to the object. (This is to avoid runaway recursion, where the getProp handler 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. 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's script uses the value of the custom property for a different object, and the first object is in the second 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 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 handlers for the same property, the first one is used.)

Note: You cannot use a getProp handler to intercept a call 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 properties for an object. A virtual property does not exist in the list of the object's custom property|custom properties. Instead, when a statement calls for the 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"