Tag Archives: UI

ReadVar()

Posted on by vivaclipper

READVAR()

Return variable name of current GET or MENU

Syntax

      READVAR( [<cVarName>] ) --> cOldVarName

Arguments

<cVarName> is a new variable name to set.

Returns

READVAR() return the old variable name. If no variable previously was set, READVAR() return “”.

Description

READVAR() is set inside a READ or MENU TO command to hold the uppercase name of the GET / MENU TO variable, and re-set back to old value when those commands finished. You should not normally set a variable name but rather use it to retrieve the name of a GET variable when executing a VALID or WHEN clause, or during SET KEY execution and you are inside a READ or MENU TO.

Examples

      // display a menu, press F1 to view the MENU TO variable name
      CLS
      @ 1, 10 PROMPT "blood sucking insect that infect beds   "
      @ 2, 10 PROMPT "germ; virus infection                   "
      @ 3, 10 PROMPT "defect; snag; (source of) malfunctioning"
      @ 4, 10 PROMPT "small hidden microphone                 "
      @ 6, 10 SAY "(Press F1 for a hint)"
      SET KEY 28 TO ShowVar
      MENU TO What_Is_Bug

      PROCEDURE ShowVar
         Alert( ReadVar() )     // WHAT_IS_BUG in red ALERT() box

Compliance

READVAR() works exactly like CA-Cl*pper’s READKEY().

Note however, that the <cVarName> parameter is not documented and used internally by CA-Cl*pper.

Platforms

All

Files

Library is rtl

Seealso

@…GET, @…PROMPT, MENU TO, READ, SET KEY, __AtPrompt(), __MenuTo()

ReadKey()

Posted on by vivaclipper

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()

Posted on by vivaclipper

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()

MRow()

Posted on by vivaclipper

MROW()

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

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.

Files

Library is rtl

Seealso

MCOL()

MCol()

Posted on by vivaclipper

MCOL()

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

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 rtl

Seealso

MROW()

LastKey()

Posted on by vivaclipper

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()

KEYBOARD

Posted on by vivaclipper

KEYBOARD

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 32, 622, 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

Tests

      KEYBOARD CHR(13); ? INKEY() ==> 13
      KEYBOARD "HELLO"; CLEAR TYPEAHEAD; ? INKEY() ==> 0

Compliance

KEYBOARD is compliant with CA-Cl*pper 5.3

Seealso

CLEAR TYPEAHEAD, __KEYBOARD()

Inkey()

Posted on by vivaclipper

INKEY()

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.

        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.

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+Ctl 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 keypress, mouse movement, or mouse key clicks (up and/or down).

Examples

      // Wait for the user to press the Esc key
      ? "Please press the ESC key."
      DO WHILE Inkey( 0.1 ) != K_ESC
      ENDDO

Tests

      KEYBOARD "AB"; ? Inkey(), Inkey() ==>   65   66

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 rtl

Seealso

inkey.ch

hb_keyPut()

Posted on by vivaclipper

HB_KEYPUT()

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

      // Stuff an Alt+PgDn key into the keyboard buffer
      hb_keyPut( K_ALT_PGDN )

Tests

      hb_keyPut( K_ALT_PGDN ) ; ? INKEY() ==> 417
      hb_keyPut( K_F11 ) ; ? INKEY() ==> -40

Compliance

Harbour

Files

Library is rtl

Seealso

KEYBOARD, CLEAR TYPEAHEAD, INKEY()

__Keyboard()

Posted on by vivaclipper

Template

Procedure

Name

__Keyboard()

Category

API

Subcategory

User interface

Oneliner

DO NOT CALL THIS FUNCTION DIRECTLY!

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 typeahead 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

Compliance

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

Files

Library is core

Seealso

CLEAR TYPEAHEAD, KEYBOARD