Customizing configuration fields

The tkctl.def and tools.def files contain a number of configuration fields that you can modify from within your program to change operational characteristics of UI Toolkit. These fields are listed below. In the sections below, “false” indicates a value of zero; “true” indicates a nonzero value.

Note

If you want to modify any of these fields, you must first .INCLUDE the corresponding file(s) in your program.

When using Toolkit code in Synergy .NET, there are some limitations to the ways you can use these configuration fields. See Restrictions for global fields.

tkctl.def

Tkctl.def includes the following fields, which are initialized by U_START.

g_ActiveX_list

Specifies whether Toolkit will use the ActiveX list control for lists (true/false). See Specifying and determining the list type for more information. This field is initialized to true if the environment variable ACTIVEX_LIST is set to 1. Otherwise, it is initialized to false.

g_beep

Turns on or turns off the terminal bell (on all platforms) and MessageBeep (on Windows). If g_beep is set to true, the terminal bell and MessageBeep are enabled. If it is set to false,

U_START initializes this field to false if the DTK_BEEP environment variable is set to 0 or “off” (case‑insensitive) in synuser.ini, synergy.ini, or the environment. Otherwise U_START initializes it to true (the default). Note that an application can set g_beep, and the setting will determine subsequent behavior.

g_chk_char

Specifies the check mark character to be used by S_SELECTCB, S_UPDATECB, and U_MODREND. Note the following:

g_date_order

Defines date input and display. See DATE, NODATE for information. This field is initialized to 0.

g_date_sep

Specifies the character to be used to separate parts of a date when displayed. This field is initialized to a forward slash (/).

g_dtkbounds

Controls DTK_BOUNDS checking behavior after U_START is called. This field is initialized to 1 if the DTK_BOUNDS environment variable is set to 1. It is initialized to 2 if DTK_BOUNDS is set to 2. Otherwise, it initialized to 0, which turns off bounds checking. In tools.def, there are defines for 1 (D_BOUNDS_OVERRUN) and 2 (D_BOUNDS_EXACT).

g_edt_fwrd_msg

Defines the edit forward direction message. This field is initialized to “Forward”. (The message string is read from the Synergy/DE text message file.)

g_edt_ins_msg

Defines the edit insert mode message. This field is initialized to “Insert”. (The message string is read from the Synergy/DE text message file.)

g_edt_ovr_msg

Defines the edit overstrike mode message. This field is initialized to “Overstrike”. (The message string is read from the Synergy/DE text message file.)

g_edt_rev_msg

Defines the edit reverse direction message. This field is initialized to “Reverse”. (The message string is read from the Synergy/DE text message file.)

g_entnamctab (Windows only)

Specifies the name of the menu entry to be activated when ctrl+tab is pressed. This field is initialized to blank (no entry).

g_entnamcstab (Windows only)

Specifies the name of the menu entry to be activated when ctrl+shift+tab is pressed. This field is initialized to blank (no entry).

g_entnamtab (Windows only)

Specifies the name of the menu entry to be activated with tab is pressed. This is initialized to blank (no entry).

g_entnamstab (Windows only)

Specifies the name of the menu entry to be activated when shift+tab is pressed. This is initialized to blank (no entry).

g_eof_max

To facilitate redirection of input, this field specifies the maximum number of successive end‑of‑file (EOF) characters to allow on input. (On UNIX, these are ctrl+d. On OpenVMS, they are ctrl+z.) After the specified maximum number of EOF characters are encountered, the program will stop and display a message saying that too many EOF characters were encountered.

This is initialized to 100. To disable the behavior described above, set it to 0.

g_inp_trm_key

Defines the completion key code for the I_INPUT subroutine. This field is initialized to RETURN_KEY. (RETURN_KEY is defined in inpctl.def.)

g_inp_trm_msg

Defines the I_INPUT termination processing message. This field is initialized to “Make corrections or press RETURN to complete input”. (The message string is read from the Synergy/DE text message file.)

g_periods

Defines the maximum value for period‑style dates. This field is initialized to 12.

g_plc_col_args

Determines whether Toolkit will place menu columns that are passed as arguments to Toolkit routines (true/false). When set to true, Toolkit places and removes menu columns as needed. When set to false, Toolkit ignores menu column arguments. This field is initialized to false for Windows and true for UNIX and OpenVMS.

Note

Although you can change the value of g_plc_col_args on any supported platform after U_START is called, we recommend leaving it set to true for UNIX and OpenVMS because on these platforms menu columns must be placed to make their functions available to users.

g_retaincontext (Windows)

