utab (Tab)

Description

A tab widget is a collection of non-modal forms (contained forms) that overlay each other as they are made active. All the forms called by the utab widget must be explicitly activated using an activate statement.

You can use the exec operation of the parent form where the utab widget is drawn to initially activate all the forms that are called as tab pages.

ValRep Handling

The values assigned to the pages in the utab widget comprise the ValRep for the widget. The widget interprets the Value as the name of the contained form or form instance name to be assigned as a tab page. The Representation is the text displayed on the tab at runtime.

The ValRep can be set in the Widget Properties dialog as the Page Name and Tab Label Text properties. You can change the pages that are called by changing the ValRep values using the $valrep function. For more information, see ValRep.

Contained Forms

The forms activated by a tab widget must have the Window Type set to Contained Form. This property automatically defines a form as non-modal and attached, and overlays the previous form.

When defining and testing a tab widget, take into account the following points:

• If you use the syntax definition NED to disable a contained form, the tab label is not dimmed. This is because the contained form is separate from the tab label.
• You cannot make a contained form non-editable from the tab widget definition.
• You cannot test a contained form individually. If you want to test a contained form separately from the tab widget, you must change the window type of the form from Contained Form to the relevant window type.
• The contained forms in the tab widget are non-modal attached forms, so if a user changes a field or key field in a contained form, and then edits a field on the parent form, the leaveModifiedKey of the entity and the loseFocus triggers of the field are not activated. This is because the field does not lose focus and therefore cannot be validated. If there is an error, for example an illegal duplicate key is created, it will not be detected until the user tries to store the occurrence in the database.

  To force field validation for each entity in a contained form, in the loseFocus trigger of the entity, assign the primary and candidate key fields to themselves and write an explicit validateocc or validatekey statement. This forces Uniface to fill the field with values, so that you can explicitly perform the field validation. For example:

  ; Form component
  trigger loseFocus 
    PK1 = PK1
    PK2 = PK2
    validatekey
  end; loseFocus

• Uniface supports a two-phase close for Accept and Quit actions in attached component instances, and thus in contained forms. (By definition, a contained form is an attached instance.)

  Depending on the original request (Accept or Quit), the accept or quit trigger of all involved tab instances is fired, starting with the child instances and then from the bottom up to the instance that originated the close request. If one of the involved instances leaves the accept or quit trigger with a negative value in $status the close sequence is canceled without closing any of the involved instances, even if some instances have already returned 0 in $status. ProcScript in the accept or quit trigger of every instance determines whether the instance agrees to the Close request.

• The CLOSECONTEXT initialization setting determines whether a Quit request is sent to the contained form or the parent form when the Close caption button is clicked.
• Panels are not shown in a contained form. If the form containing the tab widget has a panel, that panel will be used by the contained form. However, for user-defined buttons in the panel to work in the contained form, the operations also need to be defined in the individual contained forms.

Widget Properties