T_EDIT

Edit the text in a text window

xcall T_EDIT(window_id, [row], [column], [insert], [direction], [case], [col_id1], [col_id2], 
&     [col_id3], [help_id][, decimal_value])

Arguments

window_id

The ID of the text window. (n)

row

(optional) The text row at which to begin editing; returned with a row value on exit. (n)

column

(optional) The text column at which to begin editing; returned with a column value on exit. (n)

insert

(optional) Indicates the default insert/overstrike mode. Returned with a mode value on exit. (n)

1 = Insert. (default)

0 = Overstrike.

direction

(optional) Indicates the editing direction. Returned with a direction value on exit. (n)

1 = Forward. (default)

0 = Reverse.

case

(optional) Indicates whether lowercase is allowed. Returned with a case value on exit: (n)

1 = Lowercase allowed. (default)

0 = Uppercase only allowed.

col_id1 through col_id3

(optional) The IDs of menu columns to place. (n)

help_id

(optional) The help identifier. (a)

decimal_value

(optional) The first character to input (specified as a decimal value). Ignored on Windows. (n)

Discussion

T_EDIT performs text editing in a window that T_SETUP has converted to a text window. You must call T_SETUP at least once for a window prior to using T_EDIT to edit it. (For information on an alternative text-editing routine that preserves hard returns, see U_EDIT.)

The T_EDIT subroutine places any specified menu columns and sets the entry values for the row and column at which to begin editing, insert/overstrike mode, editing direction, and case. All of these values are stored and returned upon exit so the user can continue editing where they left off. Note the following:

Row and column are the text line and position to edit, not the window line and position. For example, if row and column each have a value of 1, the edit position will be the first character of the first text line, regardless of any margins. The default row and column values are both 1.
If you define a display area, it must be the same width as the window.

The following internal menu entry names are recognized by T_EDIT on Windows: E_CLEAR, E_COPY, E_CUT, E_MARK, E_MODE, E_PASTE.

Note the following for Windows:

The col_id arguments are, by default, ignored when running on Windows. These columns usually contain reserved menu entries that are automatically supported by the Windows environment. Additionally, the excessive placing and removing of columns causes a Windows menu bar to “flicker.” Instead, we recommend that menu columns be placed before the call to T_EDIT and removed afterwards.
If the height of the display area is less than the height of the window, a scroll bar is displayed. To prevent the scroll bar from occluding text entered in the text window, make the window size large enough to accommodate the scroll bar and the text, and then in the T_SETUP call, specify a right margin that is large enough for the scroll bar.

For example:

; Get the width of a character.
charwidth = %u_winmetrics(D_CHARWIDTH, WID_APP)
; Use character width to get width (in chars) of scrollbar.
extra_width = (%u_winmetrics(D_VSCROLL_X) + charwidth - 1) / charwidth
; Create window with extra width for scrollbar.
xcall w_proc(WP_CREATE, wndid, "text", 20, 
&            textbox_cols + extra_width, WP_PLACE, wndid, 1, 1)
xcall t_setup(wndid, D_INIT, 0, extra_width, 0, 0, ,
&             1, 1, textbox_rows, textbox_cols + extra_width)

We recommend that a fixed font be used for text in a text window. Using a proportional font may cause the text to wrap unpredictably.
T_EDIT’s handling of line ends in incoming data is controlled by the g_txt_softreturn field, which is defined in tools.def. See g_txt_softreturn for information.
For text windows that are part of a composite window, tab and shift+tab move focus to the next or previous child (unless tab or shift+tab is a shortcut on a placed menu column). tab instructs T_EDIT to signal “C_NEXT”, and shift+tab instructs T_EDIT to signal “C_PREV”.

On UNIX and OpenVMS, if any col_ids are passed, the specified columns will be placed on the menu and removed on exit. (The alternative to specifying menu columns in a T_EDIT call is to place them before calling T_EDIT.)

The following internal menu entry names are recognized by T_EDIT on UNIX and OpenVMS:

E_TOP	E_LMOV	E_DIR	E_XUP
E_BOTTOM	E_PDEL	E_MODE	E_XDOWN
E_UP	E_LDEL	E_WMOV
E_DOWN	E_WDEL	E_EMOV
E_LEFT	E_EDEL	E_BMOV
E_RIGHT	E_CDEL	E_JOIN
E_PMOV	E_LCLR	E_ILIN

If passed, decimal_value (which is ignored on Windows) is converted to its alpha (ASCII) equivalent and placed into the window as if it were the first character entered by the user. T_EDIT then clears the variable passed as decimal_value, which makes it easier to use T_EDIT in a loop.

In any environment, if the internal name of the selected menu entry begins with “U_,” the EUTILS_METHOD subroutine is called and the input is redone. If the internal name of the selected menu entry is “O_HELP,” the EHELP_METHOD subroutine is called, with help_id as its argument. If some other menu entry is selected, control is returned to the calling routine. G_select will be true and g_entnam will hold the name of the entry. You will need to clear g_select after you satisfy the event.

The default behavior for each environment’s handling of columns is controlled by the g_plc_col_args flag, which is defined in the distributed tkctl.def file. See g_plc_col_args for information.