Try OpenEdge Now
skip to main content
ABL Reference
Widget Reference : CONTROL-FRAME widget
 

CONTROL-FRAME widget

(Windows only; Graphical interfaces only)
A control-frame is a field-level widget that holds an ActiveX control that you select for your application from the OpenEdge AppBuilder. A control-frame is always created dynamically.
A control-frame has no visualization.
The AVM instantiates two separate but related objects when you create a control-frame:
*A control-frame widget
*A control-frame COM object
The widget itself provides a connection between the ActiveX control and the ABL user interface. When the widget is realized, the AVM creates a COM object that provides the real ActiveX control container support. Thus, the control-frame widget provides widget attributes and methods to manage the ABL side of the interface, while the control-frame COM object provides COM object properties and methods to gain access to the control itself.
When you insert an ActiveX control into your application, the AppBuilder creates a control-frame with the CREATE widget statement and specifies a default name (NAME attribute value) for the widget. The AppBuilder creates a design-time instance of the ActiveX control based on the control you select in the AppBuilder, making its design-time properties available to the AppBuilder. When you save your application, the AppBuilder saves the design-time instance in a separate file (with .wrx extension) for use at run time.
At run time, your application accesses the control indirectly through the control-frame widget. First, you use the COM-HANDLE attribute to return a component handle to the control-frame COM object. Second, you use this handle to access properties and methods of the control-frame COM object, which provide access to the ActiveX control itself.
This is a SmartViewer into which a developer, using the AppBuilder, has dropped a literal widget, a fill-in widget, and a control-frame widget. The control-frame widget holds a Crescent spin control, as shown:

Attributes

Control-frame widget attributes

Properties

Control-frame COM object properties1

1 The name of an ActiveX control that is contained by the control-frame COM object

2 Mapped to a corresponding control-frame widget attribute.

3 Mapped to a corresponding control-frame widget attribute.

4 Mapped to a corresponding control-frame widget attribute.

5 Mapped to a corresponding control-frame widget attribute.

6 Mapped to a corresponding control-frame widget attribute.

Methods

Control-frame widget methods:
Control-frame COM object methods:2

Events

BACK-TAB navigation key function event
END-ERROR universal key function event
GO universal key function event
HELP universal key function event
TAB navigation key function event

Notes

*You must use the AppBuilder to incorporate one or more ActiveX control instances into an ABL application. The AppBuilder, operating in design mode, provides the facilities to set design-time properties for ActiveX controls.
*After incorporating ActiveX controls into an application with the AppBuilder, the resulting window file, when compiled and executed, interacts with the ActiveX controls at run time.
*To access a loaded ActiveX control at run time, use the control-frame COM-HANDLE attribute to get a handle to the control-frame COM object. To return a handle to the control, use the design-time name of the ActiveX control as a property of the control-frame COM object. For example:
/* Control Frame widget */
DEFINE VARIABLE hCFwid    AS HANDLE     NO-UNDO.
/* Control Frame COM Object */
DEFINE VARIABLE hCFcom    AS COM-HANDLE NO-UNDO.
/* ActiveX Control */
DEFINE VARIABLE hDateSpin AS COM-HANDLE NO-UNDO.

/* Control-frame created with handle hCFwid and loaded with ActiveX
   control named DateSpin. */

ASSIGN
  hCFcom    = hCFwid:COM-HANDLE
  hDateSpin = hCFcom:DateSpin.
As an alternative, use the COM object Controls property to return a handle to a control collection. Use the control collection Item(1) method call to return the handle to the ActiveX control. (This control collection object provides support for searching multiple ActiveX controls in a control-frame, available in a future release of OpenEdge.)
*You can use a single ActiveX control more than once in a single window file. Each time you insert the control, the AppBuilder creates a separate control-frame for it with a unique NAME attribute value.
*Some control-frame widget attributes correspond to control-frame COM object properties so that setting one sets the other. You must directly set and read all ActiveX control run-time properties using a handle (also a COM-HANDLE value) to the control.
*To trap control-frame events, use the ON statement, as with any ABL widget. To trap events for the associated ActiveX control, you must use ActiveX control (OCX) event procedures. Also, to "apply" an ActiveX control event from ABL, run the event procedure directly, like any ABL internal procedure. The APPLY statement has no effect on ActiveX controls. For more information, see the reference entries for the PROCEDURE statement and RUN statement.
*ABL control-frame events are mutually exclusive with associated ActiveX control events. That is, only one event handler, either an ON trigger or an event procedure, fires for a single event.

See also

CREATE widget statement, The chapter on ActiveX control container support in OpenEdge Development: Programming Interfaces

1 Accessible using a component handle set to the control-frame COM-HANDLE attribute value.The name of an ActiveX control that is contained by the control-frame COM object.Mapped to a corresponding control-frame widget attribute.

2 Accessible using a component handle set to the control-frame COM-HANDLE attribute value.