Click above to get retro games delivered to your door ever month!

MEMOEDIT()


Syntax:     MEMOEDIT([<expC1>] [,<expN1>] [,<expN2>] [,<expN3>]
            [,<expN4>] [,<expL1>] [,<expC2>] [,<expN5>] [,<expN6>]
            [,<expN7>] [,<expN8>] [,<expN9>] [,<expN10>])

Purpose:    To display or edit character strings and memo fields.

Arguments:  <expC1> is the character string or memo field to edit.

            <expN1...expN4> define the edit window coordinates in
            the following order:  top, left, bottom, and right.  If all
            are omitted, the entire screen is used.

            <expL1> determines whether a memo is edited or simply
            displayed.  If you specify true (.T.), the memo is displayed
            and you enter the edit mode.  If you specify false (.F.),
            you are placed in the browse mode where the memo is simply
            displayed.  The default is true (.T.).

            <expC2> is the name of a user function (a user-defined
            function) to control the memo editing process.  Specify the
            function name without parentheses or arguments.  Refer to
            the discussion below for more information.

            <expN5> determines the line length.  If <expN5> is
            greater than the width of the window (<expN4> - <expN2> +
            1), the window scrolls horizontally.  The default is
            (<expN4> - <expN2> - 1).

            <expN6> determines the tab size and enables real tabs.
            The default is four.  Spaces are used if <expN6> is omitted.

            <expN7> is the initial memo line where the cursor is
            placed.  The default is one.

            <expN8> is the initial memo column where the cursor is
            placed.  The default is zero.

            <expN9> is the initial row for placing the cursor
            relative to the window position.  The default is zero.

            <expN10> is the initial column for placing the cursor
            relative to the window position.  The default is zero.

            All arguments are optional.  You must, however, pass a dummy
            argument for any argument you wish to skip.

Returns:    A character string.

            MEMOEDIT() returns the modified string if it is terminated
            with Ctrl-W or the original string if it is terminated with
            Esc.

