uOcxContainer (OcxContainer)

The uOcxContainer widget embeds a Microsoft OCX control into a form component, and maps OCX properties and OCX events to fields and triggers. You can use ProcScript to activate OCX methods and let the OCX control activate widget triggers to respond to OCX events.

For more information, see Defining OCX Container Widgets.

Widget Properties

The OCX’s native properties can be retrieved from, and reapplied to the OCX using $properties. However, these properties cannot be edited. The frequency with which the OCX native properties are reapplied is controlled by the setting specified for the Set Native Properties property.

Triggers

• trigger detail
• trigger valueChanged
• trigger receiveMessage
• OCX-specific widget triggers. For more information, see Interactive Widget Triggers for OCX Controls .

Default Logical Widget

Uniface provides a logical widget called OcxContainer, which is mapped to uOcxContainer:

OcxContainer=uOcxContainer

Grid and MSAA Support

Description

An OCX control is a COM component with a visual representation. Almost every standard Windows application has a COM component that is also available as an OCX control. These OCX controls can be used in Uniface using the COM interface and the OCX container widget.

The uOcxContainer widget enables you to:

• Map Open Widget Interface (OWI) properties to OCX properties
• Map OCX events to Uniface triggers
• Implement widget triggers to respond to OCX events
• Enable call-out to OCX methods

Limitations

• The uOcxContainer widget does not support windowless activation of the OCX control, so all OCX controls are handled as windowed controls.
• The uOcxContainer widget is always displayed as LTR (Left to Right), regardless of the environment and the field layout Direction (RTL) property.
• OCX controls must support the Data Execution Protection (DEP) policy. Ensure that you are using the most recent version of the control. For more information, see Data Execution Protection.

Registration and Licenses

The OCX must be registered with your system. Normally, the OCX installation software handles registration of the OCX. When you select an OCX container as the widget type, you can view the OCX controls available to in the OCX Name property. Only registered OCXs are listed.

OCX controls are often licensed. To deploy Form components that use OCX controls, you need to deploy the licenses as well. Uniface supplies a mechanism to retrieve the license information from the OCX and encapsulates it into the Form component, so it will be available in all circumstances.

Note:  Uniface supplies only a license distribution mechanism, not the licenses themselves. You must obtain the appropriate licenses for your OCX controls.

OCX Signatures

Uniface needs the signatures of the OCX control to activate its methods (COM call-out). One OCX control can result in multiple signatures. You can generate the signatures or define them manually.

The signatures are stored in the repository in the COM subsystem and overwrite any signature having the same name. After generation, the signatures are automatically compiled and available.

For each OCX method, Uniface generates one operation that contains as many parameters as there are OCX parameters, including all the optional OCX parameters. If you use such an operation as is, you must supply all the parameters that the method expects, otherwise the OCX control might not work correctly. If you do not want to supply some of the optional OCX parameters, use the Signature Editor to create new operations with only those parameters you want to use.

Mapping OCX Properties and Events to Fields and Triggers

The uOcxContainer widget does not have a fixed set of interactive triggers because each OCX has its own set of events. You can map OCX events to a limited set of Uniface triggers (detail, valueChanged, and receiveMessage), or you can implement widget triggers to respond to specific OCX events. This is more flexible and usually preferable, although there are some limitations.For more information, see Interactive Widget Triggers for OCX Controls .

One OCX property can be mapped to the field value. Changing the field value in ProcScript automatically sets the OCX property and the other way around. The properties of the OCX control are provided in its signature.

For information about the properties, events, and event parameters of the OCX control, consult the technical documentation of the OCX control.

Instantiation and Call-out

The OCX object is instantiated after the form on which it is drawn is instantiated and executes a show, edit or display statement. The handle to the OCX object is then available and can be retrieved in ProcScript using the function $ocxhandle. If a signature is generated for the OCX control, it can be accessed from 4GL using its handle. (Previously this could be done only by using the perform ProcScript statement. )

You can use this handle to activate the public methods of the OCX control. The handle to the OCX control is destroyed if the instance of the form in which it lives is deleted. Typically, the handle of an OCX control is assigned to a component variable, which has the same scope as the OCX handle.

For example:

operation exec
  ;$myOcxHandle$ is component variable of type public handle

  show
  $myOcxHandle$ = $ocxhandle ("OCXFIELD")
  $myOcxHandle$->autostart("true")
  edit
end; exec

Testing

When the form containing the OCX is run in the Uniface IDE, the OCX control runs in the IDE process rather than in your application. This means that the OCX is loaded in a type of development mode (AmbientUserMode=false) that might have some restrictions for the OCX. For more information, see Testing Form Components Containing OCX Controls.