Adds a new property to an object at run time.
You can use AddProperty( ) to add properties and their values to valid X# objects, including those created from X# classes, COM classes, and the SCATTER...NAME command.

Namespace: XSharp.VFP
Assembly: XSharp.VFP (in XSharp.VFP.dll) Version: 2.19

Syntax

Copy

 FUNCTION AddProperty(
	oObjectName AS Object,
	cPropertyName AS STRING,
	 eNewValue AS USUAL
) AS LOGIC

public static bool AddProperty(
	Object oObjectName,
	string cPropertyName,
	[DefaultParameterValueAttribute(0, 1)] Usual eNewValue
)

Request Example View Source

Parameters

oObjectName: Type: Object
Specifies the name of the object to which the property is added.
If oObjectName is not a valid object, X# generates the appropriate message.
cPropertyName: Type: String
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: Type: Usual
Specifies the value to set for the new property.
If you omit eNewValue, and the property exists, X# leaves the value of the property unchanged. If you omit eNewValue, and the property is new, X# sets the value of the new property to False (.F.).

Return Value

Type: Logic
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( ) 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 X# 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. X# 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.

Return value

Description

True (.T.)

When AddProperty( )
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 X# 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. X# 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.
X# 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 X# native property, such as the BaseClass property, X# 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, X# generates an error, "Incorrect property name (Error 1470)".
For object instances derived from native X# 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 X# OLEPUBLIC classes.

AddProperty( ) does not work when using the For EACH command with object references. However, you can use the AddProperty method instead. Example 1
The following example adds a new property to an object created with the SCATTER command.

Copy

1Use customers
2SCATTER NAME oCust
3ADDPROPERTY(oCust,"MyProperty")

Example 2
The following example creates a property array for the object, codeoMyForm/code, and displays its contents, code1/code and code"Two"/code.

Copy

1oMyForm = CreateObject('Form')
2ADDPROPERTY(oMyForm, 'MyArray(2)', 1)
3oMyForm.MyArray(2) = "Two"
4Clear
5? oMyForm.MyArray(1)
6? oMyForm.MyArray(2)

Reference

Functions, Globals and Defines

XSharp.VFP Namespace