Using Component Wrappers
Go Up to Controlling an Imported Object
If you generated a component wrapper for your server object, writing your COM client application is not very different from writing any other application that contains VCL components. The server object's properties, methods, and events are already encapsulated in the VCL component. You only need to assign event handlers, set property values, and call methods.
To use the properties, methods, and events of the server object, see the documentation for your server. The component wrapper automatically provides a dual interface where possible. Delphi determines the VTable layout from the information in the type library.
In addition, your new component inherits certain important properties and methods from its base class.
ActiveX wrappers
You should always use a component wrapper when hosting ActiveX controls, because the component wrapper integrates the control's window into the VCL framework.
The properties and methods an ActiveX control inherits from Vcl.OleCtrls.TOleControl allow you to access the underlying interface or obtain information about the control. Most applications, however, do not need to use them. Instead, you use the imported control the same way you would use any other VCL control.
Typically, ActiveX controls provide a property page that lets you set their properties. Property pages are similar to the component editors some components display when you double-click them in the form designer. To display an ActiveX control's property page, right-click and choose Properties.
The server application determines the way you use the most frequently imported ActiveX controls. However, ActiveX controls use a standard set of notifications when they represent the data from a database field. See Vcl.OleCtrls.TOleControl for information on how to host such ActiveX controls.
Automation object wrappers
The wrappers for Automation objects let you control how you want to form the connection to your server object:
First, the ConnectKind property indicates whether the server is local or remote and whether you want to connect to a server that is already running, or if a new instance should be launched. When connecting to a remote server, you must specify the machine name using the RemoteMachineName property.
Second, once you have specified the ConnectKind, there are three ways you can connect your component to the server:
- You can explicitly connect to the server by calling the component's Connect method.
- You can tell the component to connect automatically when your application starts up by setting the AutoConnect property to true.
- You do not need to explicitly connect to the server. The component automatically forms a connection when you use one of the server's properties or methods using the component.
Calling methods or accessing properties is the same as using any other component:
TServerComponent1.DoSomething;
TServerComponent1->DoSomething();
Handling events is easy, because you can use the Object Inspector to write event handlers. Note, however, that the event handler on your component may have slightly different parameters than those defined for the event in the type library. Specifically, pointer types (var parameters and interface pointers) are changed to Variants. You must explicitly cast var parameters to the underlying type before assigning a value. Interface pointers can be cast to the appropriate interface type using the as operator.
For example, the following code shows an event handler for the ExcelApplication event, OnNewWorkBook. The event handler has a parameter that provides the interface of another CoClass (ExcelWorkbook). However, the interface is not passed as an ExcelWorkbook interface pointer, but rather as an OleVariant.
procedure TForm1.XLappNewWorkbook(Sender: TObject; var Wb:OleVariant);
begin
{ Note how the OleVariant for the interface must be cast to the correct type }
ExcelWorkbook1.ConnectTo((iUnknown(wb) as ExcelWorkbook));
end;
void _fastcall TForm1::XLappNewWorkbook(TObject *Sender, ExcelWorkbookPtr Wb)
{
ExcelWorkbook1->ConnectTo(Wb);
}
In this example, the event handler assigns the workbook to an ExcelWorkbook component (ExcelWorkbook1). This demonstrates how to connect a component wrapper to an existing interface by using the ConnectTo method. The ConnectTo method is added to the generated code for the component wrapper.
Servers that have an application object expose a Quit method on that object to let clients terminate the connection. Quit typically exposes functionality that is equivalent to using the File menu to quit the application. The code to call the Quit method is generated in your component's Disconnect method. If it is possible to call the Quit method with no parameters, the component wrapper also has an AutoQuit property. AutoQuit causes your controller to call Quit when the component is freed. If you want to disconnect at some other time, or if the Quit method requires parameters, you must call it explicitly. Quit appears as a public method on the generated component.