DispOutAt

DispOutAt

Displays a value on the screen

Syntax

      DispOutAt( <nRow>      , ;
                    <nCol>      , ;
                    <expression>, ;
                    [<cColor>]  , ;
                    [<lSetPos>]   ) --> NIL

Arguments

<nRow> : Row number of screen to <expression> write

<nCol> : Column number of screen to <expression> write

<expression> : Any expression to write to the screen.

<cColor> : Color string for display

<lSetPos> : Specifies whether or not to update the screen cursor positions ( Row(), Col() after writing

Return

DispOutAt() returns always NIL.

Description

This function write the value of <expression> at the specified cursor position on the screen, using the color <cColor>, if specified.

Note

DispOutAt() don’t obey SET DEVICE setting and write always to the screen

Example

      DispOutAt( 0, 0, "Here upper left corner of screen", "W+/R" )

         is equvalent to :

         @ 0,0  SAY ""Here upper left corner of screen" COLOR  "W+/G"

Seealso

@ … SAY, Col(), DevOut(), DispBegin(), DispCount(), DispEnd(), DispOutAt(), OutStd(), QOut() | QQOut(), Row(), SetPos()

DispOut

DispOut

Displays a value on the screen

Syntax

      DispOut( <expression>, [<cColor>] ) --> NIL

Arguments

<expression> : Any expression to write to the screen.

<cColor> : Color string for display

Return

DispOut() returns always NIL.

Description

This function write the value of <expression> at the current cursor position on the screen, using the color <cColor>, if specified.

Note

DispOut() don’t obey SET DEVICE setting and write always to the screen

Example

      SetPos( 0, 0 )
         DispOut( "Here upper left corner of screen", "W+/R" )

         is equvalent to :

          @ 0,0  SAY ""Here upper left corner of screen" COLOR  "W+/G"

Seealso

@ … SAY, Col(), DevOut(), DispBegin(), DispCount(), DispEnd(), DispOutAt(), OutStd(), QOut() | QQOut(), Row(), SetPos()

Alert()

ALERT()

Display a dialog box with a message

Syntax

      ALERT( <xMessage>, [<aOptions>], [<cColorNorm>], [<nDelay>] ) --> nChoice or NIL

Arguments

<xMessage> Message to display in the dialog box. <xMessage> can be of any Harbour type. If <xMessage> is an array of Character strings, each element would be displayed in a new line. If <xMessage> is a Character string, you could split the message to several lines by placing a semicolon (;) in the desired places.

<aOptions> Array with available response. Each element should be Character string. If omitted, default is { “Ok” }.

<cColorNorm> Color string to paint the dialog box with. If omitted, default color is “W+/R”.

<nDelay> Number of seconds to wait to user response before abort. Default value is 0, that wait forever.

Returns

ALERT() return Numeric value representing option number chosen.

If ESC was pressed, return value is zero.

The return value is NIL if ALERT() is called with no parameters, or if <xMessage> type is not Character and HB_CLP_STRICT option was used. If <nDelay> seconds had passed without user response, the return value is 1.

Description

ALERT() display simple dialog box on screen and let the user select one option. The user can move the highlight bar using arrow keys or TAB key. To select an option the user can press ENTER, SPACE or the first letter of the option.

If the program is executed with the //NOALERT command line switch, nothing is displayed and it simply returns NIL. This switch could be overridden with __NONOALERT().

If the GT system is linked in, ALERT() display the message using the full screen I/O system, if not, the information is printed to the standard output using OUTSTD().

Examples

      LOCAL cMessage, aOptions, nChoice

      // harmless message
      cMessage := "Major Database Corruption Detected!;" +  ;
                  "(deadline in few hours);;"             +  ;
                  "where DO you want to go today?"

      // define response option
      aOptions := { "Ok", "www.jobs.com", "Oops" }

      // show message and let end user select panic level
      nChoice := ALERT( cMessage, aOptions )
      DO CASE
      CASE nChoice == 0
         // do nothing, blame it on some one else
      CASE nChoice == 1
         ? "Please call home and tell them you're gonn'a be late"
      CASE nChoice == 2
         // make sure your resume is up to date
      CASE nChoice == 3
         ? "Oops mode is not working in this version"
      ENDCASE

Compliance

This function is sensitive to HB_CLP_STRICT settings during the compilation of src/rtl/alert.prg

defined : <xMessage> accept Character values only and return NIL if other types are passed.

undefined : <xMessage> could be any type, and internally converted to Character string. If type is Array, multi-line message is displayed.

defined : Only the first four valid <aOptions> are taken.

undefined : <aOptions> could contain as many as needed options.

If HB_COMPAT_C53 was define during compilation of src/rtl/alert.prg the Left-Mouse button could be used to select an option.

The interpretation of the //NOALERT command line switch is done only if HB_CLP_UNDOC was define during compilation of src/rtl/alert.prg

<cColorNorm> is a Harbour extension, or at least un-documented in Clipper 5.2 NG.

<nDelay> is a Harbour extension.

Files

Library is rtl

Seealso

@…PROMPT, MENU TO, OUTSTD(), __NONOALERT()

HB_EOL()

HB_EOL()

Returns the newline character(s) to use with the current OS

Syntax

      hb_eol() --> cString

Returns

<cString> A character string containing the character or characters required to move the screen cursor or print head to the start of a new line.

Description

Returns a character string containing the character or characters required to move the screen cursor or print head to the start of a new line for the operating system that the program is running on (or thinks it is running on, if an OS emulator is being used).

Under HB_OS_UNIX operating system the return value is the Line-Feed character (0x0a, CHR(10)); with other operating systems (like DOS) the return value is the Carriage-Return plus Line-Feed characters (0x0d 0x0a, CHR(13)+CHR(10)).

Examples

      // Get the newline character(s) for the current OS.
      // Get the newline character(s) for the current OS.
      STATIC s_cNewLine
      ...
      s_cNewLine := hb_eol()
      ...
      OutStd( "Hello World!" + s_cNewLine )

Tests

      ? ValType( hb_eol() ) == "C"
      ? Len( hb_eol() ) == 1

Compliance

Harbour

Platforms

All

Files

Library is rtl

Seealso

OS(), OUTSTD(), OUTERR()

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.