Name 

Description 

Adding Clipboard Formats 

By default, when a user chooses Copy while a component is selected in the IDE, the component is copied in Delphi's internal format. It can then be pasted into another form or data module. Your component can copy additional formats to the Clipboard by overriding the Copy method.
For example, the following Copy method allows a TImage component to copy its picture to the Clipboard. This picture is ignored by the Delphi IDE, but can be pasted into other applications.  

Adding Component Editors 

Component editors determine what happens when the component is double-clicked in the designer and add commands to the context menu that appears when the component is right-clicked. They can also copy your component to the Windows clipboard in custom formats.
If you do not give your components a component editor, Delphi uses the default component editor. The default component editor is implemented by the class TDefaultEditor. TDefaultEditor does not add any new items to a component's context menu. When the component is double-clicked, TDefaultEditor searches the properties of the component and generates (or navigates to) the first event handler... more 

Adding Items to the Context Menu 

When the user right-clicks the component, the GetVerbCount and GetVerb methods of the component editor are called to build context menu. You can override these methods to add commands (verbs) to the context menu.
Adding items to the context menu requires the steps:

• Specifying menu items
• Implementing commands

 

Adding Property Editors 

The Object Inspector provides default editing for all types of properties. You can, however, provide an alternate editor for specific properties by writing and registering property editors. You can register property editors that apply only to the properties in the components you write, but you can also create editors that apply to all properties of a certain type.
At the simplest level, a property editor can operate in either or both of two ways: displaying and allowing the user to edit the current value as a text string, and displaying a dialog box that permits some other kind of editing.... more 

Changing the Double-click Behavior 

When the component is double-clicked, the Edit method of the component editor is called. By default, the Edit method executes the first command added to the context menu. Thus, in the previous example, double-clicking the component executes the DoThis command.
While executing the first command is usually a good idea, you may want to change this default behavior. For example, you can provide an alternate behavior if

• you are not adding any commands to the context menu.
• you want to display a dialog that combines several commands when the component is double-clicked.

Override the Edit method to specify a... more 

Compiling Components into Packages 

Once your components are registered, you must compile them as packages before they can be installed in the IDE. A package can contain one or several components as well as custom property editors. For more information about packages, see Working with packages and components .
To create and compile a package, see Creating and editing packages . Put the source-code units for your custom components in the package's Contains list. If your components depend on other packages, include those packages in the Requires list.
To install your components in the IDE, see Installing component packages. 

Creating the Entries 

To make your component's Help integrate seamlessly with the Help for the rest of the components in the library, observe the following conventions:
Each component should have a Help topic:
The component topic should show which unit the component is declared in and briefly describe the component. The component topic should link to secondary windows that describe the component's position in the object hierarchy and list all of its properties, events, and methods. Application developers access this topic by selecting the component on a form and pressing F1. For an example of a component topic, place any component on... more 

Creating the Help File 

You can use any tool you want to create the source file for a Windows Help file (in .rtf format). Delphi includes the Microsoft Help Workshop, which compiles your Help files and provides an online Help authoring guide. You can find complete information about creating Help files in the online guide for Help Workshop.
Composing Help files for components consists of the steps:

• Creating the entries.
• Making component Help context-sensitive.

 

Declaring the Register Procedure 

Registration involves writing a single procedure in the unit, which must have the name Register. The Register procedure must appear in the interface part of the unit, and (unlike the rest of Delphi) its name is case-sensitive. The following code shows the outline of a simple unit that creates and registers new components:  

Deriving a Property-editor Class 

Both the component library define several kinds of property editors, all of which descend from TPropertyEditor. When you create a property editor, your property-editor class can either descend directly from TPropertyEditor or indirectly through one of the property-editor classes described in the table below. The classes in the DesignEditors unit can be used for VCL applications. The list in the table below is not... more 

Editing the Property as a Whole 

You can optionally provide a dialog box in which the user can visually edit a property. The most common use of property editors is for properties that are themselves classes. An example is the Font property, for which the user can open a font dialog box to choose all the attributes of the font at once.
To provide a whole-property editor dialog box, override the property-editor class's Edit method.
Edit methods use the same Get and Set methods used in writing GetValue and SetValue methods. In fact, an Edit method calls both a Get method and a Set method. Because... more 

