Sometimes, however, an application simply needs for the user to press one or more keys and where a dedicated space on the user interface may not be desirable.

Here's a summary of the PowerBASIC GRAPHIC functions which handle keyboard inputs.

Remember that the GRAPHIC statements apply to the selected (ATTACHED) graphic target. If no graphic target (control, memory bitmap, or graphic window) has been created or one is not currently attached, the following statements will not produced the expected results!

Characters & Strings	GRAPHIC Inkey$, GRAPHIC WaitKey$, GRAPHIC Line Input
Variables	GRAPHIC Input
Buffer	GRAPHIC Flush, GRAPHIC InStat

Characters
With Inkey$ and WaitKey$ an application can capture a single key from the user.

    GRAPHIC Inkey$ TO result$      ' result$ is not optional
    GRAPHIC Waitkey$ TO result$    ' TO result$ is optional

Inkey$ returns the current content of the keyboard buffer. Waitkey$ causes the application to wait until a key is pressed before returning a value.

With both statements, the result$ will be 0-2 characters long. Len=0 means the buffer is empty. Inkey$ will not wait for a key to be pressed. Len=1 means an ASCII character was pressed and the character is in the string. Len=2 means an extended key was pressed. The first character is 0 and the second character is the extended keyboard code.

Strings
With Line Input an entire string can be captured. All keystrokes up to, but not including, the ENTER key are assigned to a string variable. Only one variable is allowed.

    GRAPHIC LINE INPUT "Please Enter Value:" result$

Up to 255 characters are allowed.

Variables
With GRAPHIC INPUT a list of strings and/or numbers can be entered, separated by a comma.

    GRAPHIC INPUT "Please Enter Values:", a$, b%, c$, d&

Entry is complete when ENTER is pressed. If not enough values are entered, remaining numeric variables are set to 0 and remaining string values are set to "".

Entries must match the data type of the variable - string or numeric.

Managing Keyboard Status
When a user presses a key, the PC places it in a buffer and waits for an application to read the key. If several keys are pressed, they are all placed on the buffer.

If an application is waiting for the user to press a key, it's possible the buffer may already have keys in it. So when the application takes the next key in the buffer, it may not be the key a user intended for the program to receive.

To solve that problem, PowerBASIC has the GRAPHIC INPUT FLUSH statement, which empties the keyboard buffer.

    GRAPHIC INPUT FLUSH          'no arguments

Also, a program may want to check to see keys have been pressed and are waiting to be received. The GRAPHIC INSTAT checks to see if the buffer is empty. It does not remove anything from the buffer.

    GRAPHIC INSTAT TO n%         '0 = empty (False   -1 = not empty (True)

Alternate Ways to Capture Text
In addition to the built-in GRAPHICS statements, a program can capture text in several other ways.

• Keyboard Events
  The Callback function for a dialog can also be used to respond to keyboard inputs from the user.

• Text-Based Controls
  Many of the Windows controls (textbox, combobox, ...) can be placed on a dialog and used to capture user keyboard inputs.

• InputBox (Dialog)
  The Windows INPUTBOX$ command displays a dialog which prompts a user to input a text string.

Keyboard Function Listing
Here's a simple listing of the string functions above, with a one-line description of what the function does. Syntax and examples are given in the next section.

• GRAPHIC INKEY$ - read keyboard character from the graphic target
• GRAPHIC INPUT - read data from keyboard from graphic window
• GRAPHIC INPUT FLUSH - write all buffered keyboard data
• GRAPHIC INSTAT - determine whether a keyboard character is ready
• GRAPHIC LINE INPUT - read an entire line from the keyboard from graphic window
• GRAPHIC WAITKEY$ - wait for keyboard character from graphic window

Keyboard Function Reference
Here are examples for each of the keyboard functions. The functions are listed in alphabetical order.

• GRAPHIC Inkey$ - reads a single character

      GRAPHIC Inkey$ TO result$      ' result$ is not optional
  

• GRAPHIC Input - reads a comma delimited list of variables

      GRAPHIC INPUT "Please Enter Values:", a$, b%, c$, d&
  

• GRAPHIC Input Flush - empties the keyboard buffer

      GRAPHIC INPUT FLUSH          'no arguments
  

• GRAPHIC InStat - checks if keyboard buffer is empty

      GRAPHIC INSTAT TO n%         '0 = empty (False   -1 = not empty (True)
  

• GRAPHIC Line Input - reads a string (press Enter to end)

      GRAPHIC LINE INPUT "Please Enter Value:" result$
  

• GRAPHIC Waitkey$ - waits for keyboard character

      GRAPHIC Waitkey$ TO result$    ' TO result$ is optional
  

• INPUTBOX$ - dialog box in which user enters text

      INPUTBOX$ "Enter Answer", "Input Box", "47"
      ? "Enter Answer", "Input Box", "47"     
     

  Note that the ? is recognized by PowerBASIC as a synonym for INPUTBOX$.

If you have any suggestions or corrections, please let me know.