%TS_TABSET

Create and manipulate a tabbed dialog

WSupported on Windows
USupported on Unix
VSupported on OpenVMS
NSupported in Synergy .NET
return = %TS_TABSET(subfunction, arg[, ...])

or

xcall TS_TABSET(subfunction, arg[, ...])

Return value

return

A value specific to the subfunction. (^VAL)

Arguments

subfunction

One of the following: (n)

DTS_CREATE

Create a tab set.

DTS_WINDOW

Add a window to a tab set.

DTS_LIST

Add a list to a tab set.

DTS_BUTTON

Add a button to a tab set. (Windows only)

DTS_BUTTONSET

Modify the button set for a tab set. (Windows only)

DTS_ACTIVE

Bring a tab to the front.

DTS_ENABLE

Enable a tab in a tab set.

DTS_DISABLE

Disable a tab in a tab set.

DTS_REMOVE

Remove a tab from a tab set.

DTS_SELECT_ATTR

Modify the attributes for the selected tab. (Unix, VMS only)

DTS_NONSELECT_ATTR

Modify the attributes for non-selected tabs. (Unix, VMS only)

DTS_DEFAULT

Modify the default tab settings.

DTS_GETDEFAULT

Obtain the default tab settings.

DTS_NUMTABS

Obtain the number of tabs in a tab set.

DTS_TABINDEX

Obtain the tab index for a window or list.

DTS_TABINFO

Obtain information for a tab.

DTS_TABSET

Obtain the ID of the tab set that contains a specified window or list. (Unix, VMS only)

DTS_CTRCONTEXT

Set context of window on tab.

arg

One or more arguments, depending on subfunction.

Discussion

%TS_TABSET enables you to create and manipulate a tabbed dialog. See the individual subfunctions for details.

Examples

See the %TS_PROCESS Examples and the DTS_CREATE Examples.

DTS_CREATE

window_id = %TS_TABSET(DTS_CREATE, name, rows, cols, [pre_tab_string], 
&         [post_tab_string][, style])

or

xcall TS_TABSET(DTS_CREATE, name, rows, cols, [pre_tab_string], [post_tab_string]
&     [, style])

Return value

window_id

The window ID of the created tab set container window. (^VAL)

Arguments

name

A name for the created tab set (a maximum of 15 characters). (a)

rows

The maximum number of rows that a contained window may contain. (n)

cols

The maximum number of columns that a contained window may contain. (n)

pre_tab_string

(optional) The string to put before each tab in a tab set container window. (Unix, OpenVMS only) (a)

post_tab_string

(optional) The string to put after each tab in a tab set container window. (Unix, OpenVMS only) (a)

style

(optional) One or more of the following options, combined using .BOR. or the vertical bar (|) operator. (Windows only) (n)

DTS_NONE

None of the following styles apply. (default)

DTS_MULTILINE

Multiple lines of tabs.

DTS_VERTICAL

Left or right side.

DTS_BOTTOM

Bottom (or right if DTS_VERTICAL is also specified).

DTS_RIGHT

Right (or bottom if DTS_VERTICAL is not specified).

Discussion

The DTS_CREATE subfunction of %TS_TABSET creates a tab set. A tab set can have up to 24 tabs. Since the window created is a UI Toolkit window, U_WINDOW can be used to place, remove, move, or delete the tab set as a whole. Deleting the tab set does not delete its member windows, but does disassociate them from the tab set. (See Understanding tab set processing for more information.) Note also that the containing window is by default local to the current environment (for instance, it will be deleted by a subsequent E_EXIT), but it may also be promoted to global status with U_GBLWND.

Rows and cols must be greater than or equal to the height and width, respectively, of the window specified with DTS_WINDOW.

On Unix and OpenVMS, pre_tab_string and post_tab_string are used to define the two delimiter strings. The maximum length of each string is 10 characters. If pre_tag_string or post_tab_string is not passed, the default strings “/” and “\” will be used, respectively. If post_tab_string is specified as an empty string (“”), the string specified in pre_tab_string will be repeated after the last tab. If pre_tab_string is an empty string, the container window’s border acts as a border for the first tab.

Tab sets on Windows

When a tab set is created, the global default style is used. The global default style is determined by either the style specified in a prior call to %TS_TABSET(DTS_DEFAULT), the style specified by the TABSET_STYLE initialization setting in synergy.ini, or Toolkit’s default style, which is to display tabs on a single line (scrolling as necessary) on the top of the window.

