home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource3 / 167_01 / c_window.doc < prev    next >
Text File  |  1985-08-21  |  30KB  |  1,124 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                 C_WINDOW
  19.                 --------
  20.  
  21.           Windowing for the IBM PC with the C Language
  22.                   Version 1.00
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.                                  C_WINDOW
  70.    ----------------------------------------------------------------------
  71.  
  72.  
  73.     INTRODUCTION
  74.  
  75.     C_WINDOW is a collection of functions that give windowing capa-
  76.     bility to the C programmer using an IBM PC or true compatible.    
  77.     C_WINDOW is written entirely in MicroSoft (Lattice) C, Version
  78.     2.03. It was compiled using the small model for both code and
  79.     data and is distributed in .OBJ format, ready to be linked to
  80.     your C programs. The source code of C_WINDOW is available for
  81.     $15. See page 11 of this documentation for details.
  82.  
  83.     The core C_WINDOW files are:
  84.     
  85.          C_WINDOW.OBJ    - The compiled windowing code
  86.          C_WINDOW.DOC    - The documentation
  87.          C_WDEF.INC     - Include file for your C code
  88.          C_W-DEMO.EXE    - Windowing demonstration program
  89.  
  90.     To use the C_WINDOW functions in your Lattice C program:
  91.     
  92.      (1) Include the file C_WDEF.INC in your C source file. 
  93.          C_WDEF.INC defines the C_WINDOW functions and associated
  94.          constants and variables. If the C_WDEF.INC file is missing,
  95.          you can extract it from the sample program C_W-DEMO.C listed
  96.          at the end of this documentation.    
  97.  
  98.      (2) Compile your C source file using the small code and data
  99.          model.
  100.  
  101.      (3) Link C_WINDOW.OBJ to your code:
  102.  
  103.         LINK CS + yourprog + C_WINDOW, yourprog.EXE,, MCS.LIB
  104.  
  105.     To allow other C compilers to compile the C_WINDOW source code, 
  106.     standard C syntax is used where-ever possible. There are only
  107.     three non-standard C functions used: INT86(), PEEK() and POKE().
  108.     If your compiler doesn't include these functions, you will have 
  109.     to write your own. Lattice C compatible versions of the three
  110.     above functions, written in assembler, plus a full explanation, 
  111.     are on the source code disk. Also, if you don't have an IBM PC or
  112.     compatible, and you are familiar with reading and writing to the
  113.     video RAM of your computer, you can adapt C_WINDOW for use on
  114.     your PC.
  115.  
  116.     Near the end of this documentation is the C source of a sample
  117.     windowing program. It has been compiled as C_W-DEMO.EXE and is
  118.     part of the C_WINDOW package. If C_W-DEMO.EXE is missing, you can
  119.     extract the source of C_W-DEMO.C from this documentation and
  120.     compile it to see a demonstration of C_WINDOW.    
  121.  
  122.     An array of bytes, called the window buffer, is used to store
  123.     each defined window, plus the section of the screen that each
  124.     window overlays.  The window buffer size has been defined in the
  125.     C_WINDOW code to be 10000 bytes.  This is a compromise value.
  126.     Larger allows more active window definitions, smaller means a
  127.  
  128.  
  129.                                     1
  130.  
  131.  
  132.  
  133.  
  134.  
  135.                                  C_WINDOW
  136.    ----------------------------------------------------------------------
  137.  
  138.  
  139.     smaller program.  When a window is defined, storage is allocated
  140.     in the window buffer.  The standard IBM PC screen, in 80 column 
  141.     alphanumeric mode, uses 4000 bytes (80 x 25 x 2) of video RAM.
  142.     Each character on the screen has a trailing attribute byte that 
  143.     indicates if the character is bright or dark, blinking, etc.
  144.     10000 bytes is enough to create a window the size of the screen 
  145.     (4000 bytes to save old screen, 4000 for window), plus another
  146.     little window. Or several medium sized windows. 
  147.  
  148.     C_WINDOW allows deallocation of window storage so you can have as
  149.     many windows as you like by deallocating and redefining them as 
  150.     needed. The only restriction is that only as many windows as can
  151.     be defined in the window buffer can be visible at any one time. 
  152.  
  153.     The main reason why the window buffer's size is explicitly
  154.     defined in the code, rather than using dynamic memory allocation
  155.     is that if the program can load on a particular computer with x 
  156.     amount of memory, then it will run on that computer. The program
  157.     is self-contained.
  158.  
  159.  
  160.     OVERVIEW OF FUNCTIONS
  161.  
  162.     YOU MUST ALWAYS CALL W_INIT() BEFORE USING ANY OF C_WINDOW's
  163.     FUNCTIONS. Do NOT neglect to do this, as several important data 
  164.     pointers are initialized.
  165.  
  166.     There are two kinds of functions available: those that are
  167.     specific to the C_WINDOW environment, and those that are comple-
  168.     mentary. The functions specific to C_WINDOW are preceded by "W_".  
  169.  
  170.     The four major windowing functions are:
  171.  
  172.         (1) Defining a window with W_DEF().
  173.         (2) Opening a window with W_OPEN().
  174.         (3) Closing the most recently opened window with W_CLOSE().
  175.         (4) Deallocating window(s) and releasing window buffer
  176.             space with W_KILL().
  177.  
  178.     The flag "err_exit" controls the action taken when a windowing 
  179.     error occurs. "err_exit" is declared as EXTERNal CHAR in 
  180.     C_WDEF.INC. If you set "err_exit" to TRUE (default), the program 
  181.     will return to the operating system after an error message window
  182.     is displayed.  The name of the windowing function and what is
  183.     wrong with what you are asking the function to do will be
  184.     indicated in the error message window.    
  185.  
  186.     If you set "err_exit" FALSE, for all C_WINDOW functions that 
  187.     return a status code (1 == OK, 0 == error), be sure to check that
  188.     no error has occurred. If a windowing function returns an error 
  189.     code, do not ignore it.  Terminate the program and check your
  190.     code for the cause of the error. Often the problem is as simple 
  191.     as mixing the X and Y coordinates up, or not specifying enough
  192.     arguments when a function is called.
  193.  
  194.  
  195.                                     2
  196.  
  197.  
  198.  
  199.  
  200.  
  201.                                  C_WINDOW
  202.    ----------------------------------------------------------------------
  203.  
  204.  
  205.  
  206.     A window's width and height is specified when it is defined.  When
  207.     it is opened, it can be located at any location on the screen, as
  208.     long as it doesn't stray outside of the screen's boundaries. If 
  209.     you have specified a border for a window, the writeable area of 
  210.     the window is reduced to fit inside the border. THE UPPER LEFT
  211.     CORNER OF THE WRITEABLE AREA OF A WINDOW IS AT HORIZONTAL (X)
  212.     COORDINATE 0 AND VERTICAL (Y) COORDINATE 0. IF NO WINDOWS ARE
  213.     OPEN, WINDOWING COMMANDS ARE RELATIVE TO THE STANDARD 80 x 25
  214.     SCREEN. 
  215.  
  216.     No more than one version of a defined window can be open at any 
  217.     one time, irregardless of screen placement. This is because each
  218.     window's storage contains information about the section of screen
  219.     it overlaid and opening a second version of the same window would
  220.     overwrite that information.
  221.  
  222.     W_WRITE() is the C_WINDOW screen writing function. It does not
  223.     attempt to interpret and act on any characters, including carriage
  224.     returns and line feeds. The only action taken is to wrap-around on
  225.     the active window if the cursor is at the right side of the window
  226.     and to scroll up if the bottom of the window is reached. Any extra
  227.     text handling will have to be added by you. The advantage is that
  228.     you can write any character to a window with W_WRITE(). 
  229.  
  230.     W_GETSTR() is the C_WINDOW screen string input function. You can
  231.     specify the maximum length of an input string so that no borders
  232.     are over-written. Character editing capabilities are included.    
  233.     The standard C function SSCANF() can be used to perform formatted
  234.     input conversion on the string read by W_GETSTR().
  235.  
  236.     Any standard C input/output functions that involve outputting
  237.     carriage returns or line feeds to the screen MUST be avoided when
  238.     a window is open. The standard C input/output functions know
  239.     nothing about the windowing environment and can easily write
  240.     across a window's border. Functions like PRINTF() can be used
  241.     with care, providing the user (1) first positions the cursor in a
  242.     window with W_GOTOXY() (2) never sends a carriage return or line
  243.     feed to the screen and (3) avoids writing across a window's
  244.     border. 
  245.  
  246.     All function calls must include all parameters, even if they are
  247.     only dummy place-holders. For example, if a window has been
  248.     defined without a border, the window opening function W_OPEN()
  249.     must include all 5 parameters, even though the border type
  250.     specification is ignored.
  251.  
  252.     C_WINDOW automatically selects 80 column alphanumeric mode
  253.     whether you have