EmbeddedWindow property

(Windows only; GUI for .NET only)

The handle to an ABL window whose client area is embedded in the client area of the specified .NET control container. This control container can be either a Progress.Windows.MdiChildForm or a Progress.Windows.WindowContainer (which you can add to any Progress.Windows.Form). After a .NET form with this embedded client area is displayed, you can interact with its ABL widgets using the supported widget attributes, methods, and events as if they were displayed in the original ABL window.

Data type: HANDLE

Access: PUBLIC Readable/Writeable

Applies to: Progress.Windows.MDIChildForm class, Progress.Windows.WindowContainer class

To reset a previously set instance of this property on a control container:

The current ABL window referenced by this property must not yet be realized.
If the current ABL window referenced by this property is realized, you must first delete this window before resetting the property to reference another ABL window.

Note that when you embed an ABL window in a .NET form, only the client area of the window is embedded. ABL ignores all other components of the ABL window, including border controls, menu bar, message area, and status area. For more information, see the reference entries for the Progress.Windows.MDIChildForm class and Progress.Windows.WindowContainer class.

When you embed the client area of an ABL window in a supported .NET control container, the various attributes, methods, and events of the embedded ABL window either function normally, change behavior, or have no function (are ignored), depending on the element. The following tables describe how these elements are affected by embedding the ABL window. For more information on the attributes, methods, and events of an ABL window, see the WINDOW widget reference entry.

Note: You can use enhanced logging to trace the occurrence of attributes and methods in your application that are ignored when you access them on an embedded ABL window. For more information, see the IgnoredOps entry type described in the LOG-ENTRY-TYPES attribute reference entry.

Table 126 lists those attributes that work on an embedded ABL window in the same way as on a non-embedded window.

Table 126: Attributes unchanged on an embedded ABL window 

BGCOLOR	CONTEXT-HELP-FILE1	DROP-TARGET
DYNAMIC	FIRST-CHILD	HANDLE
HWND	INSTANTIATING-PROCEDURE	KEEP-FRAME-Z-ORDER
LAST-CHILD	MENU-KEY2	MENU-MOUSE2
MOUSE-POINTER	NAME	NEXT-SIBLING
NUM-DROPPED-FILES	NUM-SELECTED-WIDGETS2	POPUP-MENU2
PREV-SIBLING	PRIVATE-DATA	SCROLL-BARS3
THREE-D	TYPE	WINDOW

1You can specify a context help file for all frames within an embedded window by setting its CONTEXT- HELP-FILE attribute. However, ABL does not support the CONTEXT-HELP attribute for embedded windows (see Table 128). Instead, you must set the HelpButton property on the containing form in order to enable the context-help button on the form's caption bar. This containing form can be an MDI parent form, an MDI child form, or a form that contains a WindowContainer object. Note that MDI applications generally do not use the context-help feature on their forms; this feature is most commonly used in dialog boxes. 2These attributes work on an embedded window because they apply to actions performed on the frames and field-level widgets within the window. 3 If you set the SCROLL-BARS attribute to TRUE on an embedded window, ABL handles the scrolling of frames within that window. The value of the AutoScroll property of the embedding form or WindowContainer has no effect on the scrolling features of these frames.

Table 127 describes attributes whose behavior on an embedded ABL window differs from how they behave on a non-embedded window.

Table 127: Attributes modified on an embedded ABL window

Attributes	Behavior changes
PARENT	This attribute specifies the parent of a window in an ABL window hierarchy. An embedded window cannot participate in this hierarchy. So, the PARENT attribute always returns the Unknown value (?) for an embedded window. ABL ignores any setting of this attribute on an embedded window.
SENSITIVE HIDDEN VISIBLE	The SENSITIVE attribute indicates if a widget is enabled to receive keyboard and mouse input. The default value for the SENSITIVE attribute on a window is TRUE. Setting this attribute to FALSE on an embedded window disables input to the embedded frames, but it does not disable the non-client portions of an embedding MDI child form or any form that contains a Progress.Windows.WindowContainer object. Similarly, setting VISIBLE to FALSE or HIDDEN to TRUE on an embedded window hides the embedded frames but does not hide the .NET control container into which they have been embedded.
X Y ROW COLUMN	When queried on an embedded window, the X, Y, ROW, and COLUMN attributes return 0, 0, 1, and 1, respectively, because these attributes return position values relative to the embedded window's container. The embedded window's position is fixed at the upper-left corner of the container’s client area. ABL ignores any setting of these attributes on an embedded window. You must set the position of any Progress.Windows.WindowContainer within its containing form using appropriate .NET properties.
WIDTH-CHARS WIDTH-PIXELS HEIGHT-CHARS HEIGHT-PIXELS	The WIDTH-CHARS, WIDTH-PIXELS, HEIGHT-CHARS, and HEIGHT-PIXELS window attributes return the width and height, respectively, of the client area of the embedded window, just as they do in a non-embedded window. ABL ignores any setting of these attributes on an embedded window. You must set the size of any Progress.Windows.WindowContainer within its containing form using appropriate .NET properties. Note: The FULL-WIDTH-* and FULL-HEIGHT-* attributes include the size of the non-client areas of a window and, as such, are ignored for embedded windows (see Table 128).
VIRTUAL-HEIGHT-CHARS VIRTUAL-HEIGHT-PIXELS VIRTUAL-WIDTH-CHARS VIRTUAL-WIDTH-PIXELS	These attributes work for embedded windows. They determine the size of the virtual window for scrolling frames in windows. As noted for the SCROLL-BARS attribute in Table 126, ABL handles the scrolling of frames within an embedded window. For embedded windows, ABL maintains a minimum size for the virtual window; you cannot make the size of this virtual window smaller than the physical size of the embedded window container because that would cause the container to become smaller.

Table 128 lists attributes on an embedded ABL window that ABL ignores. You can read or write these attributes without error, but they have no effect because their function has no meaning for the client area of an ABL window embedded in a .NET form. For the corresponding behavior in a .NET form object, use the appropriate .NET class members.

Table 128: Attributes ignored on an embedded ABL window

ALWAYS-ON-TOP	CONTEXT-HELP	CONTROL-BOX
DCOLOR	FGCOLOR1	FONT1
FULL-HEIGHT-CHARS2	FULL-HEIGHT-PIXELS2	FULL-WIDTH-CHARS2
FULL-WIDTH-PIXELS2	ICON	MAX-BUTTON
MAX-HEIGHT-CHARS3	MAX-HEIGHT-PIXELS3	MAX-WIDTH-CHARS3
MAX-WIDTH-PIXELS3	MENU-BAR	MESSAGE-AREA
MESSAGE-AREA-FONT	MIN-BUTTON	MIN-HEIGHT-CHARS4
MIN-HEIGHT-PIXELS4	MIN-WIDTH-CHARS4	MIN-WIDTH-PIXELS4
PFCOLOR	RESIZE	SCREEN-LINES
SHOW-IN-TASKBAR	SMALL-ICON	SMALL-TITLE
STATUS-AREA	STATUS-AREA-FONT	TITLE
TOP-ONLY	WINDOW-STATE	–

1These attributes only affect a window's message area and are not inherited by frames placed inside the window. Thus, they will have no affect when the frames are removed from a window and placed inside a form. 2These attributes always return the Unknown value (?) when queried on an embedded window because there is no concept of "full" window size for an embedded window. 3These attributes always return the Unknown value (?) when queried on an embedded window because there is no concept of "maximum" window size for an embedded window. 4These attributes always return zero (0) when queried on an embedded window. An embedded window's size is determined by the size of its container, and that container's size is independent of the values of these ABL attributes.

Table 129 describes how methods are supported on an embedded ABL window.

Table 129: Method support on an embedded ABL window 

Methods	Support provided by ABL
END-FILE-DROP( ) GET-DROPPED-FILE( )	These methods work for file drag-and-drop operations on an embedded window.
GET-SELECTED-WIDGET( )	This method returns the handle of the selected frame in an embedded window.
LOAD-MOUSE-POINTER( )	This method specifies the mouse pointer to display when the pointer is moved over the embedded frames of the window. When a window is embedded in a form, the mouse pointer changes when the pointer is over these embedded frames, but it does not change when the pointer is over the non-client areas of the form. If you want the non-client areas of the form to have the same pointer as the embedded window, you must set the form pointer separately using the Cursor property on the form.
LOAD-ICON( ) LOAD-SMALL-ICON( ) MOVE-TO-BOTTOM( ) MOVE-TO-TOP( )	ABL ignores execution of these methods on an embedded window.

For an embedded ABL window, ABL frame-level (ENTRY, LEAVE, etc.) and field-level events (mouse button clicks, etc.) fire normally on the embedded frames and the widgets they contain (see the "Handle-based Object Events Reference" section). However, most window-level events do not fire because the ABL window is not visualized. You must handle .NET form events in ABL using .NET event handlers (see the "Class Events Reference" section). Table 130 describes how ABL supports window-level events for embedded ABL windows.

Table 130: Event support on an embedded ABL window 

Events	Support provided by ABL
DROP-FILE-NOTIFY	This event fires when a file is dragged and dropped onto the client area of an embedded window whose DROP-TARGET attribute is set to TRUE.
WINDOW-RESIZED	This event fires whenever the embedded window container is resized, as follows: A Progress.Windows.MdiChildForm can be resized either programmatically or by the user interacting with the form on screen. A Progress.Windows.WindowContainer can be resized only programmatically, typically in response to handling a .NET form Resize event. By handling the ABL WINDOW-RESIZED event in a trigger, you can resize the embedded frames and their contents to fit the new size of their container.
ENTRY LEAVE PARENT-WINDOW-CLOSE WINDOW-CLOSE1 WINDOW-MAXIMIZED2 WINDOW-MINIMIZED WINDOW-RESTORED2	The AVM never generates these events for an embedded window.

1As with any handle-based object, you must delete the embedded window widget when you no longer need it. You can do this in an OpenEdge GUI for .NET application, for example, by handling the .NET Closed (or FormClosed) event on the form that contains the embedded window. 2ABL does not map the WINDOW-MAXIMIZED and WINDOW-RESTORED events from the corresponding .NET form events. However, for a Progress.Windows.MdiChildForm, the WINDOW-RESIZED event fires on the embedded window when the child form is maximized or restored.

OpenEdge Release 10.2B

Copyright © 2009 Progress Software Corporation