Name 

Description 

Creating Properties: Overview 

Properties are the most visible parts of components. The application developer can see and manipulate them at design time and get immediate feedback as the components react in the Form Designer. Well-designed properties make your components easier for others to use and easier for you to maintain.
To make the best use of properties in your components, you should understand the following:

• Why create properties?
• Types of properties
• Publishing inherited properties
• Defining properties
• Creating array properties
• Storing and loading properties

 

Why Create Properties? 

From the application developer's standpoint, properties look like variables. Developers can set or read the values of properties as if they were fields. (About the only thing you can do with a variable that you cannot do with a property is pass it as a var parameter.)
Properties provide more power than simple fields because

• Application developers can set properties at design time. Unlike methods, which are available only at runtime, properties let the developer customize components before running an application. Properties can appear in the Object Inspector, which simplifies the programmer's job; instead of handling several parameters to construct... more 

Types of Properties 

A property can be of any type. Different types are displayed differently in the Object Inspector, which validates property assignments as they are made at design time.
How properties appear in the Object Inspector  

Publishing Inherited Properties 

All components inherit properties from their ancestor classes. When you derive a new component from an existing one, your new component inherits all the properties of its immediate ancestor. If you derive from one of the abstract classes, many of the inherited properties are either protected or public, but not published.
To make a protected or public property available at design time in the Object Inspector, you must redeclare the property as published. Redeclaring means adding a declaration for the inherited property to the declaration of the descendant class. 

Defining Properties 

This section shows how to declare new properties and explains some of the conventions followed in the standard components. Topics include:

• Property declarations
• Internal data storage
• Direct access
• Access methods
• Default property values

 

Property Declarations 

A property is declared in the declaration of its component class. To declare a property, you specify three things:

• The name of the property.
• The type of the property.
• The methods used to read and write the value of the property. If no write method is declared, the property is read-only.

Properties declared in a published section of the component's class declaration are editable in the Object Inspector at design time. The value of a published property is saved with the component in the form file. Properties declared in a public section are available at runtime and can be read... more 

Internal Data Storage 

There are no restrictions on how you store the data for a property. In general, however, Delphi components follow these conventions:

• Property data is stored in class fields.
• The fields used to store property data are private and should be accessed only from within the component itself. Derived components should use the inherited property; they do not need direct access to the property's internal data storage.
• Identifiers for these fields consist of the letter F followed by the name of the property. For example, the raw data for the Width property defined in TControl is stored in a field called... more 

Direct Access 

The simplest way to make property data available is direct access. That is, the read and write parts of the property declaration specify that assigning or reading the property value goes directly to the internal-storage field without calling an access method. Direct access is useful when you want to make a property available in the Object Inspector but changes to its value trigger no immediate processing.
It is common to have direct access for the read part of a property declaration but use an access method for the write part. This allows the status of the component to be... more 

Access Methods (properties) 

You can specify an access method instead of a field in the read and write parts of a property declaration. Access methods should be protected, and are usually declared as virtual; this allows descendant components to override the property's implementation.
Avoid making access methods public. Keeping them protected ensures that application developers do not inadvertently modify a property by calling one of these methods. 

The Read Method 

The read method for a property is a function that takes no parameters (except as noted below) and returns a value of the same type as the property. By convention, the function's name is Get followed by the name of the property. For example, the read method for a property called Count would be GetCount. The read method manipulates the internal storage data as needed to produce the value of the property in the appropriate type.
The only exceptions to the no-parameters rule are for array properties and properties that use index specifiers (see Creating array properties), both... more 

The Write Method 

The write method for a property is a procedure that takes a single parameter (except as noted below) of the same type as the property. The parameter can be passed by reference or by value, and can have any name you choose. By convention, the write method's name is Set followed by the name of the property. For example, the write method for a property called Count would be SetCount. The value passed in the parameter becomes the new value of the property; the write method must perform any manipulation needed to put the appropriate data in the property's... more 

Default Property Values 

When you declare a property, you can specify a default value for it. The VCL uses the default value to determine whether to store the property in a form file. If you do not specify a default value for a property, the VCL always stores the property.
To specify a default value for a property, append the default directive to the property's declaration (or redeclaration), followed by the default value. For example,  

Specifying No Default Value 

When redeclaring a property, you can specify that the property has no default value, even if the inherited property specified one.
To designate a property as having no default value, append the nodefault directive to the property's declaration. For example,  

Creating Array Properties 

