The OLE control button in the Controls menu gives you the option of inserting an object or a custom control in an OLE container. When you select an OLE custom control (ActiveX control), you fix the container's type and contents. You cannot choose later to insert an object and you cannot select a different custom control.
Each ActiveX control has its own properties, events, and functions. Preventing the ActiveX control from being changed helps avoid errors later in scripts that address the properties and methods of a particular ActiveX control.
The PowerBuilder custom control container has properties that apply to any ActiveX control. The ActiveX control itself has its own properties. This section describes the purpose of each type of property and how to set them.
PowerBuilder properties
For OLE custom controls, PowerBuilder properties have two purposes:
-
To specify appearance and behavior of the container, as you do for any control
You can specify position, pointer, and drag-and-drop settings, as well as the standard settings on the General property page (Visible, Enabled, and so on).
-
To provide default information that the ActiveX control can use
Font information and the display name are called ambient properties in OLE terminology. PowerBuilder does not display text for the ActiveX control, so it does not use these properties directly. If the ActiveX control is programmed to recognize ambient properties, it can use the values PowerBuilder provides when it displays text or needs a name to display in a title bar.
To modify the PowerBuilder properties for the custom control:
-
Double-click the control, or select Properties from the control's pop-up menu.
The OLE Custom Control property sheet displays.
-
Give the control a name that is relevant to your application. You will use this name in scripts. The default name is ole_ followed by a number.
-
Specify values for other properties on the General property page and other pages as appropriate.
-
Click OK when you are done.
Documenting the control
Put information about the ActiveX control you are using in a comment for the window or in the control's Tag property. Later, if another developer works with your window and does not have the ActiveX control installed, that developer can easily find out what ActiveX control the window was designed to use.
ActiveX control properties
An ActiveX control usually has its own properties and its own property sheet for setting property values. These properties control the appearance and behavior of the ActiveX control, not the PowerBuilder container.
To set property values for the ActiveX control in the control:
-
Select OLE Control Properties from the control's pop-up menu or from the General property page.
-
Specify values for the properties and click OK when done.
The OLE control property sheet might present only a subset of the properties of the ActiveX control. You can set other properties in a script.
For more information about the ActiveX control's properties, see the documentation for the ActiveX control.
You make an ActiveX control do its job by programming it in scripts, setting its properties, and calling its functions. Depending on the interface provided by the ActiveX control developer, a single function call might trigger a whole series of activities or individual property settings, and function calls may let you control every aspect of its actions.
An ActiveX control is always active -- it does not contain an object that needs to be opened or activated. The user does not double-click and start an OLE server. However, you can program the DoubleClicked or any other event to call a function that starts ActiveX control processing.
Setting properties in scripts
Programming an ActiveX control is the same as programming automation for insertable objects. You use the container's Object property to address the properties and functions of the ActiveX control.
This syntax accesses a property value. You can use it wherever you use an expression. Its datatype is Any. When the expression is evaluated, its value has the datatype of the control property:
olecontrol.Object.ocxproperty
This syntax calls a function. You can capture its return value in a variable of the appropriate datatype:
{ value } = olecontrol.Object.ocxfunction ( { argumentlist } )Errors when accessing properties
The PowerBuilder compiler does not know the correct syntax for accessing properties and functions of an ActiveX control, so it does not check any syntax after the Object property. This provides the flexibility you need to program any ActiveX control. But it also leaves an application open to runtime errors if the properties and functions are misnamed or missing.
PowerBuilder provides two events (ExternalException and Error) for handling OLE errors. If the ActiveX control defines a stock error event, the PowerBuilder OLE control container has an additional event, ocx_event. These events allow you to intercept and handle errors without invoking the SystemError event and terminating the application. You can also use a TRY-CATCH exception handler.
For more information, see Handling errors.
Using events of the ActiveX control
An ActiveX control has its own set of events, which PowerBuilder merges with the events for the custom control container. The ActiveX control events appear in the Event List view with the PowerBuilder events. You write scripts for ActiveX control events in PowerScript and use the Object property to refer to ActiveX control properties and methods, just as you do for PowerBuilder event scripts.
The only difference between ActiveX control events and PowerBuilder events is where to find documentation about when the events get triggered. The ActiveX control provider supplies the documentation for its events, properties, and functions.
The PowerBuilder Browser provides lists of the properties and methods of the ActiveX control. For more information, see OLE information in the Browser.
New versions of the ActiveX control
If you install an updated version of an ActiveX control and it has new events, the event list in the Window painter does not add the new events. To use the new events, you have to delete and recreate the control, along with the scripts for existing events. If you do not want to use the new events, you can leave the control as is -- it will use the updated ActiveX control with the pre-existing events.