Implementing Commands 

When the command provided by GetVerb is selected in the designer, the ExecuteVerb method is called. For every command you provide in the GetVerb method, implement an action in the ExecuteVerb method. You can access the component that is being edited using the Component property of the editor.
For example, the following ExecuteVerb method implements the commands for the GetVerb method in the previous example.  

Making Component Help Context-sensitive 

Each component, property, method, and event topic must have an A footnote. The A footnote is used to display the topic when the user selects a component and presses F1, or when a property or event is selected in the Object Inspector and the user presses F1. The A footnotes must follow certain naming conventions:
If the Help topic is for a component, the A footnote consists of two entries separated by a semicolon using this syntax:  

Making Components Available at Design Time: Overview 

Making your components available at design time requires several steps:

• Registering components
• Providing Help for your component
• Adding property editors
• Adding component editors
• Compiling components into packages

Not all these steps apply to every component. For example, if you don't define any new properties or events, you don't need to provide Help for them. The only steps that are always necessary are registration and compilation.
Once your components have been registered and compiled into packages, they can be distributed to other developers and installed in the IDE. For information on installing packages in the IDE, see Installing component packages.... more 

Property Categories 

In the IDE, the Object Inspector lets you selectively hide and display properties based on property categories. The properties of new custom components can be fit into this scheme by registering properties in categories. Do this at the same time you register the component by calling RegisterPropertyInCategory or RegisterPropertiesInCategory. Use RegisterPropertyInCategory to register a single property. Use RegisterPropertiesInCategory to register multiple properties in a single function call. These functions are defined in the unit DesignIntf.
Note that it is not mandatory that you register properties or that you register all of the properties of a custom component... more 

Specifying Property Categories 

When you register properties in a category, you can use any string you want as the name of the category. If you use a string that has not been used before, the Object Inspector generates a new property category class with that name. You can also, however, register properties into one of the categories that are built-in. The built-in property categories are described in the following table:
Property categories  

Providing Help for Your Component 

When you select a standard component on a form, or a property or event in the Object Inspector, you can press F1 to get Help on that item. You can provide developers with the same kind of documentation for your components if you create the appropriate Help files.
You can provide a small Help file to describe your components, and your Help file becomes part of the user's overall Delphi Help system.
See the section Creating the Help file for information on how to compose the Help file for use with a component. 

Registering Components 

Registration works on a compilation unit basis, so if you create several components in a single compilation unit, you can register them all at once.
To register a component, add a Register procedure to the unit. Within the Register procedure, you register the components and determine where to install them on the Tool palette. in the IDE, the code required to register your component is added automatically. The steps for manually registering a component are:

• Declaring the Register procedure
• Writing the Register procedure

 

Registering Multiple Properties at Once 

Register multiple properties at one time and associate them with a property category using the RegisterPropertiesInCategory function. RegisterPropertiesInCategory comes in three overloaded variations, each providing a different set of criteria for identifying the property in the custom component to be associated with property categories.
The first variation lets you identify properties based on property name or type. The list is passed as an array of constants. In the example below, any property that either has the name "Text" or belongs to a class of type TEdit is registered in the category 'Localizable.'  

Registering One Property at a Time 

Register one property at a time and associate it with a property category using the RegisterPropertyInCategory function. RegisterPropertyInCategory comes in four overloaded variations, each providing a different set of criteria for identifying the property in the custom component to be associated with the property category.
The first variation lets you identify the property by the property's name. The line below registers a property related to visual display of the component, identifying the property by its name, "AutoSize".  

Registering the Component Editor 

Once the component editor is defined, it can be registered to work with a particular component class. A registered component editor is created for each component of that class when it is selected in the form designer.
To create the association between a component editor and a component class, call RegisterComponentEditor. RegisterComponentEditor takes the name of the component class that uses the editor, and the name of the component editor class that you have defined. For example, the following statement registers a component editor class named TMyEditor to work with all components of type TMyComponent:  