You can override the default style currently in effect by specifying style for the DTS_CREATE subfunction. The style options for a tabbed dialog cannot be changed after a tab set has been created. Style options should be combined using .BOR. or the vertical bar (|) operator.

To restore the default style in effect back to the Toolkit default style, specify DTS_NONE.

If DTS_MULTILINE is specified, the tabs display on multiple rows if they cannot fit on one row. This will use more container space for the tabs, so you may need to adjust the number of rows and columns specified in rows and cols to allow the contained windows to display fully. If tabs are displayed on the top or left, contained windows will be shifted down or to the right, respectively. This means that rows or columns at the bottom or right of the contained window may be truncated.

If DTS_VERTICAL is specified, tabs are displayed vertically on the left or right side of the contained windows with the text rotated 90 degrees to follow the vertical border. Setting DTS_VERTICAL forces DTS_MULTILINE to be set.

If DTS_RIGHT or DTS_BOTTOM is specified along with DTS_VERTICAL, the tabs are displayed on the right side. If DTS_RIGHT or DTS_BOTTOM is specified and DTS_VERTICAL is not, the tabs are displayed on the bottom.

DTS_DEFAULT subfunction for setting the default style

Examples

On Unix and OpenVMS, the following example sets the tab delimiter to “|”, by setting pre_tab_string to “|” and post_tab_string to “”, as shown below.

tabid = %ts_tabset(DTS_CREATE, "Tabset1", 15, 50, "|", "")

On Windows, the following example specifies multi-line tabs on the bottom of the tab set.

tabid = %ts_tabset(DTS_CREATE, "Tabset2", 10, 30,,,
&       DTS_MULTILINE .bor. DTS_BOTTOM) 

Example tab set

DTS_WINDOW

index = %TS_TABSET(DTS_WINDOW, tab_id, window_id, method, [elb][, tooltip])

or

xcall TS_TABSET(DTS_WINDOW, tab_id, window_id, method, [elb][, tooltip])

Return value

index

The tab index of the new tab if successful, or 0 if not. (^VAL)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

window_id

The ID of a window to add to the tab set. (n)

method

The name of the subroutine to call when this tab is selected. (a)

elb

(optional) The .elb filename in which to find method. (a)

tooltip

(optional) The text of a ToolTip to be displayed if the mouse rests over the tab. (a)

Discussion

The DTS_WINDOW subfunction of %TS_TABSET adds a window to a tab set.

The window referenced by window_id is visually transformed into a tab page: It is placed adjacent to the tabs, a tab is created for it, the border is turned off, and the window is made to appear to be a tabbed page.

When a tab is created, the window is sized to fit the tab. If the window is larger than the tab, the display area is resized, and scroll bars appear. If the window is smaller than the tab, the blank portion of the tab is filled with the background window color. When a tab is resized, the window display area is also resized.

Note

When a window is added to a tab set, UI Toolkit changes the color of the window to the color palette entry specified by the g_tabfacecolor global variable, if this variable is set to a value in the range 1 through 16. On Windows, g_tabfacecolor is set to 9 by default if Windows themes are used. On Unix and OpenVMS or on Windows if themes are not enabled, the default is 0, a setting that instructs Toolkit to leave a window’s color as is.

When a window is removed from a tab set, Toolkit does not restore the original color for the window. If the color was changed when the window was added to a tab set, that change will stand until the program or the user changes the renditions for the window.

Additionally, if unframed fields are displayed or cleared (initialized) after the input window for the fields is added to a tab set, Toolkit will apply the Input Field Display rendition or the Cleared Input Field rendition to the fields—renditions that might not match the g_tabfacecolor palette entry (if that has been applied to the field). In this case, do one of the following:

  • Before performing the display (I_DISPLAY or I_DSPFLD) or clear (I_INIT), use U_REND to set the Input Field Display rendition or the Cleared Input Field rendition to g_tabfacecolor.
  • After performing the display or clear, overwrite the renditions using W_AREA. For example:
xcall w_area(wndid, WA_COPY, WAC_WTOP, WA_COLOR, g_tabfacecolor)

For more information, see g_tabfacecolor.

On Unix and OpenVMS, the tabs are rendered as a single-line window. By default, slashes are used to delimit the tabs, and the underscore attribute is used to distinguish the inactive tabs from the active tab. (See under Understanding tab set processing for an example.)

