ADDPROPERTY( ) Function
Adds a new property to an object at run time.
You can use ADDPROPERTY( ) to add properties and their values to valid Visual FoxPro objects, including those created from Visual FoxPro classes, COM classes, and the SCATTER...NAME command.
ADDPROPERTY(oObjectName, cPropertyName, [, eNewValue ])
Parameters
oObjectName
Specifies the name of the object to which the property is added.If oObjectName is not a valid object, Visual FoxPro generates the appropriate message.
cPropertyName
Specifies the name of the new property to add to the object.If the property with the name you specify does not exist, the property is created and added.
eNewValue
Specifies the value to set for the new property.If you omit eNewValue, and the property exists, Visual FoxPro leaves the value of the property unchanged. If you omit eNewValue, and the property is new, Visual FoxPro sets the value of the new property to False (.F.).
Return Value
Logical data type. The following table describes the return values for ADDPROPERTY( ) and the behavior when you attempt to add a property that already exists for an object.
Return value |
Description |
|---|---|
True (.T.) |
When ADDPROPERTY( ) adds the property successfully. When the new property is an array property, and the array already exists, ADDPROPERTY( ) redimensions the array with the dimensions specified by cPropertyName. If you specify a value with eNewValue, all elements in the array are set to that value. If you omit eNewValue, all array elements are set to False (.F.). If the new property is not an array property, but the existing property is an array property. The property remains an array property with the same dimensions. If you specify a value with eNewValue, all elements in the array are set to that value. If you omit eNewValue, all array elements are set to False (.F.). If the new property is not an array property, and the existing property is not an array property or is not a read-only Visual FoxPro native property. If you specify a value with eNewValue, the existing property is set to that value. If you omit eNewValue, the existing property value remains unchanged. If the specified property is already a member of the object but is marked as Hidden or Protected. Visual FoxPro generates an error, "Property name is not found (Error 1734)", and the property is not set to the value passed to ADDPROPERTY( ). |
False (.F.) |
When ADDPROPERTY( ) did not add the property successfully. If the property is an array property, and the existing property is not an array property. The existing property remains unchanged. |
Remarks
You can create property arrays using ADDPROPERTY( ) for an object. When you do so, every element in the array is initialized with eNewValue, if provided. Otherwise, the value of each property in the array is set to False (.F.). For more information about creating a property array for an object, see the Examples section.
Visual FoxPro adds the new property as a Public property. You cannot specify the property as Protected or Hidden.
If the existing property is a read-only Visual FoxPro native property, such as the BaseClass property, Visual FoxPro generates an error, "Property name is read-only (Error 1743)".
If the property name is not valid, for example, the property name contains a space or other illegal characters, Visual FoxPro generates an error, "Incorrect property name (Error 1470)".
For object instances derived from native Visual FoxPro classes, ADDPROPERTY( ) respects the visibility setting of the intrinsic AddProperty method. If AddProperty is marked as Hidden or Protected, ADDPROPERTY( ) does not create the new property and returns False (.F.). If the AddProperty method is marked as Public (default), ADDPROPERTY( ) creates the property and returns True (.T.). This protects the original class design.
Note
This does not apply to COM objects created with Visual FoxPro OLEPUBLIC classes.
ADDPROPERTY( ) does not work when using the FOR EACH command with object references. However, you can use the AddProperty method instead.
Examples
Example 1
The following example adds a new property to an object created with the SCATTER command.
USE customers
SCATTER NAME oCust
ADDPROPERTY(oCust,"MyProperty")
Example 2
The following example creates a property array for the object, oMyForm, and displays its contents, 1 and "Two".
oMyForm = CREATEOBJECT('Form')
ADDPROPERTY(oMyForm, 'MyArray(2)', 1)
oMyForm.MyArray(2) = "Two"
CLEAR
? oMyForm.MyArray(1)
? oMyForm.MyArray(2)