handles the message sent to an object when you access one of its custom property.
# Metadata
Platforms: desktop, server, mobile OS: mac, windows, linux, ios, android Introduced: 1.0 Security:
# Syntax
getProp propertyName statementList end propertyName
# Params
- 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 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 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 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 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 script > uses the value of the custom property for a different > object, and the first object is in the second > object 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 property for an object. A virtual property does not exist in the list of the object custom property. Instead, when a statement calls for the property 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"
# Tags
# See
- **property:** 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