harbour-core/doc/en/inputall.txt

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Inkey()
   $CATEGORY$
      API
   $SUBCATEGORY$
      User interface
   $ONELINER$
      Extracts the next key code from the Harbour keyboard buffer.
   $SYNTAX$
      Inkey( [<nTimeout>] [, <nEvents>] ) --> nKey
   $ARGUMENTS$
      <nTimeout> is an optional timeout value in seconds, with a granularity
      of 1/10th of a second. If omitted, Inkey() returns immediately. If set
      to 0, Inkey() waits until an input event occurs. If set to any other
      value, Inkey() will return either when an input event occurs or when
      the timeout period has elapsed. If only this parameter is specified
      and it is not numeric, it will be treated as if it were 0. But if both
      parameters are specified and this parameter is not numeric, it will be
      treated as if it were not present.

      <nEvents> is an optional mask of input events that are to be enabled.
      If omitted, defaults to `hb_set.HB_SET_EVENTMASK`. Valid input masks are
      in inkey.ch and are explained below. It is recommended that the mask
      names be used rather than their numeric values, in case the numeric
      values change in future releases of Harbour. To allow more than one
      type of input event, simply add the various mask names together.

      <table>
       inkey.ch            Meaning

       INKEY_MOVE          Mouse motion events are allowed
       INKEY_LDOWN         The mouse left click down event is allowed
       INKEY_LUP           The mouse left click up event is allowed
       INKEY_RDOWN         The mouse right click down event is allowed
       INKEY_RUP           The mouse right click up event is allowed
       INKEY_KEYBOARD      All keyboard events are allowed
       INKEY_ALL           All mouse and keyboard events are allowed
       HB_INKEY_EXTENDED   Extended keyboard codes are used.
      </table>

      If the parameter is not numeric, it will be treated as if it were set
      to `hb_set.HB_SET_EVENTMASK`.
   $RETURNS$
      0 in case of timeout with no input event, otherwise returns a value
      in the range -47 to 386 for keyboard events or the range 1001 to 1007
      for mouse events. Mouse events and non-printable keyboard events are
      represented by the `K_<event>` values listed in inkey.ch. Keyboard
      event return codes in the range 32 through 127 are equivalent to the
      printable ASCII character set. Keyboard event return codes in the
      range 128 through 255 are assumed to be printable, but results may
      vary based on hardware and nationality. If HB_INKEY_EXTENDED mode is
      used, then the return value for keyboard events ranges from 1 through
      767 and 1077 through 1491, although not all codes are used.

      Extended key codes consist of the PC keyboard scan code and one
      or more offset values. If no keyboard modifier was used, then
      HB_INKEY_NONE is added. The <Alt> key adds HB_INKEY_ALT, the <Ctrl>
      key adds HB_INKEY_CTRL, the <Shift> key adds HB_INKEY_SHIFT, and
      enhanced keys (<KeyPad+/> and <CursorPad> keys) add HB_INKEY_ENHANCED.
      For example, <F1> is scan code 59, so if you just press <F1>, you get
      key code 315, but <Alt+F1> gives 443, <Ctrl+F1> gives 571, and <Shift+F1>
      gives 699. And <NumPad+/> gives 1077, 1205, 1333, and 1461. At
      this time, the only value that can combine with other values is
      HB_INKEY_ENHANCED (i.e., there are no <Alt+Ctrl> combinations, etc.)

      Note: The extended key code set is larger than the normal key code
      set. As a result, if you switch between the normal and extended
      modes, you need to be aware that some codes get translated into a
      zero in normal mode (because there is no corresponding code in
      normal mode) and that these codes get removed from the keyboard
      input buffer in normal mode and you won't be able to go back and
      fetch them later in extended mode.
   $DESCRIPTION$
      Inkey() can be used to detect input events, such as key-press, mouse
      movement, or mouse key clicks (up and/or down).
   $EXAMPLES$
      #include "inkey.ch"
      // Wait for the user to press the <Esc> key
      ? "Please press the <Esc> key."
      DO WHILE Inkey( 0.1 ) != K_ESC
      ENDDO

      KEYBOARD "AB"; ? Inkey(), Inkey()  // -->   65   66
   $STATUS$
      S
   $COMPLIANCE$
      Inkey() is compliant with the CA-Cl*pper 5.3 Inkey() function with one
      exception: The Harbour Inkey() function will raise an argument error
      if the first parameter is less than or equal to 0 and the second
      parameter (or the default mask) is not valid, because otherwise Inkey()
      would never return, because it was, in effect, asked to wait forever
      for no events (Note: In CA-Cl*pper, this also blocks `SET KEY` events).
   $FILES$
      Library is core
      Header is inkey.ch
   $SEEALSO$
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Procedure
   $NAME$
      __Keyboard()
   $CATEGORY$
      API
   $SUBCATEGORY$
      User interface
   $ONELINER$
      Use hb_keyPut() instead
   $SYNTAX$
      KEYBOARD <cString>
      CLEAR TYPEAHEAD
   $ARGUMENTS$
      <cString> is the optional string to stuff into the Harbour keyboard
      buffer after clearing it first.

      Note: The character `;` is converted
      to `Chr( 13 )` (this is an undocumented CA-Cl*pper feature).
   $DESCRIPTION$
      Clears the Harbour keyboard type-ahead buffer and then inserts an
      optional string into it.
   $EXAMPLES$
      // Stuff an Enter key into the keyboard buffer
      KEYBOARD Chr( 13 )
      // Clear the keyboard buffer
      CLEAR TYPEAHEAD

      KEYBOARD Chr( 13 ); ? Inkey()  // --> 13
      KEYBOARD ";"; ? Inkey()  // --> 13
      KEYBOARD "Hello"; CLEAR TYPEAHEAD; ? Inkey()  // --> 0
   $STATUS$
      R
   $COMPLIANCE$
      C
   $FILES$
      Library is core
   $SEEALSO$
      CLEAR TYPEAHEAD, KEYBOARD
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_keyPut()
   $CATEGORY$
      API
   $SUBCATEGORY$
      User interface
   $ONELINER$
      Put an inkey code to the keyboard buffer.
   $SYNTAX$
      hb_keyPut( <nInkeyCode> )
   $ARGUMENTS$
      <nInkeyCode> is the inkey code, which should be inserted into the
      keyboard buffer.
   $RETURNS$
      There is no return value.
   $DESCRIPTION$
      Inserts an inkey code to the string buffer. The buffer is *not*
      cleared in this operation. This function allows to insert such
      inkey codes which are not in the range of 0 to 255. To insert more
      than one code, call the function repeatedly. The zero code cannot
      be inserted.
   $EXAMPLES$
      #include "inkey.ch"
      // Stuff an <Alt+PgDn> key into the keyboard buffer
      hb_keyPut( K_ALT_PGDN ); ? Inkey()  // --> 417
      hb_keyPut( K_F11 ); ? Inkey()  // --> -40
   $STATUS$
      R
   $COMPLIANCE$
      H
   $FILES$
      Library is core
   $SEEALSO$
      KEYBOARD, CLEAR TYPEAHEAD, Inkey()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      NextKey()
   $CATEGORY$
      API
   $SUBCATEGORY$
      User interface
   $ONELINER$
      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$
      #include "inkey.ch"
      // 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()
         DO CASE
         CASE nKey == K_ESC
            EXIT
         CASE nKey != 0
            cChar := hb_keyChar( nKey )
         ENDCASE
      ENDDO

      KEYBOARD "AB"; ? NextKey(), NextKey()  // -->   65   65
   $STATUS$
      R
   $COMPLIANCE$
      NextKey() is compliant with CA-Cl*pper 5.3, but has been extended
      for Harbour.
   $FILES$
      Library is core
   $SEEALSO$
      Inkey(), LastKey()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      LastKey()
   $CATEGORY$
      API
   $SUBCATEGORY$
      User interface
   $ONELINER$
      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 extracted from the Harbour
      keyboard buffer
   $EXAMPLES$
      #include "inkey.ch"
      // Continue looping unless the <Esc> key was pressed in MainFunc()
      DO WHILE .T.
         MainFunc()
         IF LastKey() == K_ESC
            EXIT
         ENDIF
      ENDDO

      KEYBOARD "AB"; ? Inkey(), LastKey()  // -->   65   65

      STATIC PROCEDURE MainFunc()
         Inkey( 0 )
         RETURN
   $STATUS$
      R
   $COMPLIANCE$
      LastKey() is compliant with CA-Cl*pper 5.3, but has been extended
      for Harbour.
   $FILES$
      Library is core
   $SEEALSO$
      Inkey(), LastKey()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Command
   $NAME$
      KEYBOARD
   $CATEGORY$
      Command
   $SUBCATEGORY$
      User interface
   $ONELINER$
      Stuffs the keyboard with a string.
   $SYNTAX$
      KEYBOARD <cString>
   $ARGUMENTS$
      <cString> String to be processed, one character at a time,
      by the Harbour keyboard processor
   $DESCRIPTION$
      This command stuffs the input buffer with <cString>.

      The number of characters that can be stuffed into the keyboard
      buffer is controlled by the SET TYPEAHEAD command and may range
      from 0 to 32622, with each character being in the ASCII
      range of 0 to 255.

      None of the extended keys may be stuffed into the keyboard buffer.

      Issuing a `KEYBOARD " "` will clear the keyboard buffer.
   $EXAMPLES$
      // Stuff an Enter key into the keyboard buffer
      KEYBOARD Chr( 13 )
      // Clear the keyboard buffer
      CLEAR TYPEAHEAD

      KEYBOARD Chr( 13 ); ? Inkey()  // --> 13
      KEYBOARD "Hello"; CLEAR TYPEAHEAD; ? Inkey()  // --> 0
   $STATUS$
      R
   $COMPLIANCE$
      C
   $SEEALSO$
      CLEAR TYPEAHEAD, __Keyboard()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999 Chen Kedem <niki@actcom.co.il>
   $TEMPLATE$
      Function
   $NAME$
      ReadKey()*
   $CATEGORY$
      API
   $SUBCATEGORY$
      User interface
   $ONELINER$
      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.

      <table-doubleheader>
       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
      </table>

      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.
   $STATUS$
      R
   $COMPLIANCE$
      C
   $FILES$
      Library is core
   $SEEALSO$
      @...GET, Inkey(), LastKey(), READ, ReadExit(), Updated()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      MRow()
   $CATEGORY$
      API
   $SUBCATEGORY$
      User interface
   $ONELINER$
      Returns the mouse cursor row position.
   $SYNTAX$
      MRow() --> nMouseRow
   $ARGUMENTS$
      None
   $RETURNS$
      <nMouseRow> The mouse cursor row position.
   $DESCRIPTION$
      This function returns the current mouse row cursor position.
      On graphical systems the value represents pixel rows.
      On character-based systems the value represents character
      rows as in CA-Cl*pper.
   $EXAMPLES$
      IF MRow() < 1
         ? "Mouse is on top row!"
      ENDIF
   $STATUS$
      R
   $COMPLIANCE$
      MRow() is compliant with CA-Cl*pper 5.3, but has been extended
      to work on graphical systems as well as character-based systems.
   $PLATFORMS$

   $FILES$
      Library is core
   $SEEALSO$
      MCol()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      MCol()
   $CATEGORY$
      API
   $SUBCATEGORY$
      User interface
   $ONELINER$
      Returns the mouse cursor column position.
   $SYNTAX$
      MCol() --> nMouseColumn
   $ARGUMENTS$
      None
   $RETURNS$
      <nMouseColumn> The mouse cursor column position.
   $DESCRIPTION$
      This function returns the column position of the mouse cursor.
      On graphical systems the value represents pixels.
      On character-based systems the value represents character
      columns as in CA-Cl*pper.
   $EXAMPLES$
      IF MCol() < 1
         ? "Mouse is on left edge!"
      ENDIF
   $STATUS$
      R
   $COMPLIANCE$
      MCol() is compliant with CA-Cl*pper 5.3, but has been extended
      to work on graphical systems as well as character-based systems.
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      MRow()
   $END$
 */