Wednesday, January 21, 2004

Object Inspector API

Starting in C#Builder, the ability to provide an arbitrary selection to the Object Inspector was added to the native Delphi Win32 Open Tools API. There are two mechanisms you can use to get a selection into the OI. The first, and most complicated is to implement the IOTAPropInspSelection interface and several other optional interfaces. The idea is to provide a list of IProperty interfaces (defined in DesignIntf.pas). There are also several new interfaces you can implement in addition to IProperty to get additional features like more customized control over painting a particular item, custom drop-down editors, etc.. but that is a subject for another blog entry. The second mechanism simply allows a list of native Delphi Win32 object instances to be selected.

IOTAPropInspSelection is a very rich and complicated interface to implement, but gives the most level of control over virtually all aspects of the OI, including the hiding and showing of the description and hot commands panes. The description pane is a way to provide a simple help text that describes the currently selected property. The hot commands pane is an area where an arbitrary number of "hot-links" are displayed that the user can click in order to invoke functionality related to the entire selection.

INTAPropInspServices is a shortcut. Using this interface (which is queried for from the IOTAPropInspServices interface), you can simply provide an array of TPersistent object instances, and the OI will then select and display the property list of published properties. You can even call RegisterPropertyEditor in DesignIntf to register specific property editors in order to customize the behaviour in much the same way a Delphi component writer would register custom property editors for their design-time components. In fact, this is the exact mechanism that is used to display information about the specific items in the project manager. When the user selects an item in the PM, that item is asked for a TPersistent that represents its specific properties and is selected into the OI by calling INTAPropInspServices.SelectObjects(). One "gotcha" is that as long as that item is selected in the OI, it must remain a live instance. If you free the instance too early, the OI and the property editors will continue to attempt access to the now dead instance, which is a recipe for disaster.

There are some differences in the API between C#Builder and Delphi 8, but a simple diff of the PropInspAPI.pas files will reveal them. Also there is a reasonably detailed reference comments in that file that describes what each method/property does on the interfaces.