READ

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

Seealso

@…GET, @…SAY, CLEAR GETS, LASTKEY(), READEXIT()

ReadKey()

READKEY()*

Determine which key terminated a READ.

Syntax

      READKEY() --> nKeyCode

Arguments

None.

Returns

READKEY() returns a numeric code representing the key that caused READ to terminate.

Description

READKEY() is used after a READ was terminated to determine the exit key pressed. If the GET buffer was updated during READ, 256 is added to the return code.

      Exit               Return code     Return code
      Key                (not updated)   (updated)
      ------------------ --------------  ----------------
      Up                    4            260
      Down                  5            261
      Page-Up               6            262
      Page-Down             7            263
      Ctrl Page-Up         34            290
      Ctrl Page-Down       35            291
      Esc                  12            268
      Ctrl End             14            270
      Enter                15            271
      Key >= 32            15            271
      otherwise             0            0

READKEY() is a compatibility function so try not to use it. READKEY() is superseded by LASTKEY() which returns the INKEY() code for that key. UPDATED() could be used to find if the GET buffer was changed during the READ.

Compliance

READKEY() is compliant with CA-Cl*pper 5.3

Files

Library is rtl

Seealso

@…GET, INKEY(), LASTKEY(), READ, READEXIT(), UPDATED()

NextKey()

NEXTKEY()

Get the next key code in the buffer without extracting it.

Syntax

      NEXTKEY( [<nInputMask>] ) --> nKey

Arguments

nInputMask is an optional integer value composed of one or more INKEY_ or HB_INKEY_ constants. The sole purpose of this argument is to allow switching between using HB_INKEY_EXTENDED key codes and using the normal CA-Cl*pper-compatible key codes

Returns

<nKey> The value of the next key in the Harbour keyboard buffer.

Description

Returns the value of the next key in the Harbour keyboard buffer without extracting it.

Examples

      // Use NEXTKEY() with INKEY() to change display characters, or by
      // itself to exit the loop, so that the caller can detect the Esc.
      LOCAL nKey, cChar := "+"
      DO WHILE .T.
         ?? cChar
         nKey := NextKey()
         IF nKey == K_ESC
            EXIT
         ELSE
            IF nKey != 0
               cChar := Chr( nKey )
            ENDIF
         ENDIF
      ENDDO

Tests

      KEYBOARD "AB"; ? NEXTKEY(), NEXTKEY() ==>   65   65

Compliance

NEXTKEY() is compliant with CA-Cl*pper 5.3, but has been extended for Harbour.

Files

Library is rtl

Seealso

INKEY(), LASTKEY()

LastKey()

LASTKEY()

Get the last key extracted from the keyboard buffer.

Syntax

      LASTKEY( [<nInputMask>] ) --> nKey

Arguments

nInputMask is an optional integer value composed of one or more INKEY_ or HB_INKEY_ constants. The sole purpose of this argument is to allow switching between using HB_INKEY_EXTENDED key codes and using the normal CA-Cl*pper-compatible key codes

Returns

<nKey> The last key extracted from the keyboard buffer.

Description

Returns the value of the last key exttracted from the Harbour keyboard buffer

Examples

      // Continue looping unless the ESC key was pressed in MainFunc()
      DO WHILE .T.
         MainFunc()
         IF LastKey() == K_ESC
            EXIT
         ENDIF
      ENDDO

Tests

      KEYBOARD "AB"; ? INKEY(), LASTKEY() ==>   65   65

Compliance

LASTKEY() is compliant with CA-Cl*pper 5.3, but has been extended for Harbour.

Files

Library is rtl

Seealso

INKEY(), LASTKEY()

SP_GETAKEY

GETAKEY()

  Short:
  ------
  GETAKEY() Gets intent of last keystroke

  Returns:
  --------
  <cIntent> as key direction (FWD,BWD,ESC,CTW,UNK)

  Syntax:
  -------
  GETAKEY(nKeyVal)

  Description:
  ------------
  Gives key direction of last key, for evaluating what
  direction in a read the user is heading.

  Examples:
  ---------
   If GETAKEY(LASTKEY())=="FWD"
       nActive_field++
   elseif GETAKEY(LASTKEY())=="BWD"
       nActive_field--
   endif

  Source:
  -------
  S_GETKEY.PRG