Registering the Property Editor 

Once you create a property editor, you need to register it with Delphi. Registering a property editor associates a type of property with a specific property editor. You can register the editor with all properties of a given type or just with a particular property of a particular type of component.
To register a property editor, call the RegisterPropertyEditor procedure.
RegisterPropertyEditor takes four parameters:

• A type-information pointer for the type of property to edit—this is always a call to the built-in function TypeInfo, such as TypeInfo(TMyComponent)__typeinfo(TMyComponent).
• The type of the component to which this editor applies—if this... more 

Setting the Property Value 

The property editor's SetValue method takes a string typed by the user in the Object Inspector, converts it into the appropriate type, and sets the value of the property. If the string does not represent a proper value for the property, SetValue should throw an exception and not use the improper value.
To read string values into properties, override the property editor's SetValue method.
SetValue should convert the string and validate the value before calling one of the Set methods. 

Specifying Editor Attributes 

The property editor must provide information that the Object Inspector can use to determine what tools to display. For example, the Object Inspector needs to know whether the property has subproperties or can display a list of possible values.
To specify editor attributes, override the property editor's GetAttributes method.
GetAttributes is a method that returns a set of values of type TPropertyAttributes that can include any or all of the following values:
Property-editor attribute flags  

Specifying Menu Items 

Override the GetVerbCount method to return the number of commands you are adding to the context menu. Override the GetVerb method to return the strings that should be added for each of these commands. When overriding GetVerb, add an ampersand (&) to a string to cause the following character to appear underlined in the context menu and act as a shortcut key for selecting the menu item. Be sure to add an ellipsis (...) to the end of a command if it brings up a dialog. GetVerb has a single parameter that indicates the index of the command.
The... more 

Specifying the Components 

Within the Register procedure, pass the component names in an open array, which you can construct inside the call to RegisterComponents.  

Specifying the Palette Page 

The palette category name is a string. If the name you give for the palette category does not already exist, Delphi creates a new category with that name. Delphi stores the names of the standard categories in string-list resources so that international versions of the product can name the categories in their native languages. If you want to install a component on one of the standard categories, you should obtain the string for the category name by calling the LoadStr function, passing the constant representing the string resource for that category, such as srSystem for the System category. 

Troubleshooting Custom Components (C++) 

A common problem when registering and installing custom components is that the component does not appear in the list of components after the package is successfully installed.
The most common causes for components not appearing in the list or on the palette:

• Missing PACKAGE modifier on the Register function
• Missing PACKAGE modifier on the class
• Missing #pragma package(smart_init) in the C++ source file
• Register function is not found in a namespace with the same name as the source code module name.
• Register is not being successfully exported. Use tdump on the .BPL to look for the exported function:

tdump -ebpl... more 

Using the IsPropertyInCategory Function 

An application can query the existing registered properties to determine whether a given property is already registered in a specified category. This can be especially useful in situations like a localization utility that checks the categorization of properties preparatory to performing its localization operations. Two overloaded variations of the IsPropertyInCategory function are available, allowing for different criteria in determining whether a property is in a category.
The first variation lets you base the comparison criteria on a combination of the class type of the owning component and the property's name. In the command line below, for IsPropertyInCategory to return True... more 

Using the RegisterComponents Function 

Within the Register procedure, call RegisterComponents to register the components in the classes array. RegisterComponents is a function that takes two parameters: the name of a Tool palette category and the array of component classes.
Set the Page parameter to the name of the category on the Tool palette where the components should appear. If the named category already exists, the components are added to that category. If the named category does not exist, Delphi creates a new palette category with that name.
Call RegisterComponents from the implementation of the Register procedure in one of the units that defines the... more 

Writing the Register Procedure 

Inside the Register procedure of a unit containing components, you must register each component you want to add to the Tool palette. If the unit contains several components, you can register them at the same time.
To register a component, call the RegisterComponents procedure once for each category of the Tool palette to which you want to add components. RegisterComponents involves three important things:

1. Specifying the components.
2. Specifying the palette page.
3. Using the RegisterComponents function.