home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / CPROG / VISIONS.ZIP / VIS_WIND.TXT < prev    next >
Text File  |  1990-05-20  |  18KB  |  488 lines
  1. /*------------------------ VIS_WIND.TXT ------------------------*/
  2. /*                                                              */
  3. /*  This file contains the VISIONS Window Library Manual        */
  4. /*                                                              */
  5. /*         Copyright 1990 Dan Vogel & David Bernazzani          */
  6. /*                                                              */
  7. /*   Date        Initials        Comments                       */
  8. /*                                                              */
  9. /*  03/13/90       DCV       Initial Release 0.00.              */
  10. /*--------------------------------------------------------------*/
  11.  
  12.                         Overview
  13.  
  14.  
  15.    The VISIONS window library is a simple library, written in C, to 
  16. provide color or monochrome text windows on PC/XT/AT class machines.  The 
  17. library was originally written in Microsoft C 5.1, but an attempt to 
  18. separate compiler specific code into a separate source was made, and 
  19. this file, COMPSPEC.C, is provided with the library source.
  20.    The window library supports the following functions:
  21.  
  22.  
  23.      MGA, CGA, EGA, VGA, MCGA compatible color text windows.
  24.      Automatic color conversion for monochrome adaptors.
  25.      User selectable window colors and sizes.
  26.      Optional window borders and border type.
  27.      Pop-Up windows.
  28.      Exploding and Imploding windows.
  29.      Error windows.
  30.      Pagable file display windows.
  31.  
  32.  
  33.  
  34.  
  35.                         Theory of Operation
  36.  
  37.  
  38.    The following is an overview of the operation of the window 
  39. library routines.  This is intended to help the user to understand 
  40. the library's operation better, so that it may be used more effectively.
  41.    The VISIONS window system is intended to execute structures which 
  42. define windows.  These structures consist of headers which define 
  43. window coordinates, colors, and attributes.  Each structure is created 
  44. by a single call to a define windows routine.  Note that a window may not 
  45. be defined until the windows package is initialized by a call to 
  46. InitWindows.  Once a window has been defined it can be executed at any time.  
  47. Execution of a window causes the window to be displayed upon the screen in 
  48. the defined location.  Several attributes may affect the way in which a 
  49. window is displayed.  A pop up window saves the screen data underneath itself 
  50. prior to display, so that the previous screen may be restored when the window 
  51. is removed.  An exploded window 'explodes' outward from its defined center.  
  52. A window may also have a title and a border.  Once the window is executed, 
  53. it is displayed on the screen with appropriate colors, borders, and titles, 
  54. but the rest of the contents of the window will be blank.  This may be filled 
  55. in using other window routines provided, such as WindMesgPtr.  
  56.    Removing a window from the display is accomplished by the RemoveWindow 
  57. routine.  This routine determines the correct way to remove a window 
  58. depending upon its attributes, such as implode and pop-up.  The window 
  59. definition structure is still active at this point and the window could be 
  60. executed again, but the contents of the window prior to removal are lost.  
  61. Finally the window definition structure is freed by the routine DeleteWindow.
  62.  
  63.    In brief, to use the VISIONS window library to execute a window, up to 
  64. seven steps must be taken:
  65.         1) Initialize windows once.            - InitWindow.
  66.         2) Define the window structure.        - DefineWindow.
  67.         3) Display the window.                 - DisplayWindow.
  68.         4) Display items within the window.    - SetWindow, SetWindowPtr, 
  69.                                                  WindMesg, WindMesgPtr.
  70.         5) Remove the window from the screen.  - RemoveWindow.
  71.         6) Release the window storage.         - DeleteWindow.
  72.         7) Exit windows once.                  - ExitWindow.
  73.  
  74.    Two windows may be created without any of these steps.  The routines, 
  75. ErrWindow and HelpWindow may be used to display a single line error message 
  76. and to display the contents of a file to a window respectively.  These two 
  77. routines create, display, and remove a window without any further routine 
  78. calls.
  79.  
  80.  
  81.  
  82.  
  83.  
  84.                         Routine Definitions
  85.  
  86.    In order to use the below routines you must include the file 
  87. "USERWIND.H" in your source code with the following statement.
  88.  
  89.                 #include "USERWIND.H"
  90.  
  91. Examples of the use of these routines are available in the VISIONS 
  92. demonstration program, in the file DEMOWIND.C.
  93.  
  94.  
  95.  
  96. /*------------------------------------------------------------------------*/
  97.                         DefineWindow
  98.  
  99. Purpose:  This routines creates a new window structure, complete with color, 
  100.   border, and position definitions.
  101.  
  102. Calling Sequence: 
  103.    status = DefineWindow(new_wind,topy,leftx,height,width,bkcol,txtcol,
  104.         title, border, explode, implode, popup);
  105.  
  106. Inputs:
  107.    BYTE topy, leftx, height, width;  - Respective row, col, height and width 
  108.         coordinates.  The height parameter is the # of rows to make the 
  109.         window down and the width is the # of cols to make the window wide.  
  110.         The row and col values specify the top left corner of the help
  111.         window created.
  112.  
  113.    long int bkcol, txtcol;  - These are the background and text colors to 
  114.         be used for the help window.  Possible values include TEXT_BLUE, 
  115.         TEXT_BLACK, and others specified in InitWindow.
  116.  
  117.    char *title;  - This is the title of the window created.  This title can 
  118.         be NULL, the empty string, or a string shorter than the window is 
  119.         wide.
  120.  
  121.    BYTE border;  - This is the type of border desired for the menu.  
  122.         Possibilities are NOBORDER, SINGLEBORDER, and DOUBLEBORDER.
  123.  
  124.    BYTE explode, implode, popup;  - These are TRUE/FALSE options for window 
  125.         display.  The options are for the window to explode outward, implode 
  126.         inward on closing, and whether or not to popup (save underlying 
  127.         screen).
  128.  
  129. Outputs:
  130.    WINDOW_HEAD **new_wind;  - This is a pointer to the window structure 
  131.         created describing the window.
  132.  
  133.    int status;  - This is the result of the function.  Possible values are:
  134.         0                         Success
  135.         OUT_OF_WINDOW_HEAP        Out of heap for allocating window.
  136.         BAD_WINDOW_DEF            Bad coordinates passed for window.
  137.         <others>                  As returned by called functions.
  138.  
  139. Functions called:
  140.    SaveWindow.
  141.  
  142. /*------------------------------------------------------------------------*/
  143.  
  144.  
  145.  
  146.  
  147. /*------------------------------------------------------------------------*/
  148.                         DeleteWindow
  149.  
  150. Purpose:  This routine releases all memory attached to the window structure.
  151.  
  152. Calling Sequence: 
  153.    status = DeleteWindow(window_ptr);
  154.  
  155. Inputs:
  156.    WINDOW_HEAD *window_ptr;  - This is a pointer to the window structure 
  157.         describing the window to be deleted.
  158.  
  159. Outputs:
  160.    int status; - This is the result of the function.  Possible values are:
  161.         0                       Success
  162.         NOT_A_WINDOW_POINTER    Bad pointer passed, not a window structure.
  163.  
  164. Functions called:
  165.    free.
  166.  
  167. /*------------------------------------------------------------------------*/
  168.  
  169.  
  170.  
  171.  
  172. /*------------------------------------------------------------------------*/
  173.                         DisplayWindow
  174.  
  175. Purpose:    This routine displays the window described in the passed 
  176.  structure.
  177.  
  178. Calling Sequence: 
  179.    status = DisplayWindow(window_ptr);
  180.  
  181. Inputs:
  182.    WINDOW_HEAD *window_ptr;  - This is a pointer to the window structure 
  183.         describing the window to be displayed.
  184.  
  185. Outputs:
  186.    int status;  - This is the result of the call.  Possible values are:
  187.         0                       Success.
  188.         NOT_A_WINDOW_POINTER    Bad pointer passed, not a window structure.
  189.         <Others>                As returned by called routines.
  190.  
  191. Functions called:
  192.    ExplodeWindow,  Window,  SaveWindow.
  193.  
  194. /*------------------------------------------------------------------------*/
  195.  
  196.  
  197.  
  198. /*------------------------------------------------------------------------*/
  199.                         ErrWindow
  200.  
  201. Purpose:  This routine displays a window centered in the screen with 
  202.  the passed message displayed.  Background is always set to red with 
  203.  white text.
  204.  
  205. Calling Sequence: 
  206.    status = ErrWindow(msg);
  207.  
  208. Inputs:
  209.    char *msg;  - This is the message stirng to be displayed.
  210.  
  211. Outputs:
  212.    int status; - This is the result of the function.  Possible values are:
  213.         0               Success
  214.         <others>        As returned by called functions.
  215.  
  216. Functions called:
  217.    DefineWindow,  DisplayWindow,  WindMesg,  RemoveWindow,  DeleteWindow
  218.    GetKey.
  219.  
  220. /*------------------------------------------------------------------------*/
  221.  
  222.  
  223.  
  224.  
  225. /*------------------------------------------------------------------------*/
  226.                         ExitWindow
  227.  
  228. Purpose:   This routine restores wrapon, and the cursor, and the default
  229.  video setup.  All windows should be popped before this call.
  230.  
  231. Calling Sequence: 
  232.    ExitWindow();
  233.  
  234. Inputs:
  235.    None.
  236.  
  237. Outputs:
  238.    None.
  239.  
  240. Functions called:
  241.    WrapOn,  hidecursor,  SetVideoMode.
  242.  
  243. /*------------------------------------------------------------------------*/
  244.  
  245.  
  246.  
  247.  
  248. /*------------------------------------------------------------------------*/
  249.                         HelpWindow
  250.  
  251. Purpose: This routine displays the passed files name in window sized 
  252.  chunks as a help screen.  Note that this routine can be used for 
  253.  generalized file display!
  254.  
  255. Calling Sequence: 
  256.    status = HelpWindow(row, col, height, width, 
  257.         bkcol, txtcol, border, title, filename);
  258.  
  259. Inputs:
  260.    BYTE row, col, height, width;  - Respective row, col, height and width 
  261.         coordinates.  The height parameter is the # of rows to make the 
  262.         window down and the width is the # of cols to make the window wide.  
  263.         The row and col values specify the top left corner of the help
  264.         window created.
  265.  
  266.    long int bkcol, txtcol;  - These are the background and text colors to 
  267.         be used for the help window.  Possible values include TEXT_BLUE, 
  268.         TEXT_BLACK, and others specified in InitWindow.
  269.  
  270.    BYTE border; - This is the type of border to be drawn around the window.
  271.         Possible values are: NOBORDER, SINGLEBORDER, DOUBLEBORDER.
  272.  
  273.    char *title;  - This is the string to be used for the title of the 
  274.         window.  The null string, NULL, means no title to be displayed.
  275.  
  276.    char *filename;  - This is the name of the text file to be displayed
  277.         in the window created.
  278.  
  279. Outputs:
  280.    int status;  - This is the result of the call.  Possible values are:
  281.         0                               Success
  282.         UNABLE_TO_OPEN_HELPFILE         File Error.
  283.         HELP_WINDOW_TOO_SMALL           Window to small for display.
  284.         <others>                        As returned by called functions.
  285.  
  286. Functions called:
  287.    RemoveWindow,  DeleteWindow,  GetKey,  WindMesg,  DefineWindow,  
  288.    DisplayWindow.
  289.  
  290. /*------------------------------------------------------------------------*/
  291.  
  292.  
  293.  
  294.  
  295. /*------------------------------------------------------------------------*/
  296.                         InitWindow
  297.  
  298. Purpose:   This routine sets up the video segments that window routines
  299.  need to access the screen.  The video mode is also set and the cursor is 
  300.  turned off.  Colors used for all windows are defined at this point.  Call 
  301.  this routine before using the other window routines.
  302.  
  303. Calling Sequence: 
  304.         InitWindow();
  305.  
  306. Inputs:
  307.    None.
  308.  
  309. Outputs:
  310.    The color variables below are defined for color or monochrome operation.
  311.  The definitions are:
  312.        Color Variable       Color Value         Monochrome value
  313.  
  314.         TEXT_BLACK         INIT_TEXT_BLACK      INIT_TEXT_BLACK
  315.         TEXT_BLUE          INIT_TEXT_BLUE       INIT_TEXT_BLACK
  316.         TEXT_GREEN         INIT_TEXT_GREEN      INIT_TEXT_BLACK
  317.         TEXT_CYAN          INIT_TEXT_CYAN       INIT_TEXT_BLACK
  318.         TEXT_RED           INIT_TEXT_RED        INIT_TEXT_BLACK
  319.         TEXT_MAGENTA       INIT_TEXT_MAGENTA    INIT_TEXT_BLACK
  320.         TEXT_BROWN         INIT_TEXT_BROWN      INIT_TEXT_BLACK
  321.         TEXT_WHITE         INIT_TEXT_WHITE      INIT_TEXT_WHITE
  322.         TEXT_DGREY         INIT_TEXT_DGREY      INIT_TEXT_BLACK
  323.         TEXT_LBLUE         INIT_TEXT_LBLUE      INIT_TEXT_WHITE
  324.         TEXT_LGREEN        INIT_TEXT_LGREEN     INIT_TEXT_WHITE
  325.         TEXT_LCYAN         INIT_TEXT_LCYAN      INIT_TEXT_WHITE
  326.         TEXT_LRED          INIT_TEXT_LRED       INIT_TEXT_BWHITE
  327.         TEXT_LMAGENTA      INIT_TEXT_LMAGENTA   INIT_TEXT_WHITE
  328.         TEXT_YELLOW        INIT_TEXT_YELLOW     INIT_TEXT_WHITE
  329.         TEXT_BWHITE        INIT_TEXT_BWHITE     INIT_TEXT_BWHITE
  330.  
  331. Functions called:
  332.    WrapOn,  hidecursor,  SetVideoMode.
  333.  
  334. /*------------------------------------------------------------------------*/
  335.  
  336.  
  337.  
  338.  
  339. /*------------------------------------------------------------------------*/
  340.                         RemoveWindow
  341.  
  342. Purpose:   This routine removes the passed window from the screen.  This 
  343.  only has an effect if the window was a pop up window.
  344.  
  345. Calling Sequence: 
  346.    status = RemoveWindow(window_ptr);
  347.  
  348. Inputs:
  349.    WINDOW_HEAD *window_ptr;  - This is a pointer to the window structure 
  350.         describing the window to be removed from the display.
  351.  
  352. Outputs:
  353.    int status;  - This is the result of the call.  Possible values are:
  354.         0                       Success
  355.         NOT_A_WINDOW_POINTER    Bad pointer passed, not a window structure.
  356.  
  357. Functions called:
  358.    ImplodeWindow.
  359.  
  360. /*------------------------------------------------------------------------*/
  361.  
  362.  
  363.  
  364. /*------------------------------------------------------------------------*/
  365.                         SetWindow
  366.  
  367. Purpose:   This routine defines the window to be in use and sets up the 
  368.  color definitions.  This is mainly used for jumping between 
  369.  non-popup windows.
  370.  
  371. Calling Sequence: 
  372.    SetWindow(row, col, height, width, bkcol, txtcol);
  373.  
  374. Inputs:
  375.    BYTE row, col, height, width;  - Respective row, col, height and width 
  376.         coordinates.  The height parameter is the # of rows to make the 
  377.         window down and the width is the # of cols to make the window wide.  
  378.         The row and col values specify the top left corner of the help
  379.         window created.
  380.  
  381.    long int bkcol, txtcol;  - These are the background and text colors to 
  382.         be used for the help window.  Possible values include TEXT_BLUE, 
  383.         TEXT_BLACK, and others specified in InitWindow.
  384.  
  385. Outputs:
  386.    None.
  387.  
  388. Functions called:
  389.    SetTextWindow,  SetBkColor,  SetTextColor.
  390.  
  391. /*------------------------------------------------------------------------*/
  392.  
  393.  
  394.  
  395.  
  396. /*------------------------------------------------------------------------*/
  397.                         SetWindowPtr
  398.  
  399. Purpose:   This routine defines the window to be in use and sets up the 
  400.  color definitions.  This is mainly used for jumping between 
  401.  non-popup windows.
  402.  
  403. Calling Sequence: 
  404.    status = SetWindowPtr(window_ptr);
  405.  
  406. Inputs:
  407.    WINDOW_HEAD *window_ptr;  - This is a pointer to the window structure 
  408.         describing the window desired.
  409.  
  410. Outputs:
  411.    int status;  - This is the result of the call.  Possible values are:
  412.         0                        Success
  413.         NOT_A_WINDOW_POINTER     Bad pointer passed, not a window structure.
  414.  
  415. Functions called:
  416.    SetWindow.
  417.  
  418. /*------------------------------------------------------------------------*/
  419.  
  420.  
  421.  
  422.  
  423. /*------------------------------------------------------------------------*/
  424.                         WindMesg
  425.  
  426. Purpose:   This routine displays a text string at a specific point on the 
  427.    current window.
  428.  
  429. Calling Sequence: 
  430.    WindMesg(row, col, message);
  431.  
  432. Inputs:
  433.    BYTE row, col;  - Respective row, and column where message is to be 
  434.         displayed.
  435.  
  436.    char *message;  - This is the text string to display.
  437.  
  438. Outputs:
  439.    None.
  440.  
  441. Functions called:
  442.    SetTextPosition,  OutText.
  443.  
  444. /*------------------------------------------------------------------------*/
  445.  
  446.  
  447.  
  448.  
  449. /*------------------------------------------------------------------------*/
  450.                         WindMesgPtr
  451.  
  452. Purpose:   This routine displays a text string at a specific point in the 
  453.    specified window.
  454.  
  455. Calling Sequence: 
  456.    WindMesgPtr(window_ptr,row, col, message);
  457.  
  458. Inputs:
  459.    WINDOW_HEAD *window_ptr;  - Pointer to window structure to be 
  460.         made current.
  461.    BYTE row, col;  - Respective row, and column where message is to be 
  462.         displayed.
  463.    char *message;  - This is the text string to display.
  464.  
  465. Outputs:
  466.    None.
  467.  
  468. Functions called:
  469.    SetWindowPtr,  WindMsg.
  470.  
  471. /*------------------------------------------------------------------------*/
  472.  
  473.  
  474.  
  475.  
  476.                         Error Codes
  477.  
  478.    The following is the list of error codes that can be returned from the 
  479. VISIONS window library.
  480.  
  481. Error Name              Value       Description.
  482.  
  483. UNABLE_TO_OPEN_HELPFILE -201        File opening error.
  484. HELP_WINDOW_TOO_SMALL   -202        Display window too small!
  485. OUT_OF_WINDOW_HEAP      -203        Out of heap for pop up storage.
  486. NOT_A_WINDOW_POINTER    -204        Bad window structure pointer.
  487. BAD_WINDOW_DEF          -205        Size of window exceeds screen.
  488.