U_EDIT

Edit text and control line breaks in a window

WTSupported in traditional Synergy on Windows

 

USupported on UNIX
VSupported on OpenVMS
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;

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:

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:

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.

See also

Examples

The following example results in a window that accepts text that can include hard and soft returns:

import System.Collections       ;U_EDIT uses System.Collections.ArrayList
                                ; for the text_array argument.
main
.include "DBLDIR:windows.def"
.include "WND:tools.def"
record
  text      ,@ArrayList
  wndid     ,int
  line      ,int
  char      ,int
  flags     ,int
  dchr      ,int
proc
  u_start
  .
  .
  .
  u_window(D_PLACE, wndid, 1, 1)
  text = new ArrayList()
  repeat
    begin
      xcall u_edit(wndid, text, line, char, flags,,,, "help", dchr)
      if (g_select)
        using g_entnam select
        .
        .
        .
        (),      exitloop
        endusing
      end
  u_finish
end