Some properties lend themselves to being indexed like arrays. For example, the Lines property of TMemo is an indexed list of the strings that make up the text of the memo; you can treat it as an array of strings. Lines provides natural access to a particular element (a string) in a larger set of data (the memo text).
Array properties are declared like other properties, except that

• The declaration includes one or more indexes with specified types. The indexes can be of any type.
• The read and write parts of the property declaration, if specified, must be methods. They... more 

Creating Properties for Interfaces 

You can use an interface as the value of a published property, much as you can use an object. However, the mechanism by which your component receives notifications from the implementation of that interface differs. In Creating properties for subcomponents, the property setter called the FreeNotification method of the component that was assigned as the property value. This allowed the component to update itself when the component that was the value of the property was freed. When the value of the property is an interface, however, you don't have access to the component that implements that interface. As a... more 

Creating Properties for Subcomponents 

By default, when a property's value is another component, you assign a value to that property by adding an instance of the other component to the form or data module and then assigning that component as the value of the property. However, it is also possible for your component to create its own instance of the object that implements the property value. Such a dedicated component is called a subcomponent.
Subcomponents can be any persistent object (any descendant of TPersistent). Unlike separate components that happen to be assigned as the value of a property, the published properties of subcomponents... more 

Storing and Loading Properties 

Delphi stores forms and their components in form (.dfm in VCL applications ) files. A form file stores the properties of a form and its components. When Delphi developers add the components you write to their forms, your components must have the ability to write their properties to the form file when saved. Similarly, when loaded into Delphi or executed as part of an application, the components must restore themselves from the form file.
Most of the time you will not need to do anything to make your components work with form files because the ability to store a representation... more 

Using the Store-and-load Mechanism 

The description of a form consists of a list of the form's properties, along with similar descriptions of each component on the form. Each component, including the form itself, is responsible for storing and loading its own description.
By default, when storing itself, a component writes the values of all its published properties that differ from their default values, in the order of their declaration. When loading itself, a component first constructs itself, setting all properties to their default values, then reads the stored, non-default property values.
This default mechanism serves the needs of most components, and requires no action... more 

Specifying Default Values 

Delphi components save their property values only if those values differ from the defaults. If you do not specify otherwise, Delphi assumes a property has no default value, meaning the component always stores the property, whatever its value.
To specify a default value for a property, add the default directive and the new default value to the end of the property declaration.
You can also specify a default value when re-declaring a property. In fact, one reason to re-declare a property is to designate a different default value.  

Determining What to Store 

You can control whether Delphi stores each of your components' properties. By default, all properties in the published part of the class declaration are stored. You can choose not to store a given property at all, or you can designate a function that determines dynamically whether to store the property.
To control whether Delphi stores a property, add the stored directive to the property declaration, followed by True, False, or the name of a Boolean function. 

Initializing After Loading 

After a component reads all its property values from its stored description, it calls a virtual method named Loaded, which performs any required initializations. The call to Loaded occurs before the form and its controls are shown, so you do not need to worry about initialization causing flicker on the screen.
To initialize a component after it loads its property values, override the Loaded method. The following code... more 

Storing and Loading Unpublished Properties 

By default, only published properties are loaded and saved with a component. However, it is possible to load and save unpublished properties. This allows you to have persistent properties that do not appear in the Object Inspector. It also allows components to store and load property values that Delphi does not know how to read or write because the value of the property is too complex. For example, the TStrings object can't rely on Delphi's automatic behavior to store and load the strings it represents and must use the following mechanism.
You can save unpublished properties by adding code that... more 

Creating Methods to Store and Load Property Values 

To store and load unpublished properties, you must first create a method to store your property value and another to load your property value. You have two choices:

• Create a method of type TWriterProc to store your property value and a method of type TReaderProc to load your property value. This approach lets you take advantage of Delphi's built-in capabilities for saving and loading simple types. If your property value is built out of types that Delphi knows how to save and load, use this approach.
• Create two methods of type TStreamProc, one to store and one to load... more 

Overriding the DefineProperties Method 

Once you have created methods to store and load your property value, you can override the component's DefineProperties method. Delphi calls this method when it loads or stores the component. In the DefineProperties method, you must call the DefineProperty method or the DefineBinaryProperty method of the current filer, passing it the method to use for loading or saving your property value. If your load and store methods are of type TWriterProc and type TReaderProc, then you call the filer's DefineProperty method. If you created methods of type TStreamProc, call DefineBinaryProperty instead.
No matter which method you use to... more