/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://www.harbour-project.org
 *
 * Copyright 1999 Victor Szakats <info@szelvesz.hu>
 *    Documentation for: HB_COLORINDEX()
 *
 * Copyright 1999 Jose Lalin <dezac@corevia.com>
 *    Documentation for: __WAIT(), __INPUT()
 *
 * Copyright 1999 Chen Kedem <niki@actcom.co.il>
 *    Documentation for: ALERT(), __NONOALERT(), __XSaveScreen(), SAVE SCREEN
 *                       __XRestScreen(), RESTORE SCREEN, __TextSave(),
 *                       __TextRestore()
 *
 * Copyright 1999 David G. Holm <dholm@jsd-llc.com>
 *    Documentation for: DEVOUTPICT()
 *
 * See doc/license.txt for licensing terms.
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *      __XSaveScreen()
 *  $CATEGORY$
 *      Data input and output
 *  $ONELINER$
 *      Save whole screen image and coordinate to an internal buffer
 *  $SYNTAX$
 *      __XSaveScreen() --> NIL
 *  $ARGUMENTS$
 *      none.
 *  $RETURNS$
 *      __XSaveScreen() always return NIL.
 *  $DESCRIPTION$
 *      __XSaveScreen() save the image of the whole screen into an internal
 *      buffer, it also save current cursor position. The information could
 *      later be restored by __XRestScreen(). Each call to __XSaveScreen()
 *      overwrite the internal buffer.
 *
 *      SAVE SCREEN command is preprocessed into __XSaveScreen() function
 *      during compile time. Note that SAVE SCREEN TO is preprocessed into
 *      SAVESCREEN() function.
 *
 *      __XSaveScreen() is a compatibility function, it is superseded by
 *      SAVESCREEN() which allow you to save part or all the screen into a
 *      variable.
 *  $EXAMPLES$
 *      // save the screen, display list of files than restore the screen
 *      SAVE SCREEN
 *      DIR *.*
 *      WAIT
 *      RESTORE SCREEN
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      __XSaveScreen() works exactly like CA-Clipper's __XSaveScreen()
 *  $PLATFORMS$
 *      __XSaveScreen() is part of the GT API, and supported only by some
 *      platforms.
 *  $FILES$
 *      Library is rtl.lib
 *  $SEEALSO$
 *       RESTORE SCREEN,RESTSCREEN(),SAVESCREEN()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     SAVE SCREEN
 *  $CATEGORY$
 *      Command
 *  $ONELINER$
 *      Save whole screen image and coordinate to an internal buffer
 *  $SYNTAX$
 *      SAVE SCREEN
 *  $ARGUMENTS$
 *      none.
 *  $RETURNS$
 *      SAVE SCREEN always return NIL.
 *  $DESCRIPTION$
 *      SAVE SCREEN save the image of the whole screen into an internal
 *      buffer, it also save current cursor position. The information could
 *      later be restored by REST SCREEN. Each call to SAVE SCREEN
 *      overwrite the internal buffer.
 *
 *      SAVE SCREEN command is preprocessed into __XSaveScreen() function
 *      during compile time. Note that SAVE SCREEN TO is preprocessed into
 *      SAVESCREEN() function.
 *  $EXAMPLES$
 *      // save the screen, display list of files than restore the screen
 *      SAVE SCREEN
 *      DIR *.*
 *      WAIT
 *      RESTORE SCREEN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      __XSaveScreen() works exactly like CA-Clipper's __XSaveScreen()
 *  $PLATFORMS$
 *      __XSaveScreen() is part of the GT API, and supported only by some
 *      platforms.
 *  $SEEALSO$
 *      RESTORE SCREEN,__XRESTSCREEN(),__XSAVESCREEN()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      __XRestScreen()
 *  $CATEGORY$
 *      Data input and output
 *  $ONELINER$
 *      Restore screen image and coordinate from an internal buffer
 *  $SYNTAX$
 *      __XRestScreen() --> NIL
 *  $ARGUMENTS$
 *      none.
 *  $RETURNS$
 *      __XRestScreen() always return NIL.
 *  $DESCRIPTION$
 *      __XRestScreen() restore saved image of the whole screen from an
 *      internal buffer that was saved by __XSaveScreen(), it also restore
 *      cursor position. After a call to __XRestScreen() the internal buffer
 *      is cleared.
 *
 *      RESTORE SCREEN command is preprocessed into __XRestScreen() function
 *      during compile time. Note that RESTORE SCREEN FROM is preprocessed
 *      into RESTSCREEN() function.
 *
 *      __XRestScreen() is a compatibility function, it is superseded by
 *      RESTSCREEN() which allow you to restore the screen from a variable.
 *  $EXAMPLES$
 *      // save the screen, display list of files than restore the screen
 *      SAVE SCREEN
 *      DIR *.*
 *      WAIT
 *      RESTORE SCREEN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      __XRestScreen() works exactly like CA-Clipper's __XRestScreen()
 *  $PLATFORMS$
 *      __XRestScreen() is part of the GT API, and supported only by some
 *      platforms.
 *  $FILES$
 *      Library is rtl.lib
 *  $SEEALSO$
 *      __XRESTSCREEN(),SAVE SCREEN,__XSAVESCREEN()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      RESTORE SCREEN
 *  $CATEGORY$
 *      Command
 *  $ONELINER$
 *      Restore screen image and coordinate from an internal buffer
 *  $SYNTAX$
 *      RESTORE SCREEN
 *  $ARGUMENTS$
 *      none.
 *  $RETURNS$
 *      REST SCREEN always return NIL.
 *  $DESCRIPTION$
 *      Rest Screen restore saved image of the whole screen from an
 *      internal buffer that was saved by Save Screen, it also restore
 *      cursor position. After a call to Rest Screen the internal buffer
 *      is cleared.
 *
 *      RESTORE SCREEN command is preprocessed into __XRestScreen() function
 *      during compile time. Note that RESTORE SCREEN FROM is preprocessed
 *      into RESTSCREEN() function.
 *  $EXAMPLES$
 *      // save the screen, display list of files than restore the screen
 *      SAVE SCREEN
 *      DIR *.*
 *      WAIT
 *      RESTORE SCREEN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Rest Screen() works exactly like CA-Clipper's Rest Screen
 *  $PLATFORMS$
 *      Rest Screen is part of the GT API, and supported only by some
 *      platforms.
 *  $SEEALSO$
 *      __XRESTSCREEN(),SAVE SCREEN,__XSAVESCREEN()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ALERT()
 *  $CATEGORY$
 *      Data input and output
 *  $ONELINER$
 *      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_C52_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
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is sensitive to HB_C52_STRICT settings during the
 *      compilation of source/rtl/alert.prg
 *
 *      <b>defined</b>: <xMessage> accept Character values only and return
 *      NIL if other types are passed.
 *
 *      <b>undefined</b>: <xMessage> could be any type, and internally
 *      converted to Character string. If type is Array, multi-line message
 *      is displayed.
 *
 *      <b>defined</b>: Only the first four valid <aOptions> are taken.
 *
 *      <b>undefined</b>: <aOptions> could contain as many as needed options.
 *
 *      If HB_COMPAT_C53 was define during compilation of
 *      source/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_C52_UNDOC was define during compilation of source/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.lib
 *  $SEEALSO$
 *       @...PROMPT,MENU TO,STDOUT(),__NONOALERT()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      __NONOALERT()
 *  $CATEGORY$
 *      Data input and output
 *  $ONELINER$
 *      Override //NOALERT command line switch
 *  $SYNTAX$
 *      __NONOALERT() --> NIL
 *  $ARGUMENTS$
 *      This function takes no arguments.
 *  $RETURNS$
 *      __NONOALERT() always return NIL.
 *  $DESCRIPTION$
 *      The //NOALERT command line switch cause Clipper to ignore calls to
 *      the ALERT() function, this function override this behavior
 *      and always display ALERT() dialog box.
 *  $EXAMPLES$
 *      // make sure alert are been displayed
 *      __NONOALERT()
 *  $STATUS$
 *      R
 *  $FILES$
 *      Library is rtl.lib
 *  $COMPLIANCE$
 *      __NONOALERT() is an undocumented CA-Clipper function and exist only
 *      if HB_C52_UNDOC was defined during the compilation of
 *      source/rtl/alert.prg
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      HB_OSNEWLINE()
 *  $CATEGORY$
 *      Operating System Specific
 *  $ONELINER$
 *      Returns the newline character(s) to use with the current OS
 *  $SYNTAX$
 *      HB_OSNewLine() --> 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. The string will hold either CHR(10) or CHR(13) + CHR(10).
 *  $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).
 *  $EXAMPLES$
 *      // Get the newline character(s) for the current OS using defaults.
 *      STATIC s_cNewLine
 *      ...
 *      s_cNewLine := HB_OSNewLine()
 *      ...
 *      OutStd( "Hello World!" + s_cNewLine )
 *      ...
 *  $TESTS$
 *      <fixed>
 *      valtype( HB_OSNewLine() ) == "C"
 *      LEN( HB_OSNewLine() ) == 1
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This is an add-on Operating System Tool function.
 *  $PLATFORMS$
 *      Under OS_UNIX_COMPATIBLE operating system the return value is the
 *      Line-Feed (0x0a) character CHR(10), with other operating systems
 *      (like DOS) the return value is the Carriage-Return plus Line-Feed
 *      (0x0d 0x0a) characters CHR(13)+CHR(10).
 *  $FILES$
 *      Library is rtl.lib
 *  $SEEALSO$
 *      OS(),OUTSTD(),OUTERR()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_ColorIndex()
 *  $CATEGORY$
 *      GT
 *  $ONELINER$
 *      Extract one color from a full Clipper colorspec string.
 *  $SYNTAX$
 *      hb_ColorIndex( <cColorSpec>, <nIndex> )
 *  $ARGUMENTS$
 *      <cColorSpec> is a Clipper color list
 *
 *      <nIndex> is the position of the color item to be extracted, the
 *      first position is the zero.
 *  $RETURNS$
 *      The selected color string, or if anything goes wrong, an empty
 *      string.
 *  $DESCRIPTION$
 *      Clipper has a color spec string, which has more than one
 *      color in it, separated with commas. This function is able to extract
 *      a given item from this list. You may use the manifest constants
 *      defined in color.ch to extract common Clipper colors.
 *  $EXAMPLES$
 *      ? hb_ColorIndex( "W/N, N/W", CLR_ENHANCED ) // "N/W"
 *  $TESTS$
 *      see the regression test suit for comprehensive tests.
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Was not part of CA-Clipper.
 *  $FILES$
 *      Library is rtl.lib
 *  $SEEALSO$
 *      ColorSelect()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      DEVOUTPICT()
 *  $CATEGORY$
 *      Terminal
 *  $ONELINER$
 *      Displays a value to a device using a picture template
 *  $SYNTAX$
 *      DEVOUTPICT(<xExp>,<cPicture>[,<cColorString>]) --> NIL
 *  $ARGUMENTS$
 *      <xExp> is any valid expression.
 *
 *      <cPicture> is any picture transformation that TRANSFORM() can use.
 *
 *      <cColorString> is an optional string that specifies a screen color to
 *      use in place of the default color when the output goes to the screen.
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      Outputs any expression using a picture transformation instead of
 *      using the default transformation for the type of expression.
 *  $EXAMPLES$
 *      // Output a negative dollar amount using debit notation.
 *      DEVOUTPICT( -1.25, "@D$ 99,999.99 )
 *  $TESTS$
 *      <fixed>
 *      @ 3,1 SAY -1.25 PICTURE "@D$ 99,999.99"
 *      will display "$(     1.25)" starting on row four, column two of the
 *      current device (without the double quotation marks, of course).
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      DEVOUTPICT() is mostly CA-Clipper compliant. Any differences are due
 *      to enhancements in the Harbour TRANSFORM() over CA-Clipper.
 *  $FILES$
 *      Library is rtl.lib
 *  $SEEALSO$
 *      DEVOUT(),TRANSFORM()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      __INPUT()
 *  $CATEGORY$
 *      Data input and output
 *  $ONELINER$
 *      Stops application
 *  $SYNTAX$
 *      __INPUT( <cMessage> ) --> <cString>
 *  $ARGUMENTS$
 *      <cMessage> is any valid expression.
 *  $RETURNS$
 *      Macroed <cString>
 *  $DESCRIPTION$
 *      This function waits for a console input and returns macroed
 *      expression entered.
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      __INPUT() is fully CA-Clipper compliant.
 *  $FILES$
 *      Library is rtl.lib
 *  $SEEALSO$
 *      __WAIT(),__ACCEPT()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     __TextSave()
 *  $CATEGORY$
 *     Internal
 *  $ONELINER$
 *     Redirect console output to printer or file and save old settings
 *  $SYNTAX$
 *      __TextSave( <cFile> ) --> NIL
 *  $ARGUMENTS$
 *      <cFile> is either "PRINTER" (note the uppercase) in which console
 *      output is SET to PRINTER, or a name of a text file with a default
 *      ".txt" extension, that is used to redirect console output.
 *  $RETURNS$
 *      __TextSave() always return NIL.
 *  $DESCRIPTION$
 *      __TextSave() is used in the preprocessing of the TEXT TO command to
 *      redirect the console output while saving old settings that can be
 *      restored later by __TextRestore().
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      __TextSave() is an Undocumented CA-Clipper function
 *  $PLATFORMS$
 *      ALL
 *  $FILES$
 *      Library is rtl.lib
 *  $SEEALSO$
 *      SET(),SET ALTERNATE,SET PRINTER,TEXT,__TextRestore()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      __TextRestore()
 *  $CATEGORY$
 *      Internal
 *  $ONELINER$
 *      Restore console output settings as saved by __TextSave()
 *  $SYNTAX$
 *      __TextRestore() --> NIL
 *  $ARGUMENTS$
 *      none.
 *  $RETURNS$
 *      __TextRestore() always return NIL.
 *  $DESCRIPTION$
 *      __TextRestore() is used in the preprocessing of the TEXT TO command
 *      to restore console output settings that were previously saved by
 *      __TextSave().
 *  $STATUS$
 *       R
 *  $COMPLIANCE$
 *      __TextRestore() is an Undocumented CA-Clipper function
 *  $PLATFORMS$
 *       All
 *  $FILES$
 *      Library is rtl.lib
 *  $SEEALSO$
 *      SET(),SET ALTERNATE,SET PRINTER,TEXT,__TextSave()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      __WAIT()
 *  $CATEGORY$
 *      Events
 *  $ONELINER$
 *      Stops the application until a key is pressed.
 *  $SYNTAX$
 *      __WAIT( <cMessage> ) --> <cKey>
 *  $ARGUMENTS$
 *      <cMessage> is a string.
 *  $RETURNS$
 *      Pressed key.
 *  $DESCRIPTION$
 *      This function stops the application until a key is pressed. The key
 *      must be in the range 32..255. Control keys are not processed.
 *  $EXAMPLES$
 *      // Wait for a key stroke
 *      __Wait( "Press a key to continue" )
 *  $TESTS$
 *      <fixed>
 *      do while cKey != "Q"
 *        cKey := __Wait( "Press 'Q' to continue" )
 *      end do
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      __WAIT() is fully CA-Clipper compliant.
 *  $FILES$
 *      Library is rtl.lib
 *  $SEEALSO$
 *      __ACCEPT(),__INPUT()
 *  $END$
 */