DTS_LIST

index = %TS_TABSET(DTS_LIST, tab_id, list_id, method, [elb][, tooltip])

or

xcall TS_TABSET(DTS_LIST, tab_id, list_id, method, [elb][, tooltip])

Return value

index

The tab index of the new tab if successful, or 0 if not. (^VAL)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

list_id

The ID of a list to add to the tab set. (n)

method

The name of the subroutine to call when this tab is selected. (a)

elb

(optional) The .elb filename in which to find method. (a)

tooltip

(optional) The text of a ToolTip to be displayed if the mouse rests over the tab. (a)

Discussion

The DTS_LIST subfunction of %TS_TABSET adds a list to a tab set.

This subfunction is similar to the DTS_WINDOW subfunction, except that it’s for lists. By default, when a tab is created, the list is sized to fit the tab regardless of the number of list items you’ve specified to display. If the tab is resized, the list is also resized. To override this behavior, specify the NOAUTOSIZE list class option.

DTS_BUTTON

xcall TS_TABSET(DTS_BUTTON, tab_id, name, [DSB_TEXT|DSB_BITMAP], [type_data],
&     [method], [elb], [select_char], [position][, tooltip])

Return value

The return value of this subfunction is undefined; we recommend you use XCALL TS_TABSET in this case.

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

name

The name of the button to add (a maximum of 30 characters). (a)

DSB_TEXT | DSB_BITMAP

(optional) The button face type. Pass DSB_TEXT for text (default) or DSB_BITMAP for a graphic. (n)

type_data

(optional) Text for the button face if the type is DSB_TEXT, or the filename of the graphic if the type is DSB_BITMAP. (a)

method

(optional) The name of the subroutine to call when this button is selected. (a)

elb

(optional) The name of the library from which to draw method. (a)

select_char

(optional) The quick-select character. (a)

position

(optional) The position the button will be inserted in the button set. (a or n)

tooltip

(optional) The text of a ToolTip to be displayed when the mouse pointer rests over the button. (a)

Discussion

This subfunction is only supported on Windows. (On Unix and OpenVMS, it is ignored.)

The DTS_BUTTON subfunction of %TS_TABSET adds a button to a tab set. If there are no existing buttons, a default button set is created.

By default, button sets are placed at the bottom of the tab set, are left-justified, and can have as many buttons on a row as will fit before the row wraps. You can change these defaults with B_BUTTONSET.

The tab set will expand downward or to the right to accommodate the buttons, which may cause your window to extend beyond the bottom or right side of the application window. Also, buttons are a standard size; text that exceeds that size will not be visible.

For information on the arguments for this subroutine, see the DSB_ADD Discussion. All the comments in the Discussion apply to tab sets.

DTS_BUTTONSET

xcall TS_TABSET(DTS_BUTTONSET, tab_id, [placement], [per_row_col], [justification]
&     [, button_name])

Return value

The return value of this subfunction is undefined; we recommend you use XCALL TS_TABSET in this case.

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

placement

(optional) One of the following: (n)

DSB_BOTTOM

The set of buttons will be placed horizontally along the bottom of the window with a maximum of per_row_col buttons per row. (default)

DSB_RIGHT

The set of buttons will be placed vertically along the right side of the window with a maximum of per_row_col buttons per column.

per_row_col

(optional) The maximum number of buttons to place on a row if DSB_BOTTOM is specified, or on a column if DSB_RIGHT is specified. The default behavior is to display as many as will fit and wrap to the next row or column. (n)

justification

(optional) One of the following: (n)

DSB_BEGIN

The buttons will be left-justified if DSB_BOTTOM is specified, or positioned towards the top if DSB_RIGHT is specified. (default)

DSB_CENTER

The buttons will be centered along the designated side.

DSB_END

The buttons will be right-justified if DSB_BOTTOM is specified, or positioned towards the bottom is DSB_RIGHT is specified.

button_name

(optional) The name of the default button. (a)

Discussion

This subfunction is only supported on Windows. (On Unix and OpenVMS, it is ignored.)

The DTS_BUTTONSET subfunction of %TS_TABSET modifies the button set for a tab set.

If a tab set container and its contained window both have buttons, the following rules are used to determine which button is the default:

