%TS_PROCESS

Process a tabbed dialog

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
status = %TS_PROCESS(tabid[, method_arg, ...])

or

xcall TS_PROCESS(tabid[, method_arg, ...])

Return value

status

Always returns true. (^VAL)

Arguments

tabid

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

method_arg

(optional) One of up to 20 arguments that are passed to the method for each tab as it becomes active.

Discussion

%TS_PROCESS enables your applications to process tabbed dialogs. When this function is called, the method for the active tab is immediately invoked. If no tab has been designated as the active tab (with DTS_ACTIVE), then the first defined tab is presumed. When the user clicks on a tab, the menu entry “TS_TABn” is generated, where n is the index of the desired tab (there are exceptions for composite windows; see Controlling tabbing, focus, and input context). The tab method may “see” this menu entry and perform any cleanup or preparation for tab switching that may be needed, but it must allow this menu entry to be returned from the method in order for the automatic tab switching to occur. Clearing g_select or modifying g_entnam at this point will disable the tab switch.

On UNIX and OpenVMS, “TS_TABn” menu entries can be placed on the menu to achieve immediate tabbing. Also, the entries “TS_TABNEXT” and “TS_TABPREV” will create the same effect as signaling the corresponding next or previous “TS_TABn” menu entry. On Windows, ctrl+tab and ctrl+shift+tab will be automatically mapped to these latter two entries, respectively. For cross‑platform compatibility, place any “TS_xxx” menu entries on columns whose IDs are passed to Toolkit input routines. (By default, on UNIX and OpenVMS, these will be placed; on Windows, they won’t be placed.)

When a tab switch occurs within %TS_PROCESS, the associated window is brought to the front, and its associated method subroutine is called, passing the associated ID (window ID or list ID) and up to 20 optional arguments that were passed to %TS_PROCESS.

When the method for a tab returns, if a menu entry has been signaled (g_select is true), then if it is a menu entry which %TS_PROCESS recognizes (TS_xxx), it will be processed by %TS_PROCESS and the method for the active tab will be called. If the menu entry is not recognized by %TS_PROCESS, it is returned to the routine that called %TS_PROCESS. If no menu entry has been signaled (g_select is false) when the method returns, then the method is immediately called again.

If the method for a tab doesn’t allow a TS_xxx menu entry to be returned to %TS_PROCESS, the method should reset the active tab by calling %TS_TABSET with the DTS_ACTIVE subfunction. Otherwise, the tab which is forward will not match the window displayed within. To prevent the tab from switching in the first place, remove or disable the other tabs.

Calls to %TS_TABSET are allowed while within %TS_PROCESS, even if they reference the same tab set.

Tip

We do not recommend using required fields in a tab set because when the user clicks OK, the tab set field validation behavior does not follow general Windows conventions. Instead, we recommend filling the windows with valid data, so that required field validation does not occur.

The only time that %TS_PROCESS returns is when a menu entry is selected that is not processed by the currently active tab’s method subroutine, nor recognized by %TS_PROCESS.

Examples

The following subroutine loads a tab set and processes it:

subroutine process_tabs
.include "WND:tools.def"
record
        tabid           ,int
        inpid1          ,int
        inpid2          ,int
        lstid           ,int
        inp_record      ,a10
        list_record     ,a40
proc
        ;Create a tab container large enough for windows of 14 x 70.
        tabid = %ts_tabset(DTS_CREATE, "tab_container", 14, 70)
        ;Create the first tab as an input window.
        xcall i_ldinp(inpid1,, "i_tab1")
        xcall ts_tabset(DTS_WINDOW, tabid, inpid1, "inp_method")

        ;Create the second tab as a list.
        xcall i_ldinp(inpid2,, "i_tab2")
        xcall l_create(lstid, inpid2, list_record, g_utlib, "l_tab2")
        xcall ts_tabset(DTS_LIST, tabid, lstid, "list_method")
        ;Add a button to the tab set.
        xcall ts_tabset(DTS_BUTTON, tabid, "O_EXIT", DSB_TEXT, "Done")
        ;Main input loop
        repeat
          begin
            xcall ts_process(tabid, inp_record, list_record)
            if (g_select)
              begin
                using g_entnam select
                ("O_EXIT "),  exitloop
                ;Add other cases as needed.
                endusing
              end
          end
        xreturn
end
; Tab method for the input window
subroutine inp_method 
        a_inpid         ,n   ;The input window ID
        a_inp_record    ,a   ;The input record
        a_list_record   ,a   ;The list record, though we don't use it here
proc
        ;Just perform input on the default set of the window, 
        ; updating a_inp_record.
        xcall i_input(a_inpid,, a_inp_record)
        xreturn
end
; Tab method for the list
subroutine list_method
        a_lstid         ,n   ;The list's ID
        a_inp_record    ,a   ;The input record, though we don't use 
                             ; it here
        a_list_record   ,a   ;The list record
record
        req             ,int ;A variable for the list request code
proc
        ;Just select an entry, and place its record in a_list_record.
        xcall l_select(a_lstid, req=D_LNOP, a_list_record)
        xreturn
end