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)
Create a tab set.
Add a window to a tab set.
Add a list to a tab set.
Add a button to a tab set. (Windows only)
Modify the button set for a tab set. (Windows only)
Bring a tab to the front.
Enable a tab in a tab set.
Disable a tab in a tab set.
Remove a tab from a tab set.
Modify the attributes for the selected tab. (Unix, VMS only)
Modify the attributes for non-selected tabs. (Unix, VMS only)
Modify the default tab settings.
Obtain the default tab settings.
Obtain the number of tabs in a tab set.
Obtain the tab index for a window or list.
Obtain information for a tab.
Obtain the ID of the tab set that contains a specified window or list. (Unix, VMS only)
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.
See the %TS_PROCESS Examples and the DTS_CREATE Examples.
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)
None of the following styles apply. (default)
Multiple lines of tabs.
Left or right side.
Bottom (or right if DTS_VERTICAL is also specified).
Right (or bottom if DTS_VERTICAL is not specified).
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.
See also
DTS_DEFAULT subfunction for setting the default style
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)
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.
|
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:
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.)
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)
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.
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.
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)
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)
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)
The buttons will be left-justified if DSB_BOTTOM is specified, or positioned towards the top if DSB_RIGHT is specified. (default)
The buttons will be centered along the designated side.
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 only one, either the contained window or the tab set container, defines a default button, the specified button is the default button.
- If neither the contained window nor the tab set container defines a default button, the first button on the contained window is the default button.
- If both the contained object and the tab set container define a default button, the default button of the contained window is the default button.
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.
See also
- B_BUTTONSET routine for more information on defining the placement of a set of buttons
- .BUTTON_SET routine for defining the placement of a window’s button set in a script file
- L_BUTTON routine for creating buttons within a list
- L_BUTTONSET routine for information about specifying button placement for a list
- E_STATE routine for information about the Enter key selecting the default button
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.
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.
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.
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.
|
|
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. |
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.
See also
- DTS_DEFAULT subfunction for information about setting the default rendition for tab sets
- DTS_NONSELECT_ATTR subfunction for information about setting the rendition for non-selected tabs in a tab set
- Synergy Windowing API for more information on the effects of setting, changing, loading, and clearing attributes
- Colors and the color palette
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)
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 also
- DTS_DEFAULT for information about setting the default rendition for tab sets
- DTS_SELECT_ATTR for information about setting the rendition for the selected tab in a tab set
- Synergy Windowing API for more information on the effects of setting, changing, loading, and clearing attributes
- Colors and the color palette for more information on using color palettes
Examples
See the DTS_SELECT_ATTR Examples.
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.
See also
- DTS_SELECT_ATTR for information about setting the rendition for the selected tab in a tab set
- DTS_NONSELECT_ATTR for information about setting the rendition for non-selected tabs in a tab set
- DTS_CREATE for information about creating a tabbed dialog with specific delimiter strings and tabbed dialog style
- TABSET_STYLE for setting the global default style in synergy.ini
- Colors and the color palette for more information on using color palettes
- Synergy Windowing API for more information on effects of setting, changing, loading, and clearing attributes
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, "|", "")
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.
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.
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.
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)
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.
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.)
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)
Focus moved in attempt to reach first child in a composite window.
Focus moved in attempt to reach last child in a composite window.
Focus moved from previous child in a composite window (e.g., by pressing Tab).
Focus moved from next child in a composite window (e.g., by pressing Shift+Tab).
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.)
- For an input window on a tab, DTS_CTRCONTEXT calls I_CTRCONTEXT, passing the ID of the input window and reason on to that routine.
- For a list on a tab, DTS_CTRCONTEXT calls L_CTRCONTEXT, passing the ID of the list and reason on to that routine.
- For a composite container window on a tab, DTS_CTRCONTEXT calls the DC_CTRCONTEXT subfunction of %C_CONTAINER, passing the ID of the container and reason on to that routine.
- For a tab set on a tab (which we don’t recommend), DTS_CTRCONTEXT recursively calls itself, passing the ID of the child tab set and reason.
- For any other type of window, DTS_CTRCONTEXT calls U_CTRCONTEXT, passing the ID of the window and reason on to that routine.
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.
See also
- C_PROCESS for information on how it uses child processing methods
- Controlling tabbing, focus, and input context for information on tabbing indices
Examples
See the ctrmeths.dbl file included in your UI Toolkit distribution. It includes code for the C_METHTS method, which uses DTS_CTRCONTEXT.
