U_EDIT

Edit text and control line breaks in a window

xcall U_EDIT(window_id, text_array, [line], [character], [flags], [col_id1], [col_id2], 
&     [col_id3], [help_id][, decimal_value])

Arguments

window_id

The ID of the window that will be the container for text editing. (n)

text_array

A System.Collections.ArrayList array for passing initial text to be inserted when U_EDIT starts, and for returning the final state of text in the window when program control returns from U_EDIT. (System.Collections.ArrayList)

line

(optional) A writable variable whose value determines the line that the cursor will be initially positioned on when U_EDIT starts. When control returns from U_EDIT, line returns the line that the cursor was on when last used for input. Line defaults to 1. (n)

character

(optional) A writable variable whose value determines the cursor’s character position in line when program control moves to U_EDIT. When control returns from U_EDIT, character returns the character position last occupied by the cursor. Character defaults to 1. (n)

flags

(optional) A writable variable that sets one or more of the following flags and that returns the final state of these flags (except D_EDIT_SELECTALL, which is never returned). By default these are set to off. They are defined in tools.def and can be combined using .BOR. or the vertical bar ( | ) operator: (n)

D_EDIT_SELECTALL = Initially select all text (Windows only).

D_EDIT_OVERSTRIKE = Use overstrike mode.

D_EDIT_BACKWARD = Use backward navigation.

D_EDIT_SOFT = Insert soft return for Enter.

col_id1
col_id2
col_id3

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

help_id

(optional) A help identifier. (a)

decimal_value

(optional) A writable variable whose value specifies an initial character to be input. This value must be passed as a decimal value for an ASCII character (e.g., pass 65 for the letter A). (n)

Discussion

U_EDIT enables users to enter and edit text in a window. It is similar to T_EDIT in that you control where editing starts, whether insert mode or overstrike mode is used, and the direction for certain menu entries. You can also optionally specify menu columns to load while the routine is processing, a help ID, and an initial character for input. And when control returns from U_EDIT, it returns the line and character position last used for input, so your program can enable users to continue editing where they left off.

However, unlike T_EDIT, the U_EDIT subroutine does the following;

Preserves hard returns, and enables you to specify the kind of return (hard or soft) that is created when the user presses Enter.
Enables you to supply initial text to be displayed when U_EDIT starts (this text can include hard returns), and returns the resulting edited text in a way that preserves the location of hard returns. (You supply initial text in text_array, and U_EDIT returns text in text_array.)
Uses System.Collections.ArrayList arrays.
Doesn’t require T_SETUP to be called for the window. If T_SETUP has been called, its settings are ignored.

U_EDIT uses the entire visible area of the window (window_id) as the editing area. The visible area of a window is usually defined by its display area, but note that on Windows systems this can be affected by altering the container size with the WP_SIZE subfunction of W_PROC. To create an editing area that occupies only part of the window, turn off the window’s border and make the window a child of a larger window.

The window specified by window_id must be the ID of a window registered and placed with Toolkit. Otherwise Toolkit will generate a U_ABORT error.

On Windows, if the window is resized while U_EDIT is processing (e.g., if the window has a size event and is therefore resizable by the user, or if some other asynchronous event resizes the window), the editing area is resized accordingly.

The maximum length for text in the editing area is 65,535 characters. On Windows, that includes two characters for every hard return and three characters for every user-inserted soft return. On Unix and OpenVMS, a user-inserted soft return requires one character, while a hard return doesn’t require a character.

If the text supplied in text_array exceeds this maximum when control moves to U_EDIT, the text will be truncated to 65,535 characters before it’s displayed. Text lost in truncation will not be returned when control returns from U_EDIT.

If a user attempts to insert characters (by typing or pasting) that would cause the maximum length to be exceeded, the insertion is ignored.

If it is not possible to wrap text on a space, the text will be wrapped (with a soft return) at the character that exceeds the available width.

Hard returns are logical characters and can be deleted using any available method for deleting a character. Soft returns are not logical characters. Inserting or deleting text before a soft return (but after the preceding hard return) may remove the soft return. Furthermore, U_EDIT does not preserve soft returns in the text it returns to the calling routine.

Note the following for text_array:

When program control moves to U_EDIT, each element of the ArrayList is converted to a string and appended as a line of text in the editing area, with a hard return between each element. (If you don’t want hard returns in the text, pass all text in one element.)
When control returns from U_EDIT, all ArrayList elements are removed and replaced by strings that represent the updated state of each line.

