Using the Editors

A tab control widget contains one or more cards which are accessed by clicking on a graphic index tab associated with each card. This is particularly useful for providing a multi-layered control panel.

Notes:

• This widget is only available for Windows and Motif applications.

• Tab decks (and tab cards) are not interchangeable between the two platforms. Screens using Motif tab decks must run on the Motif platform; screens using Windows tab decks must run on the Windows platform.

Creating and Editing a Tab Control

A tab control consists of two kinds of elements:

• The tab deck widget: a container for a series of tab cards. When you initially create a tab deck, two tab cards are created within it.

• The tab card widget: a container on which additional widgets (such as buttons, text fields, grids) can be placed. Associated with each tab card is a field that is rendered as the card's index tab.
  

  Figure 16-1 A sample tab dialog screen illustrating the parts of a tab control.

How to Create and Populate a Tab Control

1. Choose CreateExtended WidgetsTab Deck or .
2. On your application screen, click once to create a default-sized tab control or drag out the frame to the desired dimension. Initially the control consists of a tab deck and two tab cards.
3. Add additional tab cards by choosing CreateExtended WidgetsTab Card and then clicking on the deck; the tab card icon is .

   Where the mouse click occurs in relation to the existing index tabs determines the placement of the new tab card. Clicking to the far right adds it to the end of the deck, clicking to the far left adds it to the beginning of the deck, and clicking in the middle of the tab deck adds it between two index tabs of existing tab cards.

   Note: A new tab card cannot be placed outside the borders of a tab deck.

4. Conversely, you can delete one or both of the initial tab cards to create a deck of one card or no cards, respectively.
5. Add widgets (such as dynamic labels, single line text, check boxes, and so on) to the topmost tab card by doing either of the following:

   • Drag existing widgets to fall within the tab deck border. Widgets can be moved and copied from within the current screen, from another screen, or from an open repository entry.

   • Choose the widget from the Create menu or select the icon from the Create toolbar and click within the tab deck border.

---

Manipulating a Tab Deck and Tab Cards

• Click on the topmost card anywhere below the index tab.

How to Make a Tab Card the Topmost Card

• Click once on the card's index tab to bring the card to the top of the deck.

How to Select a Tab Card for Editing

• With a tab card already positioned as topmost card, click on the card's index tab to bring focus to the card.

  Note: Two clicks are required to bring a card into focus in order to allow multiple selection of items appearing on different cards. (For instance, you can select an item from one card, then click a tab on a different card to make it the topmost, then shift+click to select a second item on the new topmost card.)

How to Change the Tab Card Order

You can change the order (left to right) in which the tab cards appear.

• Change the card's number property in the Properties window (refer to the description of the Card Number property for more information).

How to Move, Copy, or Delete a Tab Deck

When you move, copy, or delete a tab deck, the members of the tab deck are moved, copied, or deleted as well.

General Notes About Tab Controls

While working with tab controls, be aware that:

• Only widgets that lie within the geometrical boundaries of a tab deck can belong to a particular card in that tab deck.

• A widget cannot belong to more than one tab card.

• A tab card cannot exist outside of a tab deck.

• An entire tab deck—with its related tab cards—can be nested within a single tab card.

• If you select a group of widgets on multiple cards, you can simultaneously align them with the alignment commands (such as EditAlign).

• Widgets cannot be "rubberbanded" with the mouse in order to select multiple widgets on a tab card.

• The logical keys NCARD and PCARD move to the next and previous tab cards, respectively.

• The index tabs operate differently in Windows and Motif applications. Refer to the "Label" description.

• Only Motif 2.2 supports having both text and an image on a tab. Earlier versions can only have text or an image.

Creating a Tab Dialog Screen

A typical use for tab controls is in dialog windows. Such a dialog window would consist of a single tab control. Each card in the tab deck would provide a series of user-selectable choices. Outside of the tab control, there would typically be a series of push buttons to indicate user acceptance of the choices made.

How to Build a Tab Dialog Screen

1. Create a tab deck on a blank screen.
2. Click on the index tab of a card to bring it to the top.
3. Add widgets (such as text widgets, check boxes and option menus) for that particular card's function.
4. Create selection groups for check boxes and radio buttons in order to limit the number of selections within a group (refer to "Grouping Selection Widgets").
5. Visually group widgets within a tab card by creating a box widget or line widget (refer to "Using Boxes and Lines").
6. Create push buttons for the screen below the tab deck. With the desired push button selected, set the IdentityDefault/Cancel property to specify the push button's behavior (refer to "Assigning Default and Cancel").
7. With the screen selected, set the IdentityDialog property to Yes (refer to "Creating a Dialog Box").
   

   Figure 16-2 Two views of a tab deck, showing two of the cards in the deck. Notice the push button controls which are placed on the screen outside the tab deck.

