xHarbour Reference Documentation > Command Reference

READ

Activates editing of @...GET entry fields in text mode.

Syntax

 READ [SAVE] ;
      [MENU <oTopBarMenu>] ;
    [MSG AT <nRow>, <nLeft>, <nRight>] ;
       [MSG COLOR <cColor>]

Arguments

SAVE

If SAVE is specified, the GetList array holding the Get objects declared with @...GET remains intact when READ is terminated. By default, the GetList array is emptied when READ is complete.

MENU <oTopBarMenu>

Optionally, a TopBarMenu() object can be specified. In this case, the menu can be activated during READ.

MSG AT <nRow>, <nLeft>, <nRight>

This option specifies three numeric values as screen coordinates for the region where the message of the active Get object is displayed. <nRow> is the screen row, while <nLeft> and <nRight> are the column boundaries for message display. A message is defined with the MESSAGE option of the @...GET command.

MSG COLOR <cColor>

The parameter <cColor> is an optional character string defining the color for the message to display.

Description

The READ command activates full screen editing of all Get objects previously declared with @...GET commands. A user can enter data in the displayed entry fields and navigate between them. Editing starts with the first entry field, unless the WHEN clause of @...GET indicates that editing is not allowed. In this case, the next entry field that is allowed to be edited is activated and receives input focus.

When a user changes to the next entry field, a VALID condition, if present, is evaluated with the current value of the entry field. If this data validation fails, input focus remains with the current entry field, otherwise the next Get object, or entry field, receives input focus.

The READ command recognizes different types of keyboard input for editing entry fields, navigating between them, and terminating data entry:

Keys for navigation

Key	Description
Left	Moves cursor one character to the left
Ctrl+Left	Moves cursor one word to the left
Right	Moves cursor one character to the right
Ctrl+Right	Moves cursor one word to the right
Home	Moves cursor to the first character
End	Moves cursor to the last character
Comma | Period	Moves cursor to behind decimal point
	(only when numeric values are edited)
Up	Activates previous GET
Down	Activates next GET
Ctrl+Home	Activates the first GET
Return	Activates next GET

Keys for editing

Key	Description
ASCII character	Changes the edit buffer (if PICTURE format permits)
Backspace	Deletes one character left of the cursor
Ctrl+Backspace	Deletes one word left of the cursor
Ctrl+T	Deletes one word right of the cursor
Ctrl+U	Undo changes
Ctrl+Y	Deletes all characters from cursor to the end
Delete	Deletes one character at the cursor position
Insert	Toggles insert mode

Keys for terminating READ

Key	Description
Esc	Terminates READ and discards the currently
	edited value
Down	Terminates READ when the last GET has input focus
	and when ReadExit() is .T. (true)
Up	Terminates READ when the first GET has inout focus
	and when ReadExit() is .T. (true)
Return	Terminates READ when the last GET has input focus
Page Down, Page Up	Terminates READ and assigns the currently
and Ctrl+W	edited value

Info

See also:	@...GET, @...SAY, CLEAR GETS, Get(), LastKey(), ReadModal(), TopBarMenu()
Category:	Get system , Input commands
Source:	rtl\getsys.prg, rtl\tgetlist.prg
LIB:	xhb.lib
DLL:	xhbdll.dll