/*
 * $Id$
 */
/*
 * Copyright 2000 Alejandro de Garate <alex_degarate@hotmail.com>
 *    Documentation for: SETMODE()
 *
 * See COPYING for licensing terms.
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      SETMODE()
 *  $CATEGORY$
 *       API
 *  $SUBCATEGORY$
 *      Environment
 *  $ONELINER$
 *      Change the video mode to a specified number of rows and columns
 *  $SYNTAX$
 *      SETMODE( <nRows>, <nCols> ) --> lSuccess
 *  $ARGUMENTS$
 *      <nRows> is the number of rows for the video mode to set.
 *
 *      <nCols> is the number of columns for the video mode to set.
 *  $RETURNS$
 *      SETMODE() returns true if the video mode change was successful;
 *      otherwise, it returns false.
 *  $DESCRIPTION$
 *      SETMODE() is a function that change the video mode depend on the
 *      video card and monitor combination, to match the number of rows and
 *      columns specified.
 *      Note that there are only a real few combination or rows/cols pairs
 *      that produce the video mode change.
 *      The followings are availables for DOS:
 *
 *      <table>
 *         12 rows x 40 columns   12 rows x 80 columns
 *         25 rows x 40 columns   25 rows x 80 columns
 *         28 rows x 40 columns   28 rows x 80 columns
 *         50 rows x 40 columns   43 rows x 80 columns
 *                                50 rows x 80 columns
 *      </table>
 *
 *      The follow modes are available to Windows
 *
 *      <table>
 *         25 rows x 40 columns   25 rows x 80 columns
 *         50 rows x 40 columns   43 rows x 80 columns
 *         50 rows x 80 columns
 *      </table>
 *
 *      Some modes only are availables for color and/or VGA monitors.
 *      Any change produced on the screen size is updated in the values
 *      returned by MAXROW() and MAXCOL().
 *  $EXAMPLES$
 *      // The first example change to a 12 lines of display mode:
 *      IF SETMODE( 12, 40)
 *         ? "Hey man are you blind ?"
 *      ELSE
 *         ? "Mom bring me my glasses!"
 *      ENDIF
 *
 *      // Next example change to a 50 lines mode:
 *      IF SETMODE( 50, 80)
 *         ? "This wonderful mode was successfully set"
 *      ELSE
 *         ? "Wait. this monitor are not made in rubber !"
 *      ENDIF
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Some of these modes are not availables in CA-Cl*pper
 *  $PLATFORMS$
 *      DOS,Win
 *  $FILES$
 *      Source is gtdos.c,gtwin.c
 *  $SEEALSO$
 *      MAXCOL(),MAXROW()
 *  $END$
 */