If the E_STATE option D_RETURNBTN is set, the default button will be selected if you press Enter, no matter what field you’re on in the window. If button_name is not specified and D_RETURNBTN is set, the first button in the window is the default.

DTS_ACTIVE

index = %TS_TABSET(DTS_ACTIVE, tab_id[, new_index])

or

xcall TS_TABSET(DTS_ACTIVE, tab_id[, new_index])

Return value

index

If new_index is passed, the index of the previously active tab. Otherwise, the index of the currently active tab. (^VAL)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

new_index

(optional) The index of the tab to bring to the front, which will be processed on the next call to %TS_PROCESS. (See %TS_PROCESS for more information.) (n)

Discussion

The DTS_ACTIVE subfunction of %TS_TABSET brings a tab to the front.

DTS_ENABLE

xcall TS_TABSET(DTS_ENABLE, tab_id, index)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

index

The index of the tab to enable. (n)

Discussion

The DTS_ENABLE subfunction of %TS_TABSET enables a tab in a tab set.

Index is the tab index returned from the DTS_WINDOW or DTS_LIST subfunctions.

DTS_DISABLE

xcall TS_TABSET(DTS_DISABLE, tab_id, index)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

index

The index of the tab to disable. (n)

Discussion

The DTS_DISABLE subfunction of %TS_TABSET disables a tab in a tab set. Be aware that the disabled tab is not rendered visually. For behavior that is more Windows-like, we recommend removing the tab.

Index is the tab index returned from the DTS_WINDOW or DTS_LIST subfunctions.

DTS_REMOVE

curr_index = %TS_TABSET(DTS_REMOVE, tab_id, index)

or

xcall TS_TABSET(DTS_REMOVE, tab_id, index)

Return value

curr_index

The index of the active tab. (^VAL)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

index

The index of the tab to remove. (n)

Discussion

The DTS_REMOVE subfunction of %TS_TABSET removes a tab from a tab set. (It does not remove the tab window from memory. See Understanding tab set processing for more information.)

Index is the tab index returned from the DTS_WINDOW or DTS_LIST subfunctions.

Note

Although UI Toolkit may change the color palette entry for a window when the window is added to a tab set, Toolkit does not restore the original palette entry setting for the window when it is removed from the tab set. See DTS_WINDOW for information.

DTS_SELECT_ATTR

