ucontainer (FormContainer)

The ucontainer widget embeds a non-modal form in a field of the current form. Uniface provides a logical widget called FormContainer, which is mapped to ucontainer.

For more information, see Specifying a Widget for a Field or Entity.

Widget Overview
Logical widget name: FormContainer
Maps to physical widget:

ucontainer

Default definition:

FormContainer=ucontainer

Use for: String field
Supported triggers: trigger Resized
Supported properties: See Widget Properties
Supported in egrid(Grid) widget? No
Supports MSAA? : No

Description

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 ucontainer widget:

  • 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 ucontainer field by its instance name.

    The value of the ucontainer widget 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.

If the ucontainer widget has no value, nothing is displayed, and the field cannot have focus.

Widget Properties

FormContainer Widget Properties

Property

Technical Name

Dynamic?

3-D Effect (3d)

3D

No

Attach to Window Border (attach)

attach

Yes

Frame

frame

No

Attach Margin (AttachMargin)

AttachMargin

Yes

Popup Rectangle (PopupRect)

PopupRect

Yes

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 write 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 focus:

; 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

The 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 ucontainer widget 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 ucontainer field.

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.

Layout

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 ofucontainer widget, 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.