OLE custom controls

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.

Setting up the custom 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:

1. Double-click the control,
   or select Properties from the control’s pop-up menu.

   The OLE Custom Control property sheet displays.

2. 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.

3. Specify values for other properties on the General
   property page and other pages as appropriate.

4. 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:

1. Select OLE Control Properties from the
   control’s pop-up menu or from the General property page.

2. 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.

Programming 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:

This syntax calls a function. You can capture its return value
in a variable of the appropriate datatype:

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.

---