[<<Previous Entry]
[^^Up^^]
[Next Entry>>]
[Menu]
[About The Guide]
READ
Activate full-screen editing mode using Get objects
------------------------------------------------------------------------------
Syntax
READ [SAVE] [MENU <oMenu>] [MSG AT <nRow>, <nLeft>,
<nRight>] [MSG COLOR <cColorString>]
Arguments
SAVE retains the contents of the current GetList after the READ
terminates. Later, you can edit the same Get objects by issuing another
READ. If not specified, the current GetList is assigned an empty array
deleting all of the previous Get objects when the READ terminates.
MENU <oMenu> specifies an optional Topbarmenu object that, when
supplied, permits menu selection during data entry.
MSG AT <nMsgRow>, <nMsgLeft>, <nMsgRight> specify the row,
left, and right margins where the Get object messages appear on the
screen. If omitted, messages will not appear.
MSG COLOR <cMsgColor> defines the color setting of the message area.
It consists of a single foreground/background color pair.
Description
READ executes a full-screen editing mode using all Get objects created
and added to the current GetList since the most recent CLEAR, CLEAR
GETS, CLEAR ALL or READ commands. If there is a format procedure
active, READ executes that procedure before entering the full-screen
editing mode.
Within a READ, the user can edit the buffer of each Get object as well
as move from one Get object to another. Before the user can enter a Get
object, control passes to the associated WHEN <lPreCondition> if one has
been assigned to that Get object. If <lPreCondition> returns true
(.T.), the user is allowed to edit the buffer of the Get object.
Otherwise, control passes to the next Get object in the GetList. Within
a GET buffer, the user can edit using the full complement of editing and
navigation keys. See the tables below.
When the user presses a GET exit key, control passes to the associated
RANGE or VALID postcondition if one has been specified. If either
condition returns true (.T.), editing of the Get object is terminated
and control passes to the next Get object. Otherwise, control remains
within the current Get object until a valid value is entered or the user
presses the Esc key.
When the user successfully enters a value into a Get object, the
associated variable is assigned the value of the Get object's buffer.
The following tables list active keys within a READ:
READ Navigation Keys
------------------------------------------------------------------------
Key Action
------------------------------------------------------------------------
Left arrow, Ctrl+S Character left. Does not move cursor to
previous GET.
Right arrow, Ctrl+D Character right. Does not move cursor to
next GET.
Ctrl+Left arrow, Ctrl+A Word left.
Ctrl+Right arrow, Ctrl+F Word right.
Up arrow, Shift+Tab, Ctrl+E Previous GET.
Down arrow, Tab, Ctrl+X, Return, Ctrl+M Next GET.
Home First character of GET.
End Last character of GET.
Ctrl+Home Beginning of first GET.
------------------------------------------------------------------------
READ Editing Keys
------------------------------------------------------------------------
Key Action
------------------------------------------------------------------------
Del, Ctrl+G Delete character at cursor position
Backspace, Ctrl+H Destructive backspace
Ctrl+T Delete word right
Ctrl+Y Delete from cursor position to end of GET
Ctrl+U Restore current GET to original value
------------------------------------------------------------------------
READ Toggle Keys
------------------------------------------------------------------------
Key Action
------------------------------------------------------------------------
Ins, Ctrl+V Toggle insert mode
------------------------------------------------------------------------
READ Exit Keys
------------------------------------------------------------------------
Key Action
------------------------------------------------------------------------
Ctrl+W, Ctrl+C, PgUp, PgDn Terminate READ saving current GET
Return, Ctrl+M Terminate READ from last GET
Esc Terminate READ without saving current GET
Up arrow Terminate READ from first GET if
READEXIT()=.T.
Down arrow Terminate READ from last GET if
READEXIT()=.T.
------------------------------------------------------------------------
Notes
. Nested READs: To perform a nested READ within a SET KEY,
VALID, or WHEN procedure or user-defined function, declare or create
a new GetList, perform a series of @...GET statements, and then READ.
When the procedure terminates, the new GetList is released and the
previous GetList becomes visible again. See the example below.
. Quick keys: Pressing Home or End in quick succession goes to
the first or last nonblank character in a Get object's buffer.
. Terminating a READ: A READ is terminated by executing a BREAK,
CLEAR, CLEAR GETS, or CLEAR ALL from within a SET KEY procedure or a
user-defined function initiated by VALID.
. UPDATED(): If any Get object buffer was changed during the
current READ, UPDATED() is set to true (.T.).
Examples
. This example defines several GETs then READs them:
CLEAR
cVar1 := cVar2 := cVar3 := SPACE(10)
@ 10, 10 SAY "Variable one:" GET cVar1 VALID ;
!EMPTY(cVar1)
@ 11, 10 SAY "Variable two:" GET cVar2 ;
WHEN RTRIM(cVar1) != "One"
@ 12, 10 SAY "Variable three:" GET cVar3 VALID ;
!EMPTY(cVar3)
READ
. This example performs a nested READ within a SET KEY, WHEN, or
VALID procedure or user-defined function:
LOCAL cName := SPACE(10)
@ 10, 10 GET cName VALID SubForm( cName )
READ
RETURN
FUNCTION SubForm( cLookup )
LOCAL GetList := {} // Create new GetList
USE Sales INDEX Salesman NEW
SEEK cLookup
IF FOUND()
@ 15, 10 GET Salesman // Add Get objects to
@ 16, 10 GET Amount // new GetList
READ // READ from new GetList
ENDIF
CLOSE Sales
RETURN .T. // Release new GetList
Files Library is CLIPPER.LIB.
See Also:
@...GET
@...SAY
CLEAR GETS
LASTKEY()
READEXIT()
This page created by ng2html v1.05, the Norton guide to HTML conversion utility.
Written by Dave Pearson