Determines how context is handled when a menu entry is signaled from a change, display, or leave method and a user action (mouse click, enter, tab, shift+tab, etc.) moves input context to a subsequent field or button. Prior to UI Toolkit version 8.3, if a menu entry was signaled in this situation, Toolkit would incorrectly apply the menu entry processing to the subsequent field or button rather than to the field whose method called %M_SIGNAL. This was corrected in Toolkit version 8.3. By default, context now remains on the field whose method signaled the menu entry, which matches Toolkit behavior on UNIX and OpenVMS. You can, however, restore the previous behavior. If g_retaincontext is set to true, Toolkit emulates Windows behavior for Toolkit versions prior to 8.3 (it moves input context to the subsequent field or button). If g_retaincontext is set to false (the default), context remains on the field whose method signaled the menu entry. Note the following:

This field is initialized to true if the RETAIN_CONTEXT_CHANGE_ON_SIGNAL environment variable is set to 1. If RETAIN_CONTEXT_CHANGE_ON_SIGNAL is set to any other value or is undefined, g_retaincontext is initialized to false.

g_tabfacecolor

Determines which color palette entry will be applied to a window when the window is added to a tab set. If this field is set to 0 (or a value greater than 16), no color palette entry is applied to a window when it is added to a tab set; the window’s color remains as is.

On Windows, this field is initialized to 9 if themes are enabled; otherwise, it is initialized to 0.

On UNIX and OpenVMS, this field is initialized to 0.

g_throwabort

Determines the behavior of U_ABORT. If g_throwabort is set to zero, U_ABORT pops up a message box and performs a STOP. If g_throwabort is set to a non‑zero value, U_ABORT will instead call U_FINISH to shut down Toolkit and then use EXITE to throw a trappable error.

This field is initialized to true (1) if the environment variable DTK_THROW_ABORT is set to 1. Otherwise, this is initialized to false (0).

Note

If you want U_ABORT to throw a trappable error during U_START processing (i.e., call U_FINISH and then EXITE), set g_throwabort before calling U_START. However, note that U_START will reset g_throwabort to the value of DTK_THROW_ABORT, so you may need to set g_throwabort again after the U_START call.

g_time_entry

Specifies the name of the time‑out menu entry. This field is initialized to O_TIMEOUT.

g_time_sep

Defines the character used to separate parts of a time field when displayed. This field is initialized to a colon (:).

g_wait_time

Specifies a default time‑out value. This field is initialized by U_START to Q_WAIT, which is equivalent to D_FOREVER, ‑1, or FOREVER (for .FIELD), but can be any one of the following:

See the following for more information:

g_wt_alrt_key

Defines the completion key code for the alert state of the U_WAIT subroutine. This field is initialized to RETURN_KEY. (RETURN_KEY is defined in inpctl.def.)

g_wt_alrt_msg

Defines the display message for the alert state of the U_WAIT subroutine. This field is initialized to “Press RETURN to continue”. (This message string is read from the Synergy/DE text message file.)

g_wt_err_key

Defines the completion key code for the error state of the U_WAIT subroutine. This field is initialized to CTRL_G_KEY. (CTRL_G_KEY is defined in inpctl.def.)

g_wt_err_msg

Defines the display message for the error state of the U_WAIT subroutine. This field is initialized to “Press ^G to continue”. (The message string is read from the Synergy/DE text message file.)

tools.def

Tools.def includes the following fields.

g_netnativemsgbox

In Synergy .NET, Toolkit uses native Windows message boxes for the following routines if g_netnativemsgbox is set to true: U_MESSAGE, %U_MSGBOX, and U_WAIT. If this field is set to false, which is the default, Toolkit uses cell‑based‑style message boxes for these routines in Synergy .NET.

g_txt_rtrn

When set to false, pressing enter while in an input window text field will be interpreted as completion of input. If you want enter to insert a new line, set the variable to true. This field is initialized to false.

g_txt_softreturn

Controls the way Toolkit handles line ends on Windows when using T_EDIT or when using I_INPUT with multi‑line text fields. When set to 0, Toolkit retains line ends in incoming data and uses those line ends when displaying the data. When set to a non‑zero value, Toolkit assumes that line ends are the result of wrapping and discards them, rewrapping lines as needed when displaying the data. This field is initialized to 0.

g_updt_fld

When performing “DONE” processing (passing *DONE* to I_NEXT or selecting an I_DONE menu entry), UI Toolkit updates the window system as each field in the input set is processed. If you have a lot of input fields being set by the DONE processing, and you want to improve performance, set this variable to false. This field is initialized to true.

g_updt_set

When performing “DONE” processing (passing *DONE* to I_NEXT or selecting an I_DONE menu entry), UI Toolkit does not update the window system until the next input occurs (unless g_updt_fld is set). If you want to force a window system update after DONE processing (for instance if your program does some lengthy processing before the next input might normally occur), set this variable to true. This field is initialized to false.