status = %TS_TABSET(DTS_SELECT_ATTR, tab_id, [option+attribute][, palette#])

or

xcall TS_TABSET(DTS_SELECT_ATTR, tab_id, [option+attribute][, palette#])

Return value

status

True if successful; false if not. (^VAL)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

option

Pass DA_SET to set attributes or DA_CLR to clear attributes. (n)

attribute

One of the following flags defined in tools.def: (n)

A_NONE = No attributes.

A_U = Underlined.

A_R = Reverse.

A_RU = Reverse, underlined.

A_B | A_I = Blinking (on Unix and OpenVMS) or italic (on Windows). “I” can be substituted whenever “B” appears in the following flags.

A_BU = Blinking, underlined.

A_BR = Blinking, reverse.

A_BRU = Blinking, reverse, underlined.

A_H = Highlighted.

A_HU = Highlighted, underlined.

A_HR = Highlighted, reverse.

A_HRU = Highlighted, reverse, underlined.

A_BH = Blinking, highlighted.

A_BHU = Blinking, highlighted, underlined.

A_BHR = Blinking, highlighted, reverse.

A_BHRU = Blinking, highlighted, reverse, underlined.

A_ALL = All attributes (same as A_BHRU).

palette#

(optional) A palette number, in the range 1 to 16, to set for the selected tab. (n)

Discussion

This subfunction is only supported on Unix and OpenVMS. (On Windows, it is ignored.)

The DTS_SELECT_ATTR subfunction of %TS_TABSET sets the rendition for the selected tab in a tab set. These renditions apply to the currently selected tab as well as any tab selected in the future.

Using DTS_SELECT_ATTR, you can set and clear various attributes for the selected tab to modify the effect of which tab is selected. See the example below.

If option+attribute is not passed, the default attribute will be used. The default is DA_CLR+A_U, unless it is modified through %TS_TABSET(DTS_DEFAULT). It is important to note that whatever attributes are specified using DTS_SELECT_ATTR overwrite the default attributes for a selected tab. For example, if DA_SET+A_R is specified, and the current default is DA_SET+A_U, the attribute of the selected tab will be reverse only.

If palette# is not passed, the default color will be used. The initial default color palette number is 1. If palette# is specified, but not between 1 and 16, a fatal error will be generated.

Changes to the selected tab’s renditions will take effect either at the next call to the %TS_PROCESS function using tab_id, or within a call to %TS_PROCESS as a result of returning from a tab method.

Examples

The following example sets the rendition for the selected tab, in this case, Tab 2, in tab set tabid to be reverse video, and clears reverse non-selected tabs.

if (%TS_TABSET(DTS_SELECT_ATTR, tabid, DA_SET+A_R))
  status = %TS_TABSET(DTS_NONSELECT_ATTR, tabid, DA_CLR+A_U)

Example rendition setting

DTS_NONSELECT_ATTR

status = %TS_TABSET(DTS_NONSELECT_ATTR, tab_id, [option+attribute][, palette#])

or

xcall TS_TABSET(DTS_NONSELECT_ATTR, tab_id, [option+attribute][, palette#])

Return value

status

True if successful; false if not. (^VAL)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

option

Pass DA_SET to set attributes or DA_CLR to clear attributes. (n)

attribute

One of the following flags defined in tools.def: (n)

A_NONE = No attributes.

A_U = Underlined.

A_R = Reverse.

A_RU = Reverse, underlined.

A_B | A_I = Blinking (on Unix and OpenVMS) or italic (on Windows). “I” can be substituted whenever “B” appears in the following flags.

A_BU = Blinking, underlined.

A_BR = Blinking, reverse.

A_BRU = Blinking, reverse, underlined.

A_H = Highlighted.

A_HU = Highlighted, underlined.

A_HR = Highlighted, reverse.

A_HRU = Highlighted, reverse, underlined.

A_BH = Blinking, highlighted.

A_BHU = Blinking, highlighted, underlined.

A_BHR = Blinking, highlighted, reverse.

A_BHRU = Blinking, highlighted, reverse, underlined.

A_ALL = All attributes (same as A_BHRU).

palette#

(optional) A palette number, in the range 1 to 16, to set for the selected tab. (n)

Discussion

This subfunction is only supported on Unix and OpenVMS. (On Windows, it is ignored.)

The DTS_NONSELECT_ATTR subfunction of %TS_TABSET sets the rendition for non-selected tabs in a tab set. These renditions apply to the currently non-selected tabs as well as any unselected tabs in the future.

Using DTS_NONSELECT_ATTR, you can set and clear various attributes for the non-selected tabs to modify the effect of which tabs aren’t selected. See the %TS_TABSET Examples.

If option+attribute is not passed, the default attribute will be used. The default is DA_SET+A_U, unless it is modified through %TS_TABSET(DTS_DEFAULT). It is important to note that whatever attributes are specified using DTS_NONSELECT_ATTR overwrite the default attributes for unselected tabs. For example, if DA_SET+A_R is specified, and the current default is DA_SET+A_U, the attribute of the non-selected tab will be reverse only.

If palette# is not passed, the default color will be used. The initial default color palette number is 1. If palette# is specified, but not between 1 and 16, a fatal error will be generated.

Changes to the non-selected tab’s renditions will take effect either at the next call to the %TS_PROCESS function using tab_id, or within a call to %TS_PROCESS as a result of returning from a tab method.

See the DTS_SELECT_ATTR Examples.

DTS_DEFAULT

status = %TS_TABSET(DTS_DEFAULT,DTS_SELECT_ATTR, [option+attribute][, palette#])
status = %TS_TABSET(DTS_DEFAULT,DTS_NONSELECT_ATTR, [option+attribute][, palette#])
status = %TS_TABSET(DTS_DEFAULT,DTS_TABTEXT, [pre_tab_string][, post_tab_string])
status = %TS_TABSET(DTS_DEFAULT,DTS_STYLE [, style])

Return value

status

True if successful; false if not. (^VAL)

Arguments

DTS_SELECT_ATTR

Set rendition for the selected tab in a tab set. (Unix, OpenVMS only) (n)

DTS_NONSELECT_ATTR

Set rendition for non-selected tabs in a tab set. (Unix, OpenVMS only) (n)

option

One of the following:

DA_SET = Set attributes.

DA_CHNG = Change existing attributes.

DA_LOAD = Set listed attributes and clear all others.

DA_CLR = Clear attributes.

attribute

One of the following flags defined in tools.def:

A_NONE = No attributes.

A_U = Underlined.

A_R = Reverse.

A_RU = Reverse, underlined.

A_B | A_I = Blinking (on Unix and OpenVMS) or italic (on Windows). “I” can be substituted whenever “B” appears in the following flags.

A_BU = Blinking, underlined.

A_BR = Blinking, reverse.

A_BRU = Blinking, reverse, underlined.

A_H = Highlighted.

A_HU = Highlighted, underlined.

A_HR = Highlighted, reverse.

A_HRU = Highlighted, reverse, underlined.

A_BH = Blinking, highlighted.

A_BHU = Blinking, highlighted, underlined.

A_BHR = Blinking, highlighted, reverse.

A_BHRU = Blinking, highlighted, reverse, underlined.

A_ALL = All attributes (same as A_BHRU).

palette#

(optional) Palette number, in the range 1 to 16, to set for the selected tab. (n)

DTS_TABTEXT

Specify text to put before and after each tab in a tab set container window. (Unix, OpenVMS only) (n)

pre_tab_string

(optional) String to put before each tab in a tab set container window. (a)

post_tab_string

(optional) String to put after each tab in a tab set container window. (a)

DTS_STYLE

Specify a tabbed dialog. (n)

style

One or more of the following options, combined using .BOR. or the vertical bar (|) operator. (Windows only) (n)

DTS_NONE = None of the following styles apply. (default)

DTS_MULTILINE = Multiple lines of tabs.

DTS_VERTICAL = Left or right side.

DTS_BOTTOM = Bottom (or right if DTS_VERTICAL is also specified).

DTS_RIGHT = Right (or bottom if DTS_VERTICAL is not specified).

Discussion

The DTS_DEFAULT subfunction of %TS_TABSET sets default settings for tab sets. Defaults will be used for the next tab set created using the %TS_TABSET(DTS_CREATE) function. DTS_DEFAULT overrides Toolkit’s default styles and any styles set by the TABSET_STYLE initialization setting.

If any of the optional arguments are not passed for a given function, no default settings will be set for that function.

On Unix and OpenVMS, pre_tab_string and post_tab_string can be used to define the two delimiter strings. The maximum length of each string is 10 characters. If post_tab_string is specified as an empty string (“”), the string specified in pre_tab_string will be repeated after the last tab. If pre_tab_string is an empty string, the container window’s border acts as a border for the first tab.

Examples

The following example sets the default rendition for non-selected tabs to use reverse video, underline, and color palette number 10.

status = %TS_TABSET(DTS_DEFAULT, DTS_NONSELECT, DA_SET+A_RU, 10)

The following example sets the default tab delimiter to be “|”.

status = %TS_TABSET(DTS_DEFAULT, DTS_TABTEXT, "|", "") 

DTS_GETDEFAULT

status = %TS_TABSET(DTS_GETDEFAULT, function) 

or

xcall TS_TABSET(DTS_GETDEFAULT, function)

Discussion

The DTS_GETDEFAULT subfunction of %TS_TABSET can be called to get default settings for tab sets. It uses the same syntax as DTS_DEFAULT.

If any of the optional arguments are not passed for a given function, no default settings will be retrieved for that function.

DTS_NUMTABS

tab_count = %TS_TABSET(DTS_NUMTABS, tab_id)

or

xcall TS_TABSET(DTS_NUMTABS, tab_id)

Return value

tab_count

The number of tabs currently in the tab set. (^VAL)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

Discussion

The DTS_NUMTABS subfunction of %TS_TABSET obtains the number of tabs associated with a tab set.

DTS_TABINDEX

index = %TS_TABSET(DTS_TABINDEX, tab_id, type, type_id)

or

xcall TS_TABSET(DTS_TABINDEX, tab_id, type, type_id)

Return value

index

The index of the tab, or 0 if the window or list is not contained within the specified tab set. (^VAL)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

type

Pass DTS_WINDOW for a window or DTS_LIST for a list. (n)

type_id

The ID of the window or list. (n)

Discussion

The DTS_TABINDEX subfunction of %TS_TABSET obtains the tab index that contains the specified window or list.

If tab_id is not a valid tab set ID, a fatal error occurs.

Because the index of a tab can change when other tabs are added and removed, this subfunction should be called immediately before the returned information is required.

DTS_TABINFO

status = %TS_TABSET(DTS_TABINFO, tab_id, tab_index, type, type_id[, disabled])

or

xcall TS_TABSET(DTS_TABINFO, tab_id, tab_index, type, type_id[, disabled])

Return value

status

True if successful; false if not. (^VAL)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

tab_index

The index of the tab. (n)

type

Returned with DTS_WINDOW for a window or DTS_LIST for a list. (n)

type_id

Returned with the ID of the window or list. (n)

disabled

(optional) Returned true if the tab is disabled, false if enabled. (n)

Discussion

The DTS_TABINFO subfunction of %TS_TABSET obtains the type and ID of a contained object on a specified tab.

If tab_id is not a valid tab set ID, a fatal error occurs.

If tab_index is not in the range from 1 to the number of tabs in the specified tab set, the subfunction returns false with type and type_id set to 0.

If tab_id and tab_index are valid values, the subfunction returns true with values set for type and type_id.

Because the index of a tab can change when other tabs are added and removed, this subfunction should be called immediately before the returned information is required.

You can XCALL this subfunction if the return value is not required.

DTS_TABSET

tab_id = %TS_TABSET(DTS_TABSET, type, id[, container])

or

xcall TS_TABSET(DTS_TABSET, type, id[, container])

Return value

tab_id

The ID of the tab set that contains the window or list specified by id, or 0 if the window or list is not contained in a tab set. (^VAL)

Arguments

type

Pass DTS_WINDOW for a window or DTS_LIST for a list. (n)

id

The ID of the window or list. If id is not the ID for a window or list that has been logged with Toolkit, U_ABORT generates a Toolkit error. (n)

container

(optional) The returned ID of the composite window that contains id and is contained by the returned tab set (tab_id). If id is not part of a composite window on a tab set, container is returned as zero. (n)

Discussion

The DTS_TABSET subfunction of %TS_TABSET returns the ID of a tab set that contains the specified window or list (id), or it returns zero if the window or list is not contained in a tab set. This ID is returned if the window or list is directly placed on a tab set or if the window or list is part of a composite window that’s placed on a tab set. If there are nested tab sets, DTS_TABSET returns the ID of the innermost tab set that contains the window or list. If you want the ID of the outermost tab set, call this function iteratively using the returned ID.

If the window or list is part of a composite window on the tab_id tab set, you can also get the ID of the composite window by passing the container argument. If there are nested composite windows, the container argument returns the ID of the outermost composite window, which is the composite window that is directly placed on the tab set. (To get the ID of the innermost container window use the DC_CONTAINER subfunction for %C_CONTAINER. See DC_CONTAINER.)

DTS_CTRCONTEXT

xcall TS_TABSET(DTS_CTRCONTEXT, tab_id, reason)

Arguments

tab_id

The ID of the tab set returned by the DTS_CREATE subfunction. (n)

reason

The reason the tabbed dialog was activated, which can be blank (indicating that it was already activated), a program-supplied reason passed because it was activated programmatically, or one of the following: (a)

C_FIRST

Focus moved in attempt to reach first child in a composite window.

C_LAST

Focus moved in attempt to reach last child in a composite window.

C_NEXT

Focus moved from previous child in a composite window (e.g., by pressing Tab).

C_PREV

Focus moved from next child in a composite window (e.g., by pressing Shift+Tab).

C_SET

Child explicitly activated. For example, this could be the result of a mouse click, or it could be that the child was activated programmatically without a specified reason.

Discussion

DTS_CTRCONTEXT is designed for use in child processing methods for tab sets, where it enables users to tab through the buttons and input fields on the windows and lists in a tab set. It does this by calling routines for the various window types, which in turn use the reason code passed to the child method by C_PROCESS to determine what should have focus. (You could directly call the following, but DTS_CTRCONTEXT makes this easier by figuring out for you what type of window is on a tab.)

To use in a child method, pass the reason passed to the child method (by C_PROCESS) as the reason argument for DTS_CTRCONTEXT. See the ctrmeths.dbl file included in your UI Toolkit distribution for an example. This file includes code for the C_METHTS method, which uses DTS_CTRCONTEXT.

Note that if %TS_TABSET is invoked as a function with DTS_CTRCONTEXT, the return value for the function will be true.

Examples

See the ctrmeths.dbl file included in your UI Toolkit distribution. It includes code for the C_METHTS method, which uses DTS_CTRCONTEXT.