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.
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.
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,
- calls to U_BEEP have no effect.
- runtime routines other than %U_MSGBOX suppress the terminal bell and MessageBeep. Note that on Windows, the g_beep setting does not affect beeps for message boxes or other sounds associated with message box icons.
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.
Specifies the check mark character to be used by S_SELECTCB, S_UPDATECB, and U_MODREND. Note the following:
- On Windows, this field affects only check marks for check boxes that aren’t framed (using I_FRAMES, I_INPUT, or I_INPFLD). Framed check boxes always use the Windows standard check mark character.
- This field is initialized to “X” on most environments.
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 (/).
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.)
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.
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.
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:
- The g_retaincontext field applies only when using I_INPUT. It does not apply to any menu entry signaled from outside of the input routine.
- If you set g_retaincontext, set it from the method that signals the menu entry, or set it before calling that method. If you don’t, the setting won’t apply until the next such situation (the next time a menu entry is signaled from a method and a user action moves input context to a subsequent field or button).
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.
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).
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. |
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 (:).
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:
- D_FOREVER (or -1), which instructs Toolkit to wait until I/O processing is complete (i.e., no time-out).
- D_IMMEDIATE (or 0), which instructs Toolkit to immediately time out.
- n (a positive number), which instructs Toolkit to wait n seconds before timing out.
See the following for more information:
- AX_TIMEOUT routine
- AX_INPUT routine
- WAIT qualifier
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. For more information on using this file, see tools.def.
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.
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.