Values passed as line and character set the current cursor location when program control moves to U_EDIT, and these arguments are returned with the updated position when control returns from U_EDIT. If line or character is not passed or contains a value that’s less than 1, the default (1) is used.

Line corresponds to an element in text_array. When U_EDIT returns, line contains the line number (not considering soft returns) where the cursor was last located. Note that because System.Collections.ArrayList arrays are 0-based, line is the text_array element number for that text plus 1. It’s not necessary to take this into consideration when using line in U_EDIT calls, but you will need to account for this if you use the ArrayList outside of U_EDIT.

If line is greater than the number of elements in text_array, line is assumed to be specifying the last line. (So passing a value greater than 65535 ensures that you’re specifying the last line.)

Character is the character position within line, beginning at 1. If character is greater than the length of the specified line, the cursor is positioned after the last character in the line. (So passing a value that’s greater than or equal to 65535 ensures that the cursor will be positioned at the end of the line.) When U_EDIT returns, character contains the position at which the cursor was last located within a line of text.

The D_EDIT_BACKWARD flag determines the direction used for the following menu entries: E_LMOV, E_WMOV, E_PDEL, E_LDEL, and E_WDEL. By default, the direction is forward, but if D_EDIT_BACKWARD is set to on, the direction is backward. The E_DIR menu entry enables users to toggle the direction.

The D_EDIT_SOFT flag controls the type of line wrap inserted when the user presses Enter. By default, Enter inserts a hard return. If D_EDIT_SOFT is set to on, Enter inserts a soft return. The E_HARD menu entry enables users to toggle this setting.

If you pass any of the col_id arguments while the global variable g_plc_col_args is set to true, the specified columns are placed when program control moves to U_EDIT and are removed when control returns from U_EDIT.

On Windows, col_id arguments are ignored by default because these arguments are used only when g_plc_col_args is set to true, these arguments are ignored by default on Windows. These columns are often unnecessary because they usually contain reserved menu entries that are automatically supported by Windows. Additionally, the excessive placing and removing of columns caused by the col_id arguments causes Windows menu bars to “flicker.” If you want to place menu entries, we instead recommend placing them before a call to U_EDIT and removing them after control returns from U_EDIT.

If decimal_value is passed as a non-zero value, it is converted to its alpha (ASCII) equivalent and placed in the window as if it were the first character entered by the user (after text supplied by text_array). U_EDIT then clears the variable passed as decimal_value, which makes it easier to use U_EDIT in a loop.

U_EDIT calls EUTILS_METHOD for menu entries whose names begin with U_, and it calls EHELP_METHOD for the O_HELP menu entry, passing help_id as the argument. (If help_id is not passed to U_EDIT, no help ID argument is passed to EHELP_METHOD.) If an entry other than these or the entries listed below is called, control is returned to the calling routine, g_select is set to true, and g_entnam stores the name of the entry.

U_EDIT recognizes the following internal menu entry names on all platforms:

C_NEXT	E_DIR	E_LEFT	E_RIGHT
C_PREV	E_HARD	E_MODE	E_TOP
E_BOTTOM	E_ILIN	E_PDEL	E_WDEL
E_CDEL	E_JOIN	E_PMOV	E_WMOV

On Windows (but not with Synergy .NET), U_EDIT also recognizes the following:

E_CLEAR	E_MARK
E_COPY	E_PASTE
E_CUT

On Unix and OpenVMS, U_EDIT also recognizes the following:

E_BMOV	E_LCLR	E_XDOWN
E_DOWN	E_LDEL	E_XUP
E_EDEL	E_LMOV
E_EMOV	E_UP

Note the following:

The E_ILIN menu entry inserts a hard return regardless of the way D_EDIT_SOFT is set.
For the E_LMOV, E_EMOV, and E_LDEL menu entries, a line is considered the text delimited by either hard or soft returns.
The E_MODE menu entry enables users to toggle insert/overstrike mode. When text is selected on Windows, typing a character replaces the selection regardless of insert/overstrike mode.
For the E_PMOV and E_PDEL menu entries, a paragraph is considered a logical line of text (i.e., a string of text ending in a hard return).
The E_JOIN menu entry removes the next hard return (the return at or following the current cursor location).

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 already associated with a menu entry on a placed menu column. Tab instructs U_EDIT to signal C_NEXT, and Shift+Tab instructs U_EDIT to signal C_PREV.