home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_200 / 259_01 / win.doc < prev    next >
Text File  |  1988-02-25  |  12KB  |  272 lines
  1.  
  2.  
  3.          C-WIN - A Public Domain 'C' Windowing System
  4.          --------------------------------------------
  5.  
  6.                  Introduction
  7.                  ============
  8.  
  9.    This package was developed as a result of my desire to have a windowing
  10.    system written in a portable language.  In the three years I've been
  11.    using the 'C' language I've progressed through six compilers.  Each time
  12.    I've had to make extensive modifications to assembly language
  13.    subroutines to adapt them to the new compiler environment.  In addition,
  14.    I've occasionally used commercial libraries of functions for which I've
  15.    only had executable code.  These libraries, of course, did not work with
  16.    the new compiler and I was faced with a choice of purchasing a new
  17.    version of the library or writing my own functions to replace the
  18.    library routines I was using.  After encountering this agony several
  19.    times I've come up with a simple solution.  If I don't have the source
  20.    code to a function, it does not get linked into any of my programs!
  21.  
  22.    I'm well aware that there are many commercial windowing packages
  23.    available and some are even willing to give you the source code.  These
  24.    packages must be outstanding because they sure cost a lot.
  25.    Nevertheless, here is my first effort at a 'C' windowing package.
  26.    Humble as it may be the cost is right on.  It is free and you can have
  27.    the source code.  I don't want to sell it to you and I don't want you to
  28.    make a contribution if you like it.    It is 100% public domain software,
  29.    do with it as you please.
  30.  
  31.                  Compilers Supported
  32.                  ===================
  33.  
  34.    This software has been developed using both Borland Turbo C V1.0 and
  35.    Microsoft C V5.00.  I've also tested the code using Microsoft C V4.00.
  36.    I've tried to write this code in a portable manner and it should compile
  37.    with little or no change on most of the newer compilers which are
  38.    following the ANSI standard.  I have used the Microsoft extension
  39.    keywords "pascal" and "near" to generate more efficient code but, if
  40.    your compiler doesn't support them, they can be removed without harming
  41.    anything.
  42.  
  43.                     Files
  44.                     =====
  45.  
  46. The package consists of a single header and two source code files:
  47.  
  48.       WIN.H        The header file for use by the application code
  49.             as well as the windowing library code.
  50.  
  51.       WIN.C        The high level windowing functions. All code in
  52.             this file is machine independent.
  53.  
  54.       SCRIO.C        The low level screen access routines.  This code
  55.             is machine dependent and is written for the IBM/PC
  56.             and true compatibles.
  57.  
  58.       WINDEMO.C     A short demo program which shows some of the
  59.             windowing functions in action.
  60.  
  61.                    Video Equipment
  62.                    ===============
  63.  
  64.    This code will work properly on both TTL Monchrome and IBM CGA video
  65.    boards.  In addition, it should work fine on both EGA and VGA boards.
  66.    Following are some comments related to these video cards:
  67.  
  68.      -    Monochrome:    The ScrInitialize function will detect a monochrome
  69.                mode and automatically convert all attribute bytes
  70.                to black and white.  This is done in a manner that
  71.                I find to be reasonable, if you disagree change the
  72.                code that does the conversion.
  73.  
  74.      -    CGA:           Due to the snow generated by most CGA cards if the
  75.                video buffer is accessed during video refresh this
  76.                code disables the video signal while directly
  77.                updating the video buffer.
  78.  
  79.      -    EGA:           Currently EGA color modes are treated as CGA.  Most
  80.                schemes I've seen to detect an EGA search the EGA
  81.                extended BIOS for the IBM copyright notice.  This,
  82.                to me, is not a good approach.  I have seen one
  83.                method which used an INT 10h function added by the
  84.                EGA which caused no harm if an EGA was not
  85.                installed.  At the time I read about it I was not
  86.                really interested in EGA and now that I am I can't
  87.                find the article.  I also don't have access to EGA
  88.                documentation so I can't even figure out which
  89.                routine was being used.    If you know how to detect
  90.                EGA add the code to ScrInitialize.  Most EGA's
  91.                will work as CGA with the video signal being
  92.                disabled but this is not required with the EGA.
  93.  
  94.      -    VGA:           Currently VGA color modes are treated as CGA.  I've
  95.                never seen a VGA or any docs on it.  If you've got
  96.                one, I hope this code works.  If it doesn't,
  97.                I'm sorry, but I can't help.
  98.  
  99.  
  100.                  Room for Improvement
  101.                  ====================
  102.  
  103.    The functions included in this package provide the basics for developing
  104.    an application using a windowed environment.  There is certainly room
  105.    for improvement and I encourage you to enhance the functionality of
  106.    this package.  Some suggestions:
  107.  
  108.     -  Enhance the Move and Hide window functions to support windows which
  109.        are not fully visible (i.e. partially overlayed).
  110.  
  111.     -  Use these functions to develop a higher level of support for things
  112.        like 123 style menus, pull down menus, data entry forms, etc.
  113.  
  114.     -  Speed up the TextOut functions.    These functions rely on the ROM
  115.        BIOS character out routines as a result of my desire to stay 100%
  116.        with 'C' code.  I was tempted many times to rip out ScrTextOut and
  117.        replace it with assembly code which directly accessed the hardware.
  118.        I've resisted only because the BIOS code is tolerable in most
  119.        situations and this code is much more portable than assembly code.
  120.        With higher speed machines becoming more commonplace this problem
  121.        may diminish.
  122.  
  123.    I intend to work on some of these enhancements as time permits and I'm
  124.    sure you can think of many more.  I would be very pleased if people
  125.    making fixes and enhancements to this code would communicate their work
  126.    to me.  If we all work together we may be able to come up with a public
  127.    domain package which rivals those expensive commercial versions.
  128.  
  129.                   Disclaimer
  130.                   ==========
  131.  
  132.    Many people in the software industry are quite happy to sell you
  133.    software while assuming no responsibility for its functionality or
  134.    usefulness.    I am happy to give you this software but I also cannot
  135.    accept any responsibility for it.  I've tested this code and to the best
  136.    of my knowledge it works and contains no errors.  I simply state that I
  137.    think it is both functional and useful, I do not guarantee it.  You need
  138.    to test the code to determine if it will be useful to you.  If you
  139.    encounter problems with it, fix them.  That's why you wanted the source
  140.    in the first place, right?
  141.  
  142.                  Bob Withers
  143.                   649 Meadowbrook St
  144.                   Allen, Texas 75002
  145.  
  146.              Functions Available in WIN.C
  147.              ============================
  148.  
  149. WinExplodeWindow       Draws an exploding window on the screen. The
  150.                screen area behind the window is not saved, the
  151.                window is simply drawn.
  152.  
  153. WinDrawWindow           Draws a window on the screen without saving the
  154.                screen area behind the window.
  155.  
  156. WinCreateWindow        Creates a screen window and displays it at the
  157.                requested location.  The are behind the window
  158.                is saved and will be restored when the window
  159.                is destroyed.
  160.  
  161. WinDestroyWindow       Destroys a previously created window.  The
  162.                saved screen area is restored and all resources
  163.                allocated to support the window are freed.
  164.  
  165. WinScrollWindowUp      Scrolls a window up one line.
  166.  
  167. WinScrollWindowDown    Scrolls a window down one line.
  168.  
  169. WinSetCursorPos        Positions the cursor either relative to an
  170.                open window or to absolute screen locations.
  171.  
  172. WinClearScreen           Clears a window (or the entire screen) to the
  173.                requested color attribute.
  174.  
  175. WinTextOut           Displays a string within the requested window
  176.                at the current cursor location (for the
  177.                selected window).  If the string would extend
  178.                beyond the window it is truncated.
  179.  
  180. WinCenterText           Centers a text string within a window on the
  181.                requested row.
  182.  
  183. WinMoveWindow           Moves an existing window to a new location on
  184.                the screen.  There are a couple of caveats in
  185.                this version of the package:
  186.              1)  The window must be fully visible (i.e. no
  187.                  other window overlaying any part of it)
  188.                  for this routine to work properly.
  189.              2)  It is the callers responsibility to
  190.                  insure that the moved window will still
  191.                  fit on the screen at the new location.
  192.              3)  The size of the window may not be changed,
  193.                  it can only be moved to a new location.
  194.  
  195. WinGetWindowRow        Returns the absolute row (1 relative) of the
  196.                selected window.
  197.  
  198. WinGetWindowCol        Returns the absolute column (1 relative) of
  199.                the selected window.
  200.  
  201. WinGetWindowWidth      Returns the number of columns available for
  202.                text within the selected window. If the
  203.                window was created with a border, this value
  204.                will be two less than the width specified in
  205.                the create call.
  206.  
  207. WinGetWindowHeight     Returns the number of rows available for text
  208.                within the selected window.  If the window was
  209.                created with a border, this value will be two
  210.                less than the height specified in the create
  211.                call.
  212.  
  213. WinGetWindowClr        Returns the background color of a window.
  214.  
  215. WinGetWindowBdrClr     Returns the border color of a window.
  216.  
  217. WinGetBorderType       Returns the border type of a window.
  218.  
  219. WinHideWindow           Removes a window from the screen.  The window
  220.                still exists and is saved in it's current state.
  221.                All the caveats listed under WinMoveWindow
  222.                apply to the function.
  223.  
  224. WinShowWindow           Shows a window which is hidden and frees the
  225.                buffer used to hold the current state of the
  226.                window.
  227.  
  228. WinInitialize           Initializes the window package.    This function
  229.                must be called once before any of the other
  230.                functions in this package are used.  It should
  231.                NEVER be called while windows are open or the
  232.                buffers allocated to support them will be
  233.                stranded and their handles will no longer be
  234.                valid.
  235.  
  236. WinTerminate           Assures that all open windows are closed.
  237.  
  238.  
  239.             Functions Available in SCRIO.C
  240.             ==============================
  241.  
  242. ScrGetRectSize          Calculates the number of bytes required to
  243.               store a screen image.
  244.  
  245. ScreenClearRect       Clears a rectangle on the screen to the passed
  246.               color value.
  247.  
  248. ScrSaveRect          Save a screen rectangle in a buffer provided
  249.               by the caller.
  250.  
  251. ScrRestoreRect          Restores a saved screen image from a buffer
  252.               passed by the caller.
  253.  
  254. ScrSetCursorPos       Positions the cursor to an absolute screen
  255.               location (1 relative).
  256.  
  257. ScrGetCursorPos       Gets the absolute screen location of the cursor.
  258.  
  259. ScrCursorOn          Enables the screen cursor.
  260.  
  261. ScrCursorOff          Disables the screen cursor.
  262.  
  263. ScrTextOut          Displays a text string to the video screen.
  264.  
  265. ScrDrawRect          Draws the selected border around a screen
  266.               retangle.
  267.  
  268. ScrInitialize          Determines the video equipment installed on the
  269.               machine. This routine is called by WinInitialize
  270.               and does not need to invoked by the user code.
  271.  
  272.