Código: Selecionar todos
xHarbour Reference Documentation > Function Reference
MemoEdit()
Displays and/or edits character strings and memo fields in text mode.
Syntax
MemoEdit( [<cString>] , ;
[<nTop>] , ;
[<nLeft>] , ;
[<nBottom>] , ;
[<nRight>] , ;
[<lEditMode>] , ;
[<cUserFunc>] , ;
[<nLineLen>] , ;
[<nTabSize>] , ;
[<nBufferRow>], ;
[<nBufferCol>], ;
[<nRowOffset>], ;
[<nColOffset>] ) --> cTextBuffer
Arguments
<cString>
A character string to be copied to the text buffer. The text buffer is displayed by MemoEdit() and can be edited by the user. The default value is an empty string ("").
<nTop>
A numeric value indicating the screen coordinate for the top row of the MemoEdit() display rectangle. The default value is 0.
<nLeft>
A numeric values indicating the screen coordinate for the left column of the MemoEdit() display rectangle. The default value is 0.
<nBottom>
A numeric value indicating the screen coordinate for the bottom row of the MemoEdit() display rectangle. The default value is MaxRow().
<nRight>
A numeric values indicating the screen coordinate for the right column of the MemoEdit() display rectangle. The default value is MaxCol().
<lEditMode>
The default value is .T. (true), indicating that a user can edit the text buffer maintained by MemoEdit(). If .F. (false) is passed, MemoEdit() displays the characater string <cString> within the boundaries of its display rectangle. The user can scroll the displayed text but cannnot edit the text buffer.
<cUserFunc>
A character string holding the name of a user defined function. The function must be visible in the entire application, i.e. it must not be declared as STATIC FUNCTION. <cUserFunc> allows for modifying the standard edit behavior of MemoEdit() (see description below). As an alternative, the value .F. (false) can be passed for <cUserFunc>. This causes MemoEdit() to display <cString> in the specified rectangle and return immediately. The passed string can neither be scrolled nor edited.
<nLineLen>
A numeric value specifying the number of characters that can appear in a single line of the text buffer. The default value is <nRight> - <nLeft>. If a single text line in the text buffer contains more than <nLineLen> characters, the text line is word wrapped.
If <nLineLen> is specified as being larger than <nRight> - <nLeft> of the display rectangle, and the user navigates the text cursor to a column position beyond the coordinates of the MemoEdit() rectangle, the displayed text is scrolled horizontally.
<nTabSize>
A numeric value specifying the number of spaces a Tab character (Chr(9)) contained in <cString> should be replaced with in the displayed text buffer. The default value is 3 spaces.
<nBufferRow>
A numeric value specifying the first text buffer row to be displayed in the top screen row of the display rectangle. The default value is 1.
<nBufferCol>
A numeric value specifying the first text buffer column to be displayed in the left screen column of the display rectangle. The default value is 0.
<nRowOffset>
A numeric value specifying the row offset for initial positioning of the edit cursor. The default value is 0, i.e. the edit cursor is displayed in the first row of the display rectangle.
<nColOffset>
A numeric value specifying the column offset for initial positioning of the edit cursor. The default value is <nBufferCol>, i.e. the edit cursor is displayed in the specified column of the display rectangle, which is the first column, by default. Return
The return value of MemoEdit() depends on the key a user pressed to terminate the function.
Alt+W When the user pressed the key combination Alt+W (K_ALT_W), the edited text buffer is returned as a character string.
Esc When the user pressed the Escape key (K_ESC), the return value is a copy of <cString>.
Description
MemoEdit() is a function for editing character strings, or memo fields, in console windows or full screen applications. The function provides a character oriented user interface and processes user input for editing text. Similar to AChoice() and DbEdit(), MemoEdit() employs a standard behaviour that can be configured by a user defined function <cUserFunc>.
Altough MemoEdit() is equipped with an extensive parameter profile, it is simple to use since all parameters are optional. The simplest form of using MemoEdit() is given by this line of code:
cText := MemoEdit()
Assigning the return value of MemoEdit() to a memory variable invokes the standard text editing behaviour of the function, i.e. the entire console window, or screen, is used for displaying the internal text buffer. The edited text is assigned to a memory variable when the user terminates text editing by pressing Alt+W. If text editing is ended with the Escape key, MemoEdit() returns an unchanged copy of <cString>.
It is important to understand that the user edits only the internal text buffer. This internal buffer is filled with a copy of parameter <cString>, if specified. All other parameters for row and column coordinates change the default (initial) display of the rectangle where text is displayed and can be edited by the user.
Whether or not MemoEdit() exposes standard or user-configured text editing behavior depends on the parameter <cUserFunc>, which is a character string containing the name of a user defined function.
MemoEdit() without user function
In its standard behavior, MemoEdit() processes the keys listed in the following table:
Standard key processing of MemoEdit() Key Description
Navigation in the text buffer
Up (Ctrl+E) Go to previous line
Down (Ctrl+X) Go to next line
Left (Ctrl+S) Go to previous character
Right(Ctrl+D) Go to next character
Ctrl+Left (Ctrl+A) Go to previous word
Ctrl+Right (Ctrl+F) Go to next word
Home Go to begin-of-line
End Go to end-of-line
Ctrl+Home Go to first displayed line
Ctrl+End Go to last displayed line
PgUp Go to previous page
PgDn Go to next page
Ctrl+PgUp Go to first line
Ctrl+PgDn Go to last line
Editing the text buffer
Printable characters Insert character
Return Begin a new paragraph
Delete Delete character at cursor
Backspace Delete character to left of cursor
Tab Insert tab character or spaces
Ctrl+Y Delete the current line
Ctrl+T Delete word right
Ctrl+B Reformat paragraph
Ctrl+V (Ins) Toggle insert/overstrike mode
Alt+W Terminate editing with changes
Esc Terminate editing without changes
Keys are grouped into the tasks navigation within the text buffer and editing it. MemoEdit() supports insert and overstrike modes, which is toggled by the Ins key. An automatic word wrap is applied to the text buffer when the number of characters entered in the current text line exceeds the value for parameter <nLineLen>. This word wrap is marked in the text buffer with a so called "Soft carriage return" (Chr(141)) which indicates the end-of-line, not the end-of-paragraph. The latter is marked in the text when the user presses the Return key. This inserts a "Hard carriage return" (Chr(13)) into the text buffer.
Note that "Soft carriage returns" remain in the text returned my MemoEdit(). When this text is output to a printer, or processed otherwise, it may be necessary to replace "Soft carriage returns" with blank spaces or "Hard carriage returns". The functions HardCR(), MemoTran() or StrTran() can be used to accomplish this.
MemoEdit() with user function
If a user function <cUserFunc> is specified, the standard editing behavior of MemoEdit() becomes configurable. For this, MemoEdit() distinguishes non-configurable keys from key-exceptions. The function applies its default action to the text buffer, when non-configurable keys are pressed. The user function is called for keys that yield an exception, and the return value of the user function instructs MemoEdit() how to process such a key. If there are no more keys pending in the keyboard buffer, the user function is called once again. As a consequence, the user function is called during different MemoEdit() modes.
The user function receives three numeric values from MemoEdit(): the current MemoEdit() mode, the current row, and the current column of the text buffer. #define constants are available in MEMOEDIT.CH that identify the different modes of MemoEdit().
MemoEdit() modes Constant Mode Description
ME_IDLE 0 MemoEdit() is idle, all keys are processed
ME_UNKEY 1 Unknown key, text buffer is unaltered
ME_UNKEYX 2 Unknown key, text buffer is altered
ME_INIT 3 Initialization mode
ME_INIT The user function is called for the first time when MemoEdit() is invoked. At this point, MemoEdit() is initializing its text buffer and has not displayed it yet. The return value of the user function can be used at this stage to initialize word wrapping or the scrolling mode of MemoEdit() (see ME_TOGGLEWRAP and ME_TOGGLESCROLL in the table further down). The user function is called repeatedly in the initialization stage of MemoEdit() until the value ME_DEFAULT (0) is returned. After this, the text buffer is displayed and MemoEdit() continues key processing according to <lEditMode>. That is, if <lEditMode> is .F. (false), the user can scroll the text but cannot edit it.
ME_UNKEY This mode tells the user function that a configurable (unknown) key is pressed and the text buffer is not altered, yet. The return value of the user function instructs MemoEdit() how to treat a configurable key. Use function LastKey() to obtain the Inkey code of such key.
Configurable keys of MemoEdit() Key Default key processing
Ctrl+Y Delete the current line
Ctrl+T Delete word right
Ctrl+B Reformat paragraph
Ctrl+V (Ins) Toggle insert/overstrike mode
Alt+W Terminate editing with changes
Esc Terminate editing without changes
Returning ME_DEFAULT (0) from the user function for a configurable key instructs MemoEdit() to perform its default action. A different return value causes a different action, thus redefines the key (return values from the user function are explained further down).
ME_UNKEYX The same as ME_UNKEY, but the text buffer is altered.
ME_IDLE There are no more keys avalable in the keyboard buffer for processing. MemoEdit() calls the user function once in this situation and enters a wait state afterwards, until a new key is pressed. This mode is usually used to update row and column numbers on the screen if this information is presented to the user.
The second parameter passed to the user function is the current row in the text buffer. Rows are numbered beginning with 1.
The third parameter passed to the user function is the current column in the text buffer. Columns are numbered beginning with 0.
During the modes ME_INIT, ME_UNKEY and ME_UNKEYX, the return value of the user function instructs MemoEdit() what action to take for the pressed key. There are several #define constants available in MEMOEDIT.CH for this purpose.
Return values for the MemoEdit() user function Constant Value Description
ME_DEFAULT 0 Perform default action
ME_UNKEY 1-31 Process requested action corresponding to key code
ME_IGNORE 32 Ignore unknown key
ME_DATA 33 Treat unknown key as data
ME_TOGGLEWRAP 34 Toggle word wrap mode
ME_TOGGLESCROLL 35 Toggle scroll mode
ME_WORDRIGHT 100 Perform word-right operation
ME_BOTTOMRIGHT 101 Perform bottom-right operation
Info
See also: HardCR(), MemoLine(), MemoRead(), MemoTran(), MemoWrit(), StrTran()
Category: Character functions , Memo functions , UI functions
Header: inkey.ch, memoedit.ch
Source: rtl\memoedit.prg
LIB: xhb.lib
DLL: xhbdll.dll
Example
// The example implements a simple file editor using MemoEdit()
// with user function. The user function displays status information
// and configures the Alt+S (Save) and Alt+C (Cancel) as termination
// keys
#include "Inkey.ch"
#include "Memoedit.ch"
STATIC slChanged := .F.
PROCEDURE Main( cFileName )
LOCAL cScreen
LOCAL cText := ""
SAVE SCREEN TO cScreen
SET SCOREBOARD OFF
SetCancel( .F. )
CLS
IF .NOT. Empty( cFileName ) .AND. File( cFileName )
cText := MemoRead( cFileName )
ENDIF
@ 0, 0 TO MaxRow(), MaxCol() DOUBLE
cText := MemoEdit( cText, ;
1, 1 , ;
MaxRow()-1, MaxCol()-1, ;
.T., "USERFUNC" )
IF .NOT. Empty( cFileName ) .AND. ;
File( cFileName ) .AND. ;
slChanged .AND. ;
Alert( "Save changes?", { "Yes", "No" } ) == 1
// remove "soft carriage return/line feeds"
cText := StrTran( cText, Chr(141)+Chr(10), " " )
// save file
MemoWrit( cFileName, cText )
ENDIF
RESTORE SCREEN FROM cScreen
RETURN
FUNCTION UserFunc( nMode, nRow, nCol )
LOCAL nKey := LastKey()
LOCAL nRet := ME_DEFAULT
LOCAL cInfo := ""
DO CASE
CASE nMode == ME_INIT
Set( _SET_INSERT, .F. ) // start in overstrike mode
CASE nMode == ME_IDLE
IF nKey > 31 .AND. nKey < 256
slChanged := .T.
ENDIF
cInfo := "[row: " + LTrim(Str(nRow))
cInfo += " col: " + LTrim(Str(nCol))+"]"
cInfo += Chr(205)+Chr(205)
IF Set( _SET_INSERT )
cInfo += "[Ins]"
ELSE
cInfo += "[Ovr]"
ENDIF
IF slChanged
cInfo += Chr(205)+Chr(205)+"[Chg]"
ENDIF
@ MaxRow(), 2 SAY cInfo + Replicate(Chr(205),6)
CASE nMode == ME_UNKEY .OR. nMode == ME_UNKEYX
// buffer is changed
slChanged := ( nMode == ME_UNKEYX )
DO CASE
CASE nKey IN { K_ALT_W, K_CTRL_W, K_ESC }
nRet := ME_IGNORE // ignore default termination keys
CASE nKey == K_ALT_S
nRet := K_ALT_W // Save with Alt+S
CASE nKey == K_ALT_C
nRet := K_ESC // Cancel with Alt+C
slChanged := .F.
ENDCASE
ENDCASE
RETURN nRet
--------------------------------------------------------------------------------