home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / screen / scrn02 / scrn.doc < prev    next >
Encoding:
Text File  |  1987-10-27  |  7.3 KB  |  210 lines
  1.      March 19, 1987
  2.  
  3.  
  4.      SCRN.ARC is a collection of MSC callable functions that provide 
  5.      fast direct screen reading and writing of chars, strings, and
  6.      blocks of screen memory while *automatically* turning horizontal
  7.      retrace checking on/off based on the type of video card in use. 
  8.      The scrn_init() function checks for monochrome or EGA adapters,
  9.      and if it finds neither, assumes that a CGA card is in use and
  10.      turns on horizontal retrace checking to prevent snow. When retrace
  11.      checking is enabled, all screen i/o is performed one byte at a time
  12.      to prevent even left edge snowing. You also have the option of
  13.      playing it safe and manually setting retrace checking to on.
  14.  
  15.      Included are functions for real and logical cursor positioning,
  16.      color/attribute setting, scrolling, determining various video
  17.      types and settings, etc....And just for fun, a zoom-in window
  18.      similar to Procomm's exploding windows.  ZOOMDEMO.EXE is an
  19.      example of most of the functions in use.
  20.  
  21.      IMPORTANT - Before using any scrn_xxx function, two steps must
  22.      be taken, preferably from within main()'s source file:
  23.  
  24.           1) Declare a structure of type SCRN. Example: SCRN scrn;
  25.  
  26.           2) Initialize the structure. Example: scrn_init(&scrn);
  27.  
  28.      Without these two steps, your computer will probably freeze. Freezing
  29.      can also be cause by passing an incorrect number of parameters,
  30.      but the compiler will warn you about that as long as you include
  31.      the function declarations in the video.h file. One other cause of
  32.      freezing is incorrectly passing the structure address, like using
  33.      the address operator (&) from inside a function you've already passed
  34.      the structure's address to. I highly recommend using the MSC /W2
  35.      switch to add warnings of such things during compiling.       
  36.  
  37.  
  38.      Most of the functions in SCRN.ARC are used in ZOOMDEMO.EXE and are
  39.      documented in their source files. Here is a brief listing of each
  40.      function's type declaration, it's description, and example usage.
  41.      
  42.      void scrn_init(SCRN *) - Initializes the screen data structure with
  43.           information specific to the type of video adapter in use and it's
  44.           current mode. Must be called prior to any other scrn_xxx functions.
  45.  
  46.           Ex: SCRN xxx;
  47.               scrn_init(&xxx);
  48.   
  49.  
  50.      void scrn_puts(char *, SCRN *) - Writes a string at the current logical
  51.           cursor position, with the current attribute. The logical cursor is
  52.           updated. 
  53.  
  54.           Ex: scrn_puts("Bop 'til you drop", &xxx);
  55.  
  56.  
  57.      void scrn_putca(int, SCRN *) - Writes a char at the current logical 
  58.           cursor position with the current attribute. The logical cursor
  59.           is advanced.
  60.  
  61.           Ex: scrn_putca('X', &xxx);
  62.  
  63.  
  64.      int scrn_getca(int *, SCRN *) - Reads the char and attribute at the 
  65.           current logical cursor position. The return value is the char.
  66.           The attribute is contained in int* upon return. The logical
  67.           cursor is advanced.
  68.  
  69.           Ex: int ch, at;
  70.               ch = scrn_getca(&at, &xxx);
  71.  
  72.  
  73.      void scrn_save(int, int, int, int, char *, SCRN *) - Saves a rectangular
  74.           area of the screen to a user defined buffer. 
  75.  
  76.           Ex: scrn_save(LEFT, RIGHT, TOP, BOTTOM, &buff, &xxx);
  77.  
  78.  
  79.      void scrn_restore(int, int, int, int, char *, SCRN *) - Restores a user
  80.           defined buffer to a rectangular area of the screen. Same parameters
  81.           as scrn_save.
  82.  
  83.  
  84.  
  85.      void scrn_pos(int, int, SCRN *) - Positions the logical cursor (offset
  86.           within the screen buffer).
  87.  
  88.           Ex: scrn_pos(10, 10, &xxx);
  89.  
  90.  
  91.      void scrn_attrib(int, SCRN *) - Sets the attribute for subsequent writes.
  92.           See video.h for attribute definitions.
  93.  
  94.           Ex: scrn_attrib(INVERSE, &xxx);
  95.  
  96.  
  97.      void scrn_color(int, int, SCRN *) - Sets the foreground and background
  98.           color attribute for subsequent writes. See video.h for colors.
  99.  
  100.           Ex: scrn_color(fore, back, &xxx);
  101.  
  102.  
  103.      void scrn_set_cga(int, SCRN *) - Allows manual override of the automatic
  104.           horizontal retrace checking switch. Passing 0 turns off retrace
  105.           checking, 1 turns it on.
  106.  
  107.           Ex: scrn_set_cga(TRUE, &xxx);
  108.  
  109.  
  110.      void scrn_border(int, int, int, int, int, SCRN *) - Draws a lined
  111.           border at the given parameters with the current attribute.
  112.       If TYPE = 1 a single line else a double line
  113.  
  114.           Ex: scrn_border(LEFT, RIGHT, TOP, BOTTOM, TYPE, &xxx);
  115.  
  116.  
  117.      void scrn_hborder(int, int, int, int, SCRN *) - Draws a double lined
  118.           half border with the current attribute. In other words, writes a
  119.           top and bottom border with corners. 
  120.  
  121.           Ex: scrn_hborder(LEFT, RIGHT, TOP, BOTTOM, &xxx);
  122.  
  123.  
  124.      void scrn_wzoom(int, int, int, int, char *, int, SCRN *) - Draws a 
  125.       zoom-in window with the current attribute and saves the area 
  126.           used to a user defined buffer which may be restored with 
  127.           scrn_restore. Uses same type variables as scrn_border.
  128.  
  129.           Ex: scrn_wzoom(LEFT, RIGHT, TOP, BOTTOM, &buff, TYPE, &xxx);
  130.  
  131.  
  132.  
  133.      int vid_state(int *) - Returns the current video mode (mono, CO80, etc.)
  134.           and places the screen column width in int*. See video.h for modes.
  135.  
  136.           Ex: int cols, mode;
  137.               mode = vid_state(&cols);
  138.  
  139.  
  140.  
  141.      void vid_init(int) - Sets the desired video mode. See video.h.
  142.  
  143.           Ex: vid_init(CO80);   /* set video to color/80 columns */
  144.  
  145.  
  146.  
  147.      void vid_page(int) - Selects the desired video page.
  148.  
  149.           Ex: vid_page(0);    /* select page zero */
  150.  
  151.  
  152.  
  153.      void vid_set_cur(int, int) - Sets the real cursor position.
  154.  
  155.           Ex: vid_set_cur(10,10);
  156.  
  157.  
  158.  
  159.      void vid_get_cur(int *, int *) - Saves the real cursor position to
  160.           two user defined integers.
  161.  
  162.           Ex: int row, col;
  163.                vid_get_cur(&row, &col);  /* must pass address */
  164.  
  165.  
  166.  
  167.      void vid_cur_right(int) - Moves the real cursor right n times.
  168.  
  169.           Ex: vid_cur_rt(15); 
  170.  
  171.  
  172.  
  173.      void vid_cur_switch(int) - Turns the real cursor on/off.
  174.  
  175.           Ex: vid_cur_switch(OFF);  /* OFF = 0, ON = 1 */
  176.  
  177.  
  178.  
  179.      void vid_up(int, int, int, int, int, int) - Scrolls a rectangular
  180.           piece of the screen up by n positions with a given attribute.
  181.  
  182.           Ex: vid_up(0, LEFT, RIGHT, TOP, BOTTOM, BLUE);
  183.           If n = 0, the area will be blanked with the given attribute,
  184.           in this case BLUE.
  185.  
  186.  
  187.      void vid_down(int, int, int, int, int, int) - Scrolls down. Same
  188.           parameters as vid_up.
  189.  
  190.  
  191.  
  192.      int vcard_type(void) - Returns a value indicating the current video card
  193.           in use. 
  194.                     0 = Monochrome adapter
  195.                     1 = Color Graphics Card
  196.                     2 = Enhanced Graphics Adapter   
  197.  
  198.  
  199.  
  200.      Now the disclaimer...Although a reasonable amount of research, testing,
  201.      and experimenting has gone into this batch of functions, I make no
  202.      guarantees, implied or expressed, etc., etc. 
  203.  
  204.      Also, having only recently learned MSC and MASM, I wholeheartedly
  205.      welcome any comments or suggestions.
  206.  
  207.      Thanks...hope you find these useful.
  208.  
  209.      Tim Spencer - Compuserve [73657,1400]
  210.