utabex (TabEx)

The 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 utabex

TabEx widget with Tabs and Active Tab color properties set

For more information, see Specifying a Widget for a Field or Entity and Defining and Activating Tabs.

Widget Summary
Logical widget name:	TabEx
Maps to physical widget:	`utabex`
Default definition:	`TabEx=utabex`
Use for:	String fields with ValRep list.
Supported triggers:	See Triggers
Supported properties:	See Widget Properties
Supported in `egrid`(Grid) widget?	No
Supports MSAA? :	Yes, for testing purposes, including its child tabs and the tab strip scrollbar. For more information, see Accessibility.

Description

The 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 the utab widget, it provides many properties that enable you to customize its appearance and behavior.

Tip: The utabex widget is more flexible and customizable than the utab widget, and provides many properties that enable you to customize its appearance and behavior.

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 Tab in the .ini file. For example:

[widgets]
;Tab=utab   ; old mapping
Tab=utabex  ; new mapping
TabEx=utabex

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.

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.

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.

Tab Size

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.

Widget 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.

Scrolling

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.

Triggers

Widget Properties

General Properties

TabEx Widget Properties: General
Property Name	Technical Name	Dynamic?
Frame	Frame	Yes
Multiple Rows	Multiline	Yes
Fixed Tab Width (FixedWidth)	FixedWidth	No
Justified (Justify)	Justify	Yes
Attach to Window Border (attach)	Attach	Yes
Page Name and Tab Label Text	—	Yes
Widget Font (Font)	Font	Yes
Label Font (LabelFont)	LabelFont	Yes
Attach Margin (AttachMargin)	AttachMargin	Yes
Popup Rectangle (PopupRect)	PopupRect	Yes

Tab Properties

TabEx Widget Properties: Tabs
Property Name	Technical Name	Dynamic?	Remarks
Tab Width (TabWidth)	TabWidth	Yes	Size of the tabs, in character cells; overrides the Fixed Width property.
Tab Height (TabHeight)	TabHeight	Yes	Height of all tabs in the widget, in character cells
Tab Offset (TabOffset)	TabOffset	Yes	Offset of the tab strip in the widget.
Tab Space (TabSpace)	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 Frame is `true`.
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 `onTabButton` extended trigger when clicked.

Color Properties

TabEx Widget Properties: Color
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.
Foreground Color (ForeColor)	ForeColor	Yes	Text color. When not defined, the color is defined by Windows.
Active Background Color (BackColorSelect)	BackColorSelect	Yes	Color of the selected or active tab
Active Foreground Color (ForecolorSelect)	ForeColorSelect	Yes	Text color of the selected tab. Default is value of Foreground Color
Hover Background Color ( BackColorHover)	BackColorHover	Yes	Color of tab when the mouse cursor hovers over it.
Hover Foreground Color (ForeColorHover)	ForeColorHover	Yes	Color of the text when the mouse cursor hovers over the widget
Tab Line Color (TabLineColor)	TabLineColor	Yes	Color of the line just below the tab strip.
Active Tab Line Color (Active TabLineColor)	Active TabLineColor	Yes	Color of the tab line underneath the active tab
Frame Color (FrameColor)	FrameColor	Yes	Color of the widget border.
Tab Colors (TabColors)	TabColors	Yes	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.
Gradient Fill Style (BackColorFill)	BackColorFill	Yes	Determines whether the background color is styled with a flat or gradient color.

Image Properties

TabEx Widget Properties: Image
Property Name	Technical Name	Dynamic?	Remarks
Default Image (ImgDefault)	ImgDefault	Yes	Image defining the tab. The bigger the image the bigger the tab. Overrides the `Tabcolors`.
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.

Column Properties

Column Properties
Property	Technical Name	Dynamic?
Labels	Labels	Yes
Sorting	Formats	Yes
Alignment		Yes
Column Width		Yes

Drag and Drop Properties

Drag-and-Drop Properties
Property	Technical Name	Dynamic?
Supported Drag Formats (DragFormat)	DragFormat	Yes
Accepted Drop Formats (DropFormat)	DropFormat	Yes
Use Field Actions for All Drop Formats (DropActions)	DropAction	Yes

Properties set in .ini file or in ProcScript

Properties set in the .ini file or in ProcScript
Property	Technical Name	Dynamic?
Attach Margin (AttachMargin)	AttachMargin	Yes
LSortChg	LSortChg	Yes
LSortOrder	LSortOrder	Yes
Popup Rectangle (PopupRect)	PopupRect	Yes
Selection Delay (SelectionDelay)	SelectionDelay	Yes