Usage:      MEMOEDIT() is a general purpose text editing function you
            can use in your applications for a variety of purposes.  It
            supports a number of different modes and includes a user
            function to allow key reconfiguration and other activities
            germane to programming the current text editing task.

            Browse/Update modes: MEMOEDIT() supports two display
            modes depending on the value of <expL1>.  If <expL1> is true
            (.T.), MEMOEDIT() enters update (edit) mode; otherwise,
            MEMOEDIT() enters browse (display) mode.  In the browse
            mode, all navigation keys are active and perform the same
            actions as update mode with one exception.  In update mode,
            the default scroll state is off (Uparrow and Dnarrow move
            the cursor up or down one line).  In browse mode, the
            default scroll state is on (Uparrow and Dnarrow scroll the
            contents of the MEMOEDIT() window up or down one line).

            Note that browse mode in Autumn '86 did not allow cursor
            movement and terminated immediately.  To retain this
            behavior, specify false (.F.) for the update and user
            function arguments like this:

               MEMOEDIT(<expC1>, <expN1>, <expN2>, <expN3>,;
               <expN4>, .F., .F.)

            User Function: When MEMOEDIT() calls the user function,
            it automatically passes three parameters:  "status," "line,"
            and "col."  The status message 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 status values are possible:


            Table: MEMOEDIT() Status Messages
            -----------------------------------------------------
            Status         Description
            -----------------------------------------------------
               0           Idle
               1           Re-configurable or unknown keystroke
                           (memo unaltered)
               2           Re-configurable or unknown keystroke
                           (memo altered)
               3           Start-up
            -----------------------------------------------------

            A status value of 3 indicates that the current mode is the
            start-up mode.  When you specify a user function, MEMOEDIT()
            makes a call to it immediately after being invoked.  At this
            point, you RETURN a request to configure MEMOEDIT()'s
            various toggle states:  word-wrap, scroll, or insert.
            MEMOEDIT() calls the user function repeatedly, remaining in
            the start-up mode until you RETURN 0.  The memo is then
            displayed and you enter the display mode set by <expL1>.
            Note that if word-wrap is on when the start-up mode
            completes, the entire memo is formatted to the current line
            length.  Since the word-wrap default is on, you must toggle
            it off during start-up if you do not want this initial
            formatting.  Note also that the toggles for the scroll and
            word-wrap states are not assigned to any key, but can be
            assigned from the user function.

            The idle state (status = 0) is called once when there is no
            pending key to process.  Within this state, you generally
            update line and column number displays.  MEMOEDIT() calls
            the user function whenever a key exception occurs.  Keys
            that instigate a key exception are all available control
            keys, function keys, and Alt keys.  Since these keys are not
            processed by MEMOEDIT() when you have a user function, they
            can all be re-configured.  Some of these keys have a default
            action assigned to them (see "status message" table above).

            The other two parameters, line and col, indicate the current
            cursor position in the MEMOEDIT() window when the user
            function is called.  The line parameter begins with position
            one and col begins with position zero.

            When the status is either 1, 2, or 3, you can return a value
            instructing MEMOEDIT() what action to perform next.  The
            following table (User Function Requests) summarizes the
            possible return values and their consequences:


            Table: MEMOEDIT() User Function Requests
            -------------------------------------------------------------
            Value    Action
            -------------------------------------------------------------
            0        Perform default action
            1 - 31   Perform requested action corresponding to key value
                     (e.g., 22 = Ctrl-V = Ins = toggle insert mode)
            32       Ignore the current key (disable)
            33       Process the current key as data (insert control
                     key)
            34       Toggle word-wrap
            35       Toggle scroll state
            -------------------------------------------------------------
            The following exceptions resolve key value collisions:

            100      Next word (2 = Ctrl-B = reform)
            101      Bottom right of window (23 = Ctrl-W = save and
                     exit)
            -------------------------------------------------------------

            Key reconfiguration: When the user function argument is
            specified, MEMOEDIT() defines two classes of keys:
            non-configurable and key exceptions.  Non-configurable keys
            are detailed in the table below.  When a non-configurable
            key is pressed, MEMOEDIT() executes it.  If there are no
            more keys to execute it then goes to idle making a user
            function call.  If the key press is an exception, an
            immediate call is made to the user function with a status
            value of 1 or 2.  If the key is a configurable (those
            defined in the table below), RETURNing 0 executes the
            MEMOEDIT() default action.  You can, however, RETURN a
            different value to execute another key action thereby
            redefining the key.  If the key is not a configurable
            recognized by MEMOEDIT(), you can define an action for it
            also by RETURNing a value requesting a key action as defined
            in the table above.

            Refer to Me.prg on the Clipper distribution disk for a fully
            functional example of all these capabilities.

            Table: MEMOEDIT() Non-configurable Keys
            ---------------------------------------------------------------
            Key                           Purpose
            ---------------------------------------------------------------
            Uparrow or Ctrl-E             Move up one line
            Dnarrow or Ctrl-X             Move down one line
            Leftarrow or Ctrl-S           Move left one character
            Rightarrow or Ctrl-D          Move right one character
            Ctrl-Leftarrow or Ctrl-A      Move left one word
            Ctrl-Rightarrow or Ctrl-F     Move right one word
            Home                          Beginning of current line
            End                           End of current line
            Ctrl-Home                     Beginning of current window
            Ctrl-End                      End of current window
            PgUp                          Previous edit window
            PgDn                          Next edit window
            Ctrl-PgUp                     Beginning of memo
            Ctrl-PgDn                     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
            ---------------------------------------------------------------


            Table: MEMOEDIT() Configurable Keys
            ---------------------------------------------------------------
            Key                  Purpose
            ---------------------------------------------------------------
            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
            ---------------------------------------------------------------

            Word-wrapping: Word-wrapping is a state you toggle by
            RETURNing a 34 from the user function.  The default is on.
            When word-wrap is on, MEMOEDIT() inserts a soft carriage
            return/line feed at the closest word break to the window
            border or line length which ever occurs first.  When
            word-wrap is off, MEMOEDIT() scrolls text entry beyond the
            window definition until you reach the end-of-line.  At this
            point, you must press Return (inserting a hard carriage
            return/line feed) to advance to the next line.

            Note that soft carriage returns may interfere with the
            result of display commands such as ? and REPORT FORM or
            processing with another word processor.  Use HARDCR() and
            MEMOTRAN() to replace these embedded characters as needed.

            Paragraph reform: Pressing Ctrl-B or RETURNing a 2 from
            a user function reformats the memo until a hard carriage
            (end-of-paragraph) or the end-of-memo is encountered.  This
            happens regardless of whether word-wrap is on or off.

            Tab characters: When you specify the tab size argument
            (<expN6>), MEMOEDIT() inserts a hard tab character (09H) in
            the text when Tab is pressed.  If the tab size argument has
            not been specified, MEMOEDIT() inserts space characters
            instead.  The size of tabs is global for the entire memo and
            set with <expN6>.  The default is four.

            Note that MEMOEDIT() does not convert existing tab
            characters to spaces.

Library:    EXTEND.LIB


----------------------------------- Examples -------------------------------

   To display a memo field without editing:

   SET CURSOR OFF
   MEMOEDIT(Memo, 5, 10, 20, 69, .F.)
   SET CURSOR ON

   To edit the current memo field:

   REPLACE Memo WITH;
      MEMOEDIT(Memo, 5, 10, 20, 69, .T.)

   To create a character string using the full screen:

   note = MEMOEDIT()

   This example demonstrates a user-defined function that edits a memo
   field in a box with a title:

   FUNCTION EditMemo
   PARAMETERS memo, title, tr, tc, br, bc
   PRIVATE temp_scr
   SAVE SCREEN TO temp_scr
   @ tr - 1, tc - 2 CLEAR TO br + 1, bc + 2
   @ tr - 1, tc - 2 TO br + 1, bc + 2
   @ tr - 1, tc SAY "[" + title + "]"
   var  = MEMOEDIT(memo, tr, tc, br, bc, .T.)
   RESTORE SCREEN FROM temp_scr
   RETURN (var)

   For an advanced example that demonstrates a full-featured MEMOEDIT()
   using a user function, see Me.prg on the Clipper distribution disk.
   Note that you must compile and link it before using it.