utabex widget enables users to navigate through a collection of contained forms by
clicking a tab to display the form. The
utabex widget is highly customizable, allowing extensive
control over the appearance and behavior of the tabs. Uniface provides a logical widget called TabEx, which is mapped to
|Logical widget name:||TabEx|
|Maps to physical widget:||
|Use for:||String fields with ValRep list.|
|Supported triggers:||See Triggers|
|Supported properties:||See Widget Properties|
|Supports MSAA? :||Yes, for testing purposes, including its child tabs and the tab strip scrollbar. For more information, see Accessibility.|
utabex widget provides a way of organizing data
or organizing an application. You can use it to present multiple instances of the same form, but
with different data retrieved. Or you can display instances of completely different forms. Unlike
utab widget, it provides many properties that enable you to customize its appearance and
utabex widget is more flexible and
customizable than the
utab widget, and provides many properties that enable you to customize its appearance and
You can switch all fields that use the Tab widget to use the TabEx widget by
assigning the physical widget
utabex to the logical widget
the .ini file. For example:
[widgets] ;Tab=utab ; old mapping Tab=utabex ; new mapping TabEx=utabex
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.
Defining and Activating Contained Forms in Tabs
The collection of forms is defined by the field's
ValRep, and each form called by the
utabex widget must be explicitly activated using an
activate statement. You can use the exec operation of the parent form where the
utabex widget is drawn
to initially activate all the forms that are called as tab pages. For example:
; Form containing the utabex widget operation exec ; Create ValRep putitem/id $valrep(TABFLD), "mail", "mail.png!Mail" putitem/id $valrep(TABFLD), "contacts", "contacts.png!Contacts" putitem/id $valrep(TABFLD), "calendar", "calendar.png!Calendar" ; Create instances of contained forms newinstance "MAILLST", "mail" newinstance "CONTACTLST", "contacts" newinstance "AGENDA", "calendar" TABFLD = "mail" activate TABFLD end; exec
- Create the ValRep of the tab field. The Representation part of each ValRep item can contain text, both an image and text, or just an image. For more information, see ValRep.
- Create a new instance of each contained form in the ValRep.
- Assign one of the instances to the tab field.
- Activate the instance specified by the tab field.
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 Formto 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
0in $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.
It is good practice to let the labels in the tab
widget define the size of the tab, rather than using the Tab Width property.
This ensures that the
utabex widget design is independent of the screen resolution.
If you are using an image in the tab, you can use an image with a small width which is stretched to fill the tab according to the label size.
The size of the
utabex widget can be changed if its
Attach property is set. After the parent form is resized, the Resized extended
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.
By default, the tab strip is displayed as a single horizontal line. If the sum of the tab widths exceeds the width of the tab widget, scroll buttons are displayed to enable the user to scroll tabs into view. Each click on a scroll button moves the tab strip exactly the width of the left-most tab in the horizontal tab strip.
|Property Name||Technical Name||Dynamic?|
|Property Name||Technical Name||Dynamic?||Remarks|
|Tab Width (TabWidth)||TabWidth||Yes||Size of the tabs, in character cells; overrides the Fixed Width property.|
|TabHeight||Yes||Height of all tabs in the widget, in character cells|
|TabOffset||Yes||Offset of the tab strip in the widget.|
|TabSpace||Yes||Space between the tabs in the widget.|
|Tab Line Width (TabLineWidth)||TabLineWidth||Yes||Width of the tab line in pixels; maximum is 4 pixels.|
|Frame Width (FrameWidth)||FrameWidth||Yes||Width of the border line when
|Tab Position (TabPos)||TabPos||No||Position of the tab strip in the tab widget area.|
|Tab Orientation (TabOrientation)||TabOrientation||Yes||Orientation of tabs in a tab strip: horizontal, stack, or accordion.|
|Tabs Alignment (TabsAlignment)||TabsAlignment||Yes||Alignment of tabs in a horizontal strip.|
|Label Alignment (LabelHalign)||LabelHalign||Yes||Defines how labels are aligned In stacked tabs.|
|Label Image Alignment (ImageLabelAlign)||ImageLabelAlign||Yes||Defines the position of the image relative to the label text when the tab or button label specifies both an image and a text.|
|LabelImage Size (ImgSize)||ImgSize||No||Defines the size used to display an image in widgets and menu items, when both an image and text are defined for the value.|
|Padding||Padding||Yes||Size of the padding around the label content of a TabEx tab, in pixels.|
|Tab Button (button)||Button||Yes||Determines whether the active tab displays
a button, such as a Close button, that executes the
|Property Name||Technical Name||Dynamic?||Remarks|
|Background Color (BackColor)||BackColor||Yes||
Background color, including the tab strip. The tab area is overlaid by a form but the tab strip area can show the background color.
Text color. When not defined, the color is defined by Windows.
Color of the selected or active tab
Text color of the selected tab. Default is value of Foreground Color
Color of tab when the mouse cursor hovers over it.
Color of the text when the mouse cursor hovers over the widget
Color of the line just below the tab strip.
Color of the tab line underneath the active tab
Color of the widget border.
A comma separated list of colors for the individual tabs; can include more or fewer colors than the number of tabs; overridden by the Image Default.
Determines whether the background color is styled with a flat or gradient color.
|Default Image (ImgDefault)||ImgDefault||Yes|| Image defining the tab. The bigger the
image the bigger the tab. Overrides the
|Hover Image (ImgHover)||ImgHover||Yes||Image of the tab when the mouse cursor hovers over it|
|Active Image (ImgSelect)||ImgSelect||Yes||Image of the tab when it is selected.|
|Tab Strip Image (TabStripImage)||TabStripImage||Yes||Image that fills the area beyond the tabs in a single-line horizontal tab with the given image.|
|Tab Button Image (TabButtonImg)||TabButtonImg||Yes||Image to be used for the tab button, if enabled.|
|Tab Button Image Hover (TabButtonImgHover)||TabButtonImgHover||Yes||Image that is displayed when the mouse cursor hovers over the tab button. if enabled.|
|Supported Drag Formats (DragFormat)||DragFormat||Yes|
|Accepted Drop Formats (DropFormat)||DropFormat||Yes|
|Use Field Actions for All Drop Formats (DropActions)||DropAction||Yes|