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

BGCOLOR attribute	COLUMN attribute	COM-HANDLE attribute
CONTEXT-HELP-ID attribute	DYNAMIC attribute	FRAME attribute
FRAME-COL attribute	FRAME-NAME attribute	FRAME-ROW attribute
FRAME-X attribute	FRAME-Y attribute	HEIGHT-CHARS attribute
HEIGHT-PIXELS attribute	HELP attribute	HIDDEN attribute
INSTANTIATING-PROCEDURE attribute	HTML-CHARSET attribute	NAME attribute
NEXT-SIBLING attribute	NEXT-TAB-ITEM attribute	PARENT attribute
PREV-SIBLING attribute	PREV-TAB-ITEM attribute	PRIVATE-DATA attribute
ROW attribute	SENSITIVE attribute	TAB-POSITION attribute
TAB-STOP attribute	TYPE attribute	VISIBLE attribute
WIDGET-ID attribute	WIDTH-CHARS attribute	WIDTH-PIXELS attribute
WINDOW attribute	X attribute	Y attribute

Properties

Control-frame COM object properties¹

Control-Name property ²	Controls property	Height property ³
Left property ³	Name property ³	Top property ³
Widget-Handle property	Width property ³	–

Methods

Control-frame widget methods:

ADD-EVENTS-PROCEDURE( ) method	MOVE-AFTER-TAB-ITEM( ) method
MOVE-BEFORE-TAB-ITEM( ) method	MOVE-TO-BOTTOM( ) method
MOVE-TO-TOP( ) method	REMOVE-EVENTS-PROCEDURE( ) method

Control-frame COM object methods:⁴

LoadControls( ) method

–

Events

Developer events	BACK-TAB navigation key function event
END-ERROR universal key function event	ENTRY
GO universal key function event	HELP universal key function event
LEAVE	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.