---

Tab Control Properties

This sections describes special properties appearing in the Properties window for tab cards and tab decks. In addition, there are runtime properties for tab controls. For more information, refer to "Accessing Tab Controls" in Application Development Guide.

Tab Deck Properties

The following properties of tab decks require special mention:

Identity

Hidden

If set to yes, this hides the entire tab deck and overrides any Hidden property settings you have made for individual cards.

Conceal Tabs

Hide the index tabs at runtime (decks will still have visible tabs in the editor). By choosing Yes, the topmost card in the deck is displayed at runtime without an index tab.

If set to Yes, users will be unable to change the tab card and the logical keys NCARD and PCARD will not advance the card; but the top card can be changed by setting the deck's topmost_card property.

You cannot specify the color of the tab deck itself. It is derived from your Windows color scheme. Setting BG Color affects only the background color of label widgets placed on the tab deck.

Font

Render the labels on the index tabs. A single setting affects all the index tabs in a particular deck.

Tab Card Properties

For tab cards, the following categories in the Properties window should be noted:

Identity

Label

Enter the text to appear on a card's index tab.

Note: For Motif applications, all the index tabs in a tab deck have the same length. Also, the index tabs will not be resized when the labels are shortened. Only Motif 2.2 supports having both text and an image on a tab.

Hidden

As with other widgets, the Hidden property can be set to Yes/No/Always, allowing individual cards to be either displayed or not at runtime. The Always value, however, has no relevance to the positioning of the tab cards (which it does with other widgets). A tab card which has its Hidden value set to Always cannot have its value set to No at runtime.

Card Number

Indicate where in the sequence of cards a particular tab card is located. Cards appear left to right based on a the Card Number property. If you change a card number, the new value must be between 1 and the total number of cards on the deck. The card numbers for all the cards in the deck will be readjusted to reflect the new ordering.

Length

Determine the width of the card's index tab.

Setting the Color properties on the tab card has no effect in Windows. It is derived from your Windows color scheme.

Focus

Tab cards have three sets of entry and exit events. To understand the distinction between them, keep in mind that a tab card consists of two distinct components: a field that is displayed as the card's index tab, and a set of widgets that the tab card contains. At runtime, the index tab of the topmost card in a deck is one of the fields on the screen and can gain focus. Consequently, the index tab has its own entry and exit events.

For more information about entry and exit functions specific to tab cards, refer to "Tab Control Events" in Application Development Guide.

Card Entry and Exit

For the Card Entry and Card Exit Functions, the index tab field is considered to be a widget "contained on the tab card."

Card Entry Function

Enter the name of the function to be called when one of the widgets contained in the tab card is about to gain focus.

Card Exit Function

Enter the name of the function to be called when focus leaves one of the widgets contained in the tab card and a widget not contained in the tab card is about to gain focus.

In addition to the events that occur when a tab card is exposed or hidden, the Expose Function is called on screen entry for the card that will be topmost, and the Hide Function is called on screen exit for the current topmost card. These events occur even if the tab deck is hidden. However, the Expose and Hide Functions do not execute when the tab deck's Hidden property is used to hide or unhide a tab deck.

Expose Function

Enter the name of the function to be called when the card becomes the topmost card.

Hide Function

Enter the name of the function to be called when another card is about to become the topmost card.

The index tab has the following two functions:

Tab Entry Function

Enter the name of the function to be called when the index tab gains focus.

Tab Exit Function

Enter the name of the function to be called when the index tab loses focus.

The order of execution for the above entry functions is as follows:

1. Expose Event
2. Card Entry Event
3. Tab Entry Event

Not all events may happen at the same time. For example, focus can go directly onto a widget on the tab card—bypassing the tab index—if a widget on the card receives focus. In that case, the tab entry event does not occur. Similarly, if the card was exposed as part of an earlier event (at screen entry or when it was made topmost), the expose event does not occur when focus enters the tab card.

A situation when all three entry events occur is when the screen is being opened and the tab deck is the first widget to get focus.

Exit events occur in the corresponding opposite order.

Validation

Validation Function

Specify the name of a function to be called when the card is validated. This validation function will be triggered when the tab card is validated via a call to sm_validate, or when the entire screen is validated via a call to sm_s_val. In either case, the tab card validation will be triggered after all the individual widgets on the respective tab card are validated.

To validate all the tab cards in a deck, call sm_validate on the tab deck and this will iteratively call validation functions on all the tab cards in the deck, whether they are hidden or not.

Note: Do not call sm_validate on the tab card as part of the tab card's validation function, since this will produce an infinite loop.

Active Pixmap

Attach a pixmap file to the index tab of a tab card.

Note: Only Motif 2.2 supports having both text and an image on a tab. Earlier versions can only have text or an image.