For more information, see Specifying a Widget for a Field or Entity.
|Logical widget name:||FormContainer|
|Maps to physical widget:||
|Use for:||String field|
|Supported triggers:||trigger Resized|
|Supported properties:||See Widget Properties|
|Supports MSAA? :||No|
You can use the
ucontainer widget to embed a
non-modal form within another form. For example, you can:
- Dynamically display different forms within a parent form.
- Display multiple instances of the same form within a parent form.
- Embed tabs within a parent form.
- Display the same entity more than once in a form without the use of component subtypes.
The contained form can itself have a
ucontainer widget, thereby providing multiple levels of form nesting.
A form that is embedded using the
- Must have its Window
Type property set to
Contained Form. This property automatically defines a form as non-modal and attached, and overlays the previous form.
- Must be explicitly activated using an activate ProcScript statement.
- Can only be assigned to the
ucontainerfield by its instance name.
The value of the
ucontainerwidget must be an instance name, not a form name. Although the instance name can be assigned using the Initial Value property of the field, it is more typically assigned in ProcScript.
ucontainer widget has no value, nothing
is displayed, and the field cannot have focus.
Activating and Deactivating Embedded Forms
An embedded form must first be activated and then
assigned to a
ucontainer. You can choose to activate all required instances at once, or you can
instantiate and assign instances as required.
Unassigning a form instance does not delete or deactivate it. To delete an embedded form instance from memory, use deleteinstance, or fire its quit or accept trigger with default behavior.
Note: The form instance will not be deleted if you
return (-1) in the quit trigger.
The instance name can be reused, but the embedded form must be activated again before it can again be assigned to the form container widget.
Activating and Assigning an Embedded Form
For example, the following code in the
exec operation of a parent form creates and activates a
new instance of CHILDFORM, assigns it to the
ucontainer widget field FORMCON_FLD, and gives it
; parent form operation exec newinstance "CHILDFORM", "ChildForm_1" activate "ChildForm_1".EXEC() FORMCON_FLD = "ChildForm_1" setformfocus "ChildForm_1" edit end; exec
Focus and Triggers
ucontainer widget itself is display-only;
none of its triggers are activated by editing the contents of the embedded form. The resize trigger is fired when the widget is resized by the user or by ProcScript.
It is not possible for the
to get focus. If no form instance has been assigned to the
ucontainer widget, focus remains
with the parent form, even if the user clicks on the
Only the embedded form itself can have focus, and it must get this directly by a user mouse click, or the setformfocus statement.
Once an embedded form has been activated and
assigned to a
ucontainer widget, the embedded form's triggers can be fired, including
getFocus and loseFocus.
When an embedded form is unassigned or deactivated, focus is returned to the parent form.
At runtime, when the instance name is assigned to the form container field, the embedded instance is displayed at the location of the form container field in the layout of the parent.
The embedded form has its own layout management.
If the embedded form is smaller than the area of the form container widget, it is stretched to fit
the container's area. If the embedded form is too large to fit in area of
scrollbars are displayed on the borders of the form container.
The size of the
ucontainer can be changed if
its Attach property is set. After the parent form is resized, the
Resized trigger is fired, with the new widget dimensions
as input parameters. You can add code to this trigger that displays a different form that is more
appropriate to the new size.