SET TYPEAHEAD

SET TYPEAHEAD

Set the size of the keyboard buffer

Syntax

      SET TYPEAHEAD TO <nKeyboardSize>

Arguments

TO <nKeyboardSize> specifies the number of keystrokes the keyboard buffer can hold from a minimum of zero to a maximum of 4096. The default size of the keyboard buffer is machine-dependent but 16 is the minimum size.

Description

SET TYPEAHEAD defines the size of the Clipper keyboard buffer that caches keystrokes input directly by the user. SET TYPEAHEAD, however, does not affect the number of characters that can be stuffed programmatically using the KEYBOARD command. When executed, SET TYPEAHEAD clears the keyboard buffer and sets the size to <nKeyboardSize>.

When TYPEAHEAD is SET TO zero, keyboard polling is suspended. An explicit request for keyboard input, however, will temporarily enable the keyboard and read any pending keystrokes from the BIOS buffer. Calling NEXTKEY() constitutes such an explicit request. NEXTKEY() reads any pending keystrokes from the BIOS buffer and returns the INKEY() value of the first keystroke read, or zero if no keystrokes are pending.

Seealso

ALTD(), CLEAR, TYPEAHEAD, INKEY(), KEYBOARD, NEXTKEY()

CLEAR TYPEAHEAD

CLEAR TYPEAHEAD

Empty the keyboard buffer

Syntax

      CLEAR TYPEAHEAD

Description

CLEAR TYPEAHEAD is a keyboard command that clears all pending keys from the Clipper keyboard buffer. This is useful in user interface procedures or user-defined functions to guarantee that keys processed from the keyboard buffer are appropriate to the current activity and not pending from a previous activity. User functions called by ACHOICE() and DBEDIT() are especially sensitive to such keys.

Note that both the SET TYPEAHEAD and KEYBOARD commands also clear the keyboard buffer.

Examples

      .  This example empties the keyboard buffer before invoking
      DBEDIT(), guaranteeing that any pending keys will not be executed:
      CLEAR TYPEAHEAD
      DBEDIT()

Seealso

KEYBOARD, SET TYPEAHEAD

ACCEPT

ACCEPT*

Place keyboard input into a memory variable

Syntax

      ACCEPT [<expPrompt>] TO <idVar>

Arguments

<expPrompt> is an optional prompt displayed before the input area. The prompt can be an expression of any data type.

<idVar> is the variable that will hold input from the keyboard. If the specified <idVar> does not exist or is not visible, a private variable is created.

Description

ACCEPT is a console command and wait state that takes input from the keyboard and assigns it as a character string to the specified variable. When ACCEPT is executed, it first performs a carriage return/linefeed, displays the prompt, and then begins taking characters from the keyboard at the first character position following the prompt. You may input up to 255 characters. When input reaches the edge of the screen, as defined by MAXCOL(), the cursor moves to the next line.

ACCEPT supports only two editing keys: Backspace and Return. Esc is not supported. Backspace deletes the last character typed. Return confirms entry and is the only key that can terminate an ACCEPT. If Return is the only key pressed, ACCEPT assigns a null value (“”) to <idVar>.

Examples

      .  This example uses ACCEPT to get keyboard input from the user:
      LOCAL cVar
      ACCEPT "Enter a value: " TO cVar
      IF cVar == ""
         ? "User pressed Return"
      ELSE
         ? "User input:", cVar
      ENDIF

Seealso

@…GET, @…SAY, INKEY(), INPUT*, KEYBOARD, WAIT*

KEYBOARD

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

hb_keyPut()

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

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

SP_RAT_EVENT

RAT_EVENT()

  Short:
  ------
  RAT_EVENT() Event handler - inkey() with mouse awareness

  Returns:
  --------
  <nEvent> => Event value - either inkey() value or
  mouse value

  Syntax:
  -------
  RAT_EVENT([nTimeout],[lClearkb])

  Description:
  ------------
  Event handler - inkey() with mouse awareness

  <nTimeout>   is the   # seconds to wait before
  timeout. Zero (0) means indefinately . If you don't pass
  anything, default is 0. Slight difference from inkey() there.

  Returns values are:

     If keystroke                                   inkey() value
     If left mouse button has been depressed        K_MOUSELEFT
     If right mouse button has been depressed       500
     If timeout                                      0

  [lClearkb]   optional clear keyboard True (default)
  or False. If a keystroke is gotten, and this is True, clear the
  keyboard with:
                     while inkey()#0
                     end

  Examples:
  ---------
   e := 0

   while  e#27
      e := rat_event(30)
      do case
      case e == 0
        ? "Timed out after 30 seconds"
      case e < 400
        ? "Key press with inkey() value of :",e
      case e == 400
        ? "Left mouse button pressed at :"
        ?? "row-> ",rat_eqmrow(),  "col-> ",rat_eqmcol()
      case e == 500
        ? "Right mouse button pressed at :"
        ?? "row-> ",rat_eqmrow(),  "col-> ",rat_eqmcol()
      endcase
   end

  Source:
  -------
  S_MOOSE.PRG

See Also : INKEY(), RAT_ELBHD(), RAT_EQMCOL(), RAT_EQMROW(), RAT_ERBHD(), 
           RAT_ISMOUSE(), RAT_LASTEV(), RAT_MENU2(), RAT_READ()

SP_CTRLW

CTRLW()

  Short:
  ------
  CTRLW() Sends chr(23) (Control-W) to the keyboard

  Returns:
  --------
  Nothing

  Syntax:
  -------
  SET KEY XXX to CTRLW

  Description:
  ------------
  Allows remapping a key to Ctrl-W - a common Clipper
  EXIT key. CTRL-W is not a really intuitive key, but is often
  required by Clipper. I'll often set F10 to act as Ctrl-W.

  Examples:
  ---------
   EXTERNAL CTRLW

   SET KEY 27 to CTRLW  // remaps ESCAPE to CTRL-W
   also
   SETKEY(K_F10,{||ctrlw()})

  Notes:
  -------
  Declare as EXTERNAL i.e. EXTERNAL CTRLW

  Source:
  -------
  S_CTRLW.PRG

 

C5DG-9 Terminal Drivers

Clipper 5.x – Drivers Guide

Chapter 9

Alternate Terminal Drivers

Clipper supports a driver architecture that allows Clipper- compiled applications to use alternate terminal drivers. This architecture provides support for nonstandard video hardware and ANSI output devices, allowing your applications to run in a wider variety of environments.

The following terminal drivers are supplied as part of the Clipper Development System and are discussed in this chapter:

. The ANSITERM driver provides ANSI terminal support for systems that require it

. The NOVTERM driver causes Clipper applications to execute faster when run on some nondedicated network server software

. The PCBIOS driver provides direct BIOS calls rather than direct screen writes for systems requiring this form of I/O

In This Chapter

This chapter discusses how Alternate Terminal Drivers fit into the overall Clipper architecture as well as how to install and use each of the supplied terminal drivers. The following major topics are discussed:

. The Alternate Terminal Driver Architecture

. The ANSITERM Alternate Terminal Driver

. The NOVTERM Alternate Terminal Driver

. The PCBIOS Alternate Terminal Driver

The Alternate Terminal Driver Architecture

In Clipper, communication with I/O devices is controlled by a multilayered terminal system. At the lowest level is the terminal driver which controls screen and keyboard activity. It consists of a screen and keyboard driver that communicates directly with the I/O device (operating system or hardware). It is the device specific part of the Clipper terminal system.

There is, then, a higher level system that communicates with terminal drivers. This system is known as the General Terminal (GT) system and provides general services that create Clipper screen and keyboard commands and functions. The following figure demonstrates:

                   +—————————————–+

                   | CA-Clipper screen and keyboard commands |
                   |              and functions              |
                   |-----------------------------------------|
                   |        General Terminal (GT.OBJ)        |
                   ------------------------------------------|
                   |             Terminal Driver             |
                   |-----------------------------------------|
                   |          Screen   |   Keyboard          |
                   +-----------------------------------------+

The default terminal driver, designed for IBM PC and 100% compatibles, is supplied as a library file (TERMINAL.LIB) installed into your \CLIPPER5\LIB directory. This driver links into each program automatically if you specify no alternative terminal driver provided that you do not use the /R option when you compile. An alternate terminal driver is supplied as a separate library (.LIB) file that links into an application program in place of the default terminal driver if you specify it on the link line.

All alternate terminal drivers work through the General Terminal layer as supplied in the file GT.OBJ. The Clipper installation program installs this file in the \CLIPPER5\OBJ subdirectory on the drive that you specify, so you need not install the driver manually.

The ANSITERM Alternate Terminal Driver

The ANSITERM terminal driver supports the ANSI screen mode for all screen display from Clipper programs.

This screen mode is installed by specifying ANSI.SYS in the user’s CONFIG.SYS. ANSI.SYS replaces the default DOS CON device driver for video display and keyboard input. Once installed it supports ANSI escape sequences to erase the screen, set the screen mode, and control the cursor in a hardware-independent way. Most modern DOS programs, however, do not use it and write either directly to the video hardware or use BIOS routines for enhanced screen performance.

Use the ANSI screen mode for Clipper programs that run on hardware that does not support either writing to video hardware or BIOS calls for screen display. This is the case when using alternative display hardware to support the blind.

Note: The ANSITERM terminal driver fully supports all screen and keyboard functionality of the default terminal driver. This includes the ability to save and restore screens and support for all keys on the standard 101-key keyboard.

Installing ANSITERM Terminal Files

The ANSITERM terminal driver is supplied as the file ANSITERM.LIB. The Clipper installation program installs this file in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install it manually.

Linking the ANSITERM Terminal Driver

To link the ANSITERM alternate terminal driver into an application program, you must specify both GT.OBJ and ANSITERM.LIB to the linker along with your application object (.OBJ) modules.

1. To link with .RTLink using positional syntax:

C>RTLINK <appObjectList> GT,,, ANSITERM

2. To link with .RTLink using freeformat syntax:

C>RTLINK FI <appObjectList>, GT LIB ANSITERM

3. To link with .RTLink using ANSITERM.PLL and freeformat syntax:

C>RTLINK FI <appObjectList> /PLL:ANSITERM

Note: These link commands assume you have set the LIB, OBJ, and PLL environment variables to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Important! You cannot link the ANSITERM driver with BASE52.PLL. An application linked with both ANSITERM.LIB and BASE52.PLL may cause the computer to freeze upon execution.

The Runtime Environment

Using ANSITERM.LIB requires that ANSI.SYS be installed on the user’s computer. To accomplish this, include the following statement in the user’s CONFIG.SYS:

DEVICE=ANSI.SYS

Performance Concerns

Because the ANSITERM terminal driver uses buffered screen writes for all screen painting, some operations, especially those that scroll the screen, are slow. These include:

1. All box drawing commands and functions

2. All console commands and functions when scrolling

3. All clear screen commands and functions

4. All restore screen commands and functions

5. Standard out functions (OUTSTD() and OUTERR()) whether the screen is scrolling or not

Note: Overall performance of Clipper programs is slower since the ANSITERM terminal driver must spend more time polling for user events than the standard Clipper terminal driver.

Screen Output from C and Assembly Language

The ANSITERM terminal driver overwrites all output from C and Assembly Language when it refreshes the screen from the screen buffer. As a consequence, you should perform all screen output from Clipper.

The ANSITERM terminal driver also virtualizes the cursor. This means that BIOS functions that report the location of the hardware cursor will not always return the correct value. To obtain the cursor position, use Clipper’s ROW() and COL() functions instead.

Other Incompatibilities

1. ISCOLOR() always returns false (.F.).

2. When you load DBU, the default color mode is monochrome unless you specify DBU with the /C command line option.

3. The first time you invoke the Debugger, the default color mode is also monochrome unless you set the Options:Mono display off.

4. When an application linked with the ANSITERM terminal driver terminates, the last color set in the application becomes the DOS color. This happens since colors set with ANSITERM are global to DOS and Clipper cannot query DOS for the current screen colors as the application loads.

5. Nondisplaying ASCII characters are presented as a space by the ANSITERM terminal driver. These include BELL (CHR(7)), BS (CHR(8)), TAB (CHR(9)), LF (CHR(10)), CR (CHR(13)), and ESC (CHR(27)).

The NOVTERM Alternate Terminal Driver

The NOVTERM terminal driver is a special-purpose driver that circumvents an incompatibility between some nondedicated network server software and Clipper. This incompatibility causes printers connected to the server to slow to an unusable rate.

Clipper applications and nondedicated servers compete for resources. Clipper applications make use of the time between keystrokes to perform various system tasks. This greatly improves the application’s overall performance by limiting its idle time. Certain nondedicated servers only attempt to print within an application’s idle time. Since a Clipper application is seldom idle, this greatly slows printing.

Important! The NOVTERM terminal driver corrects the incompatibility by preventing the Clipper application from using idle time. Because this can severely hamper performance, you should only use the NOVTERM terminal driver when necessary, and then you should link it only into those applications that are physically running the nondedicated server.

Note: The NOVTERM terminal driver fully supports all screen and keyboard functionality of the default terminal driver. This includes the ability to save and restore screens and support for all keys on the standard 101-key keyboard.

Installing NOVTERM Terminal Files

The NOVTERM terminal driver is supplied as the file NOVTERM.LIB. The Clipper installation program installs the driver file in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install it manually.

Linking the NOVTERM Terminal Driver

To link the NOVTERM alternate terminal driver into an application, you must specify both GT.OBJ and NOVTERM.LIB to the linker with your application object (.OBJ) modules.

1. To link with .RTLink using positional syntax:

C>RTLINK <appObjectList> GT,,, NOVTERM

2. To link with .RTLink using freeformat syntax:

C>RTLINK FI <appObjectList>, GT LIB NOVTERM

3. To link with .RTLink using NOVTERM.PLL and freeformat syntax:

C>RTLINK FI <appObjectList> /PLL:NOVTERM

Note: These link commands assume you have set the LIB, OBJ, and PLL environment variables to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Important! You cannot link the NOVTERM driver with BASE52.PLL. An application linked with both NOVTERM.LIB and BASE52.PLL may cause the computer to freeze upon execution.

Performance Concerns

Overall performance of Clipper programs is slower since the NOVTERM terminal driver must spend more time polling for user events than the standard Clipper terminal driver and since the program will not use its idle time for other tasks.

Screen Output from C and Assembly Language

The NOVTERM terminal driver overwrites all output from C and Assembly Language when it refreshes the screen from the screen buffer. Therefore, you should perform all screen output from Clipper.

The NOVTERM terminal driver also virtualizes the cursor. This means that BIOS functions that report the location of the hardware cursor will not always return the correct value. To obtain the cursor position, use Clipper’s ROW() and COL() functions.

The PCBIOS Alternate Terminal Driver

The PCBIOS terminal driver uses BIOS calls instead of direct screen writes. It is designedd for applications that trap BIOS calls to redirect output over telecommunication lines or to convert output to a form compatible with two-byte character sets.

Note: The PCBIOS terminal driver fully supports all screen and keyboard functionality of the default terminal driver. This includes the ability to save and restore screens and support for all keys on the standard 101-key keyboard.

Installing PCBIOS Terminal Files

The PCBIOS terminal driver is supplied as the file, PCBIOS.LIB. The Clipper installation program installs the driver file in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install it manually.

Linking the PCBIOS Terminal Driver

To link the PCBIOS alternate terminal driver into an application program, you must specify both GT.OBJ and PCBIOS.LIB to the linker in addition to your application object (.OBJ) modules.

1. To link with .RTLink using positional syntax:

   C>RTLINK <appObjectList> GT,,, PCBIOS;

2. To link with .RTLink using freeformat syntax:

   C>RTLINK FI <appObjectList>, GT LIB PCBIOS

3. To link with .RTLink using PCBIOS.PLL and freeformat syntax:

   C>RTLINK FI <appObjectList> /PLL:PCBIOS

Note: These link commands assume you have set the LIB, OBJ, and PLL environment variables to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Important! You cannot link the PCBIOS driver with BASE52.PLL. An application linked with both PCBIOS.LIB and BASE52.PLL may cause the user’s computer to freeze when the user executes it.

Performance Concerns

Because the PCBIOS terminal driver uses buffered screen writes for all screen painting, some operations, especially those that scroll the screen, are slow. These include:

1. All box drawing commands and functions

2. All console commands and functions when scrolling

3. All clear screen commands and functions

4. All restore screen commands and functions

5. Standard out functions (OUTSTD() and OUTERR()) whether the screen is scrolling or not

Screen Output from C and Assembly Language

The PCBIOS terminal driver also overwrites all output from C and Assembly Language when it refreshes the screen from the screen buffer. Therefore, you should perform all screen output from Clipper.

The PCBIOS terminal driver also virtualizes the cursor. This means that BIOS functions that report the location of the hardware cursor do not always return the correct value. To obtain the cursor position, use Clipper’s ROW() and COL() functions.

Summary

This chapter has introduced you to the Alternate Terminal Driver concept, giving you specific information on the architecture used to implement them in Clipper. Each of the alternate terminal drivers supplied with Clipper was discussed, including how to link and use it into your application and the implications of doing so.