MEMOEDIT()
 Display or edit character strings and memo fields
------------------------------------------------------------------------------
 Syntax

     MEMOEDIT([<cString>],
        [<nTop>], [<nLeft>],
        [<nBottom>], [<nRight>],
        [<lEditMode>],
        [<cUserFunction>],
        [<nLineLength>],
        [<nTabSize>],
        [<nTextBufferRow>],
        [<nTextBufferColumn>],
        [<nWindowRow>],
        [<nWindowColumn>]) --> cTextBuffer

 Arguments

     <cString> is the character string or memo field to copy to the
     MEMOEDIT() text buffer.  If not specified, the text buffer is empty.

     <nTop>, <nLeft>, <nBottom>, and <nRight> are the upper
     left and lower right window coordinates.  Row values can range from zero
     to MAXROW(), and column positions can range from zero to MAXCOL().  If
     not specified, the default coordinates are 0, 0, MAXROW(), and MAXCOL().

     <lEditMode> determines whether the text buffer can be edited or
     merely displayed.  Specifying true (.T.) allows the user to make changes
     to the text buffer, while specifying false (.F.) only allows the user to
     browse the text buffer.  If not specified, the default value is true
     (.T.).

     <cUserFunction> is the name of a user-defined function that executes
     when the user presses a key not recognized by MEMOEDIT() and when no
     keys are pending in the keyboard buffer.  <cUserFunction> is specified
     as a character value without parentheses or arguments.  Specifying false
     (.F.) for this argument displays <cString> and causes MEMOEDIT() to
     immediately terminate.  If this argument is specified, the automatic
     behavior of MEMOEDIT() changes.  Refer to the discussion below.

     <nLineLength> determines the length of lines displayed in the
     MEMOEDIT() window.  If a line is greater than <nLineLength>, it is word
     wrapped to the next line in the MEMOEDIT() window.  If <nLineLength> is
     greater than the number of columns in the MEMOEDIT() window, the window
     will scroll if the cursor moves past the window border.  If
     <nLineLength> is not specified, the default line length is (<nRight> -
     <nLeft>).

     <nTabSize> determines the size of a tab character to insert when the
     user presses Tab.  If <nTabSize> is not specified, four spaces are
     inserted instead of a tab character.

     <nTextBufferRow> and <nTextBufferColumn> define the display
     position of the cursor within the text buffer when MEMOEDIT() is
     invoked.  <nTextBufferRow> begins with one and <nTextBufferColumn>
     begins with zero.  If these arguments are not specified, the cursor is
     placed at row one and column zero of the MEMOEDIT() window.

     <nWindowRow> and <nWindowColumn> define the initial position the
     cursor within the MEMOEDIT() window.  Row and column positions begin
     with zero.  If these arguments are not specified, the initial window
     position is row zero and the current cursor column position.

 Returns

     MEMOEDIT() returns the text buffer if the user terminates editing with
     Ctrl-W or a copy of <cString> if user terminates with Esc.

 Description


     MEMOEDIT() is a user interface and general purpose text editing function
     that edits memo fields and long character strings.  Editing occurs
     within a specified window region placed anywhere on the screen.  Like
     the other user interface functions (ACHOICE() and DBEDIT()), MEMOEDIT()
     supports a number of different modes and includes a user function that
     allows key reconfiguration and other activities relevant to programming
     the current text editing task.

     .  The text buffer: When you invoke MEMOEDIT() and specify
        <cString>, it is copied to the text buffer.  The user actually edits
        the text buffer.  If the <cString> is not specified, the user is
        presented with an empty text buffer to edit.

        When the user exits MEMOEDIT() by pressing Ctrl-W, the contents of
        the text buffer are returned.  If the user exits by pressing Esc, the
        text buffer is discarded and the original <cString> value is
        returned.  In either case, the return value can then be assigned to a
        variable or memo field, or passed as an argument to another function.

     .  Editing modes: MEMOEDIT() supports two editing modes depending
        on the value of <lEditMode>.  When <lEditMode> is true (.T.),
        MEMOEDIT() enters edit mode and the user can change the contents of
        the MEMOEDIT() text buffer.  When <lEditMode> is false (.F.),
        MEMOEDIT() enters browse mode and the user can only navigate about
        the text buffer but cannot edit or insert new text.  To make browsing
        easier for the user, the scrolling is disabled so Uparrow and Dnarrow
        scroll the text buffer up or down one line within the MEMOEDIT()
        window.

     .  Entering and editing text: Within MEMOEDIT(), the user can
        enter and edit text by positioning the cursor, adding, or deleting
        characters.  To facilitate editing the text, there are a number of
        different navigation and editing keys:

        MEMOEDIT() Navigation and Editing Keys
        ---------------------------------------------------------------------
        Key                      Action
        ---------------------------------------------------------------------
        Uparrow/Ctrl-E           Move up one line
        Dnarrow/Ctrl-X           Move down one line
        Leftarrow/Ctrl-S         Move left one character
        Rightarrow/Ctrl-D        Move right one character
        Ctrl-Leftarrow/Ctrl-A    Move left one word
        Ctrl-Rightarrow/Ctrl-F   Move right one word
        Home                     Move to beginning of current line
        End                      Move to end of current line
        Ctrl-Home                Move to beginning of current window
        Ctrl-End                 Move to end of current window
        PgUp                     Move to previous edit window
        PgDn                     Move to next edit window
        Ctrl-PgUp                Move to beginning of memo
        Ctrl-PgDn                Move to end of memo
        Return                   Move to beginning of next line
        Delete                   Delete character at cursor
        Backspace                Delete character to left of cursor
        Tab                      Insert tab character or spaces
        Printable characters     Insert character
        Ctrl-Y                   Delete the current line
        Ctrl-T                   Delete word right
        Ctrl-B                   Reform paragraph
        Ctrl-V/Ins               Toggle insert mode
        Ctrl-W                   Finish editing with save
        Esc                      Abort edit and return original
        ---------------------------------------------------------------------

        When the user is entering text, there are two text entry modes,
        insert and overstrike.  When MEMOEDIT() is invoked, the default mode
        is overstrike.  Edit mode changes in MEMOEDIT() when the user presses
        Ins which toggles between the insert and overstrike.  It also changes
        in a user function using READINSERT() or RETURNing 22.  In insert
        mode, characters are entered into the text buffer at the current
        cursor position and the remainder of the text moves to the right.
        Insert mode is indicated in the scoreboard area.  In overstrike mode,
        characters are entered at the current cursor position overwriting
        existing characters while the rest of the text buffer remains in its
        current position.

        As the user enters text and the cursor reaches the edge of the
        MEMOEDIT() window, the current line wraps to the next line in the
        text buffer and a soft carriage return (CHR(141)) is inserted into
        the text.  If the <nLineLength> argument is specified, text wraps
        when the cursor position is the same as <nLineLength>.  If
        <nLineLength> is greater than the width of the MEMOEDIT() window, the
        window scrolls.  To explicitly start a new line or paragraph, the
        user must press Return.

     .  The edit screen: When MEMOEDIT() displays, it overwrites the
        specified area of the screen and does not save the underlying screen.
        Additionally, it does not display a border or a title.  To provide
        these facilities, you must create a procedure or user-defined
        function that performs these actions then calls MEMOEDIT().  See the
        example below.

     .  The user function: <cUserFunction>, a user-defined function
        specified as an argument, handles key exceptions and reconfigures
        special keys.  The user function is called at various times by
        MEMOEDIT(), most often in response to keys it does not recognize.
        Keys that instigate a key exception are all available control keys,
        function keys, and Alt keys.  Since these keys are not processed by
        MEMOEDIT(), they can be reconfigured.  Some of these keys have a
        default action assigned to them.  In the user function, you perform
        various actions, depending on the current MEMOEDIT() mode, then
        RETURN a value telling MEMOEDIT() what to do next.

        When the user function argument is specified, MEMOEDIT() defines two
        classes of keys: nonconfigurable and key exceptions.  When a
        nonconfigurable key is pressed, MEMOEDIT() executes it, otherwise a
        key exception is generated and the user function is called.  When
        there are no keys left in the keyboard buffer for MEMOEDIT() to
        process, the user function is called once again.

        When MEMOEDIT() calls the user function, it automatically passes
        three parameters indicating the MEMOEDIT() mode, the current text
        buffer line, and the current text buffer column.  The mode indicates
        the current state of MEMOEDIT() depending on the last key pressed or
        the last action taken prior to executing the user function.  The
        following modes are possible:

        MEMOEDIT() Modes
        ---------------------------------------------------------------------
        Mode    Memoedit.ch    Description
        ---------------------------------------------------------------------
        0       ME_IDLE        Idle, all keys processed
        1       ME_UNKEY       Unknown key, memo unaltered
        2       ME_UNKEYX      Unknown key, memo altered
        3       ME_INIT        Initialization mode
        ---------------------------------------------------------------------