mapping Option
The mapping method option indicates that the method is a mapping method. Mapping methods have the same name as a property and they are invoked automatically each time the value of the property is accessed in a method.
A mapping method has the following method signature.
method-name(set: Boolean; _value: type io);
Mapping methods act as a wrapper around properties. They can be used, for example, to ensure that properties are not updated with invalid values. If a corresponding property with the same name exists when a method is added, the method signature is then set up with the mapping option by default.
A virtual reference property must have a defined mapping method that is activated when the value of the property is set or retrieved. By default, methods are not mapping methods.
If you have mapping logic on subclassed controls, other processes such as the Jade Painter, Translator utility, or the loading of schemas may also execute that logic. The logic therefore may need to perform checks to determine if it is running in the user application environment, to ensure that exceptions are not generated in these other situations.
When a mapped property is specified on the left of an assignment (for example, prod.amount := amt), the parameter value passed to the mapping method is amt. If the parameter value is changed to newAmt in the mapping method, the amount property becomes newAmt. When a mapped property is specified on the right of an assignment (for example, amt := prod.amount), the parameter value passed in the mapping method is amount. If the parameter value is changed to newAmount in the mapping method, the amt local variable becomes newAmount.
The set parameter is true if the property is being set and false if the value of the property is being read. The _value parameter is a variable value of the same type as the property.
Mapped properties (that is, properties that have a mapping method) from a RootSchema class cannot be used as dictionary keys.
If the mapping method for a property that is used as a key in a dictionary maintained by automatic inverse maintenance returns a value in the variable parameter that is not equal to the value of the property in the object,
The following example shows a mapping method for an amount property. The method automatically discounts any amounts over 500 by ten percent (10%) when they are set. When an amount is read, twelve and a half percent (12.5%) is automatically added.
amount(set: Boolean; value: Real io) mapping;
begin
if set then
if value > 500 then
value := value * 0.9;
endif;
else
value := value * 1.125;
endif;
end;
For details about conditionSafe mapping methods, see "conditionSafe Option", earlier in this chapter, and for details about creating a mapping method for a property selected in the Properties List of a hierarchy browser, see "
The mapping method option cannot be combined with the typeMethod method option.
