home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / cprog / vlib105.zip / VIEWLIB.MAN < prev    next >
Text File  |  1992-10-27  |  24KB  |  812 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                                        ViewLib
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                                    Reference Manual
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.                          Copyright 1992, DB/Soft Publishing.
  31.                                  All rights reserved.
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.                                 Printed in the U.S.A.
  41.  
  42.                              Version 1.00, first printing
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.           Copyright________________________________________________________
  51.  
  52.           This software is protected under  United States Copyright Law and
  53.           International Treaty provisions.  DB/Soft Publishing reserves all
  54.           rights to ViewLib except for the following:
  55.  
  56.           A limited license is hereby granted allowing you use and evaluate
  57.           ViewLib for up  to 30 days.  You may also distribute unregistered
  58.           copies of  ViewLib  in its  entirety  to any  parties  interested
  59.           provided no  modification of  the  files in  the ViewLib  archive
  60.           occurs.    The  maximum  transaction  related  to  selling  media
  61.           containing unregistered copies of ViewLib  (eg Shareware vendors)
  62.           may not exceed $10.00.   Conversion to a more  convenient archive
  63.           format  is allowed.    All other  uses  of ViewLib  violate  this
  64.           license and are hereby expressly disallowed.
  65.  
  66.                         Copyright 1992, by DB/Soft Publishing,
  67.                                  All Rights Reserved.
  68.  
  69.                     3200 Truxel Rd #199, Sacramento, CA 95833 USA
  70.  
  71.                               Telephone: (916) 927-6951
  72.  
  73.                                  BBS: (916) 927-2349
  74.  
  75.           Limited Warranty_________________________________________________
  76.  
  77.           DB/Soft Publishing  grants no warranties, express  or implied, by
  78.           statute  or otherwise,  regarding this  software and  its related
  79.           materials, their fitness for any purpose, their quality, or their
  80.           merchantability.  In  no way shall  DB/Soft Publishing be  liable
  81.           for  any  special, consequential,  other  damages  for breach  of
  82.           warranty.
  83.  
  84.           This Statement  shall be  construed, interpreted and  governed by
  85.           the laws of the State of California.
  86.  
  87.           This  warranty will be replaced by a limited 90-day warranty that
  88.           covers the diskette, software and documentation upon registration
  89.           of ViewLib.
  90.  
  91.  
  92.           Registering ViewLib______________________________________________
  93.  
  94.           ViewLib  is an example  of software marketed  under the Shareware
  95.           concept.  The premise is simple:  you may evaluate  ViewLib for a
  96.           reasonable period  of time  (30 days  maximum)  during which  you
  97.           decide if  it is  a library  worth owning  and using  for viewing
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.           files  from within your applications.   If so,  you must register
  106.           ViewLib, using order.doc for  ordering information.  If, after  a
  107.           reasonable evaluation period, you decide not to register ViewLib,
  108.           you then must discontinue its use.
  109.  
  110.           This  provides me  with a way  to market  software with  very low
  111.           advertising  overhead, which  results in  a price  savings passed
  112.           directly on to you.  And, it provides you with a chance to 'play'
  113.           with my product and decide if it meets your needs. 
  114.  
  115.           As an incentive to speed the registration process, only the small
  116.           memory  model  of ViewLib  is  distributed  as shareware.    Upon
  117.           registration, you  will receive all the  available memory models:
  118.           small, medium,  compact  and  large,  for both  Borland  C++  and
  119.           Microsoft C.
  120.  
  121.  
  122.           Getting Help_____________________________________________________
  123.  
  124.           There are several ways of contacting the author, Jeff Dunlop, for
  125.           technical assistance if you get stuck.  From cheapest and slowest
  126.           to most expensive and fastest:
  127.  
  128.                - Fidonet's SHAREWRE echo
  129.  
  130.                - ILink's Shareware conference
  131.  
  132.                - Fidonet netmail at 1:203/16
  133.  
  134.                - Compuserve mail at 72147,3055
  135.  
  136.                - Internet at 72147.3055@compuserve.com
  137.  
  138.                - The DB/Soft Online at (916) 927-2349
  139.  
  140.                 - By mail at 3200 Truxel Rd #199 Sacramento CA 95833
  141.  
  142.           The best method of contacting  the author depends on the type  of
  143.           assistance you need.   If it's a rather complicated  problem, you
  144.           will  probably be far better  served if you  prepare a message in
  145.           advance  and upload  it  with a  source  example to  the  DB/Soft
  146.           Online.  We can then test it and offer suggestions.  If it's just
  147.           a question or suggestion about ViewLib capabilities, the ILink or
  148.           Fidonet conferences  will work best.   Fidonet netmail privileges
  149.           can be difficult to  get, but offer excellent timeliness  at very
  150.           low connect time.  Check your local Fidonet BBS if interested.
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.                                   Table of Contents
  159.  
  160.  
  161.                Chapter 1 Introduction .................................. 2
  162.                     Features ........................................... 2
  163.                     Requirements ....................................... 2
  164.                     Getting Started .................................... 2
  165.  
  166.                Chapter 2 Function Reference ............................ 4
  167.                     vlLister ........................................... 4
  168.                     vlGetVidMode ....................................... 6
  169.                     vlGetVidBase ....................................... 7
  170.                     vlGetCols .......................................... 8
  171.                     vlGetRows .......................................... 8
  172.                     vlIsDV ............................................. 9
  173.                     vlIsEgaVga ......................................... 9
  174.                     vlIsShift .......................................... 10
  175.                     vlIsRShift ......................................... 10
  176.                     vlIsLShift ......................................... 10
  177.                     vlIsMono ........................................... 10
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.                                           1
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.           Chapter 1 
  214.  
  215.           Introduction_____________________________________________________
  216.  
  217.  
  218.           Features_________________________________________________________
  219.  
  220.           ViewLib provides an excellent means  to providing report and file
  221.           viewing from  within  your C  applications.   Some  of  ViewLib's
  222.           features include:
  223.  
  224.               -     View any size file
  225.  
  226.               -     Resize and move the view window at will
  227.  
  228.               -     Completely define the color of the text and border.  
  229.  
  230.               -     Completely  define  the  characters  that  compose  the
  231.                     border.
  232.  
  233.               -     Define the initial size of the View window.
  234.  
  235.               -     ViewLib can  operate with as  little as  30k free  ram,
  236.                     which  is  released  back   to  your  application  when
  237.                     finished.
  238.  
  239.               -     Desqview, EGA  and VGA are all  detected and respected.
  240.                     In DesqView, the shadow buffer is used to avoid  bleed-
  241.                     through to other tasks. 
  242.  
  243.           Requirements_____________________________________________________
  244.  
  245.           You  must own either a Microsoft  or Borland C compiler.  ViewLib
  246.           should  be compatible  with  most if  not  all of  the  compilers
  247.           produced by  these two  companies, and  with any  other companies
  248.           that  produces compatible compilers  (Watcom comes to  mind).  If
  249.           you require ViewLib's functionality with an unsupported compiler,
  250.           the  only solution  is to  purchase the  source code  (please see
  251.           order.doc for details).
  252.  
  253.           Getting Started__________________________________________________
  254.  
  255.           ViewLib  can be linked into  any application just  like any other
  256.           library.    Therefore, you  should  copy  vl*.lib into  the  same
  257.           directory  that you  keep your  other  .lib files  in.   The file
  258.  
  259.  
  260.                                           2
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.           vlibbcs.lib  is for  Borland compilers,  and vlibmscs.lib  is for
  269.           Microsoft compilers.
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.                                           3
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.           Chapter 2
  324.  
  325.           Function
  326.           Reference________________________________________________________
  327.  
  328.  
  329.           vlLister_________________________________________________________
  330.  
  331.              Usage: int vlLister(char  *FileSpec, int  x1, int y1,  int x2,
  332.                     int  y2,  unsigned   char  Foreground,  unsigned   char
  333.                     Background, unsigned BufSize, BORDER *BorderInfo);
  334.  
  335.              Prototype in:  vlib.h
  336.  
  337.              Description:   vlLister  displays  in  the coordinates  x1, y1,
  338.                             x2,  y2 the  filename  passed.   The coordinates
  339.                             are 0-based.   The minimum  allowed buffer  size
  340.                             is eight kilobytes (8092  bytes).  The suggested
  341.                             optimum buffer size is  also 8k.   The only time
  342.                             that  it might  be  beneficial to  work  with  a
  343.                             larger buffer is  in the case of reading a  file
  344.                             on  a  floppy  drive.    The  valid  colors  for
  345.                             Background (defined in vlib.h) are as follows:
  346.  
  347.                             VL_BLACK,  VL_BLUE, VL_GREEN,  VL_CYAN,  VL_RED,
  348.                             VL_MAGENTA, VL_BROWN, VL_LIGHTGREY
  349.  
  350.  
  351.                             The valid colors  for Foreground are any of  the
  352.                             colors valid for Background, plus:
  353.  
  354.                             VL_DARKGREY,    VL_LIGHTBLUE,     VL_LIGHTGREEN,
  355.                             VL_LIGHTCYAN,   VL_LIGHTRED,    VL_LIGHTMAGENTA,
  356.                             VL_YELLOW, VL_WHITE
  357.  
  358.  
  359.                             The user-accessable fields of BorderInfo are:
  360.  
  361.                             bd_enable:  Set to  TRUE if  a border is  to be
  362.                                         displayed.   If  set to  FALSE, all
  363.                                         other values are ignored.
  364.  
  365.                             b_string:   A string  describing the characters
  366.                                         that  are  used   to  construct   a
  367.                                         border.  Any character value in the
  368.                                         extended   IBM  character   set  is
  369.  
  370.                                           4
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.                                         valid.  The string  "┌─┐│└─┘" would
  379.                                         make a box similar to:
  380.                                         ┌──────┐
  381.                                         │      │
  382.                                         └──────┘
  383.  
  384.                             Foreground: The    colors   valid    for   text
  385.                                         foreground are valid here as well.
  386.  
  387.                             Background: The    colors   valid    for   text
  388.                                         background are valid here as well.
  389.  
  390.  
  391.           Return value:  Upon  successful  completion, vlLister  returns 0.
  392.                          The following error codes are defined in vlib.h:
  393.  
  394.                        VLIB_ARGERR:   The  screen  coordinates  passed  were
  395.                        outside  the  range  of   the  current  text  screen.
  396.                        Remember that the coordinates are from  0 to 24, 0 to
  397.                        79 on CGA screens.
  398.                        VLIB_DOSERR: There  was  an error  reading the  file.
  399.                        Usually this means the name passed wasn't found.
  400.                        VLIB_ALLOCERR: A request for more memory was denied.
  401.  
  402.              Example:
  403.  
  404.              #include "vlib.h"
  405.  
  406.              void main(void)
  407.              {
  408.  
  409.                BORDER  BorderInfo  =  {{TRUE},   {"┌─┐│└─┘"},  {VL_YELLOW},
  410.                {VL_BLUE}};
  411.  
  412.                vlLister("file.txt",  1,  1,  78,  23,  VL_YELLOW,  VL_BLUE,
  413.                0x2000, &bd_info);
  414.              }
  415.  
  416.           The  behavior of vlLister depends on whether BorderInfo.bd_enable
  417.           is TRUE or FALSE.   If the border is disabled, then it is assumed
  418.           that the calling  function has  prepared a custom  border and  so
  419.           border resizing/window moving is disabled as well.  If the border
  420.           is enabled, then the base of the  border has the following string
  421.           displayed:
  422.  
  423.                   PgUp PgDn Home End Esc
  424.  
  425.                                           5
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.           These are a subset of the allowed keystrokes.  The complete  list
  434.           of legal keystrokes is:
  435.  
  436.           Home:   Display from the top of the file
  437.  
  438.           End:    Display the end of the file
  439.  
  440.           PgUp:   Display  the  previous  page  (varies  according  to   the
  441.                   current window size.
  442.  
  443.           PgDn:   Display the  next page  (varies according  to the  current
  444.                   window size
  445.  
  446.           Down:   Display the next line.
  447.  
  448.           Up:     Display the previous line.
  449.  
  450.           Right:  Shift the display left 10 columns.
  451.  
  452.           Left:   Shift the display right 10 columns.
  453.  
  454.           Ctl-Right*:
  455.           RShift-Right:  Lengthen the window to the right one column.
  456.  
  457.           Ctl-Left*:
  458.           RShift-Left:   Shorten the window to the left one column.
  459.  
  460.           Ctl-Dn*:
  461.           RShift-Dn:     Lengthen the window down one row.
  462.  
  463.           Ctl-Up*:
  464.           RShift-Up:     Shorten the window up one row.
  465.  
  466.           LShift-Right:  Move the window right one column.
  467.  
  468.           LShift-Up:     Move the window up one row.
  469.  
  470.           LShift-Left:   Move the window left one column.
  471.  
  472.           LShift-Dn:     Move the window down one row.
  473.  
  474.           * Only  supported on  101-key enhanced keyboards  with supporting
  475.           BIOS.
  476.  
  477.           vlGetVidMode_____________________________________________________
  478.  
  479.  
  480.                                           6
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.              Usage: unsigned char vlGetVidMode(void);
  489.  
  490.              Prototype in:  vlib.h
  491.  
  492.              Description:   vlGetVidMode returns  the current video mode  as
  493.                             reported by Bios.
  494.  
  495.              Return Value:  Refer  to a  MS-Dos technical  reference  manual
  496.                             for  the possible  return  values of  Bios video
  497.                             modes and their meanings.
  498.  
  499.              Example:
  500.  
  501.              #include <stdio.h>
  502.              #include "vlib.h"
  503.  
  504.              void main(void)
  505.              {
  506.                printf("Current video mode is %d\n", vlGetVidMode());
  507.              }
  508.  
  509.  
  510.           vlGetVidBase_____________________________________________________
  511.  
  512.              Usage: unsigned vlGetVidbase(void);
  513.  
  514.              Prototype in:  vlib.h
  515.  
  516.              Description:   vlGetVidBase returns the segment of the  current
  517.                             video display buffer.
  518.  
  519.              Return Value:  Usually, b000  will be  returned for  monochrome
  520.                             display,  and  b800 for  all  others.   However,
  521.                             DesqView  shadow  buffers may  contain different
  522.                             addresses on some platforms.
  523.  
  524.              Example:
  525.  
  526.              #include <stdio.h>
  527.              #include "vlib.h"
  528.  
  529.              void main(void)
  530.              {
  531.                printf("The  current  video  ram  base  address  is  %xd\n",
  532.                vlGetVidBase());
  533.              }
  534.  
  535.                                           7
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.           vlGetCols________________________________________________________
  545.  
  546.              Usage: int vlGetCols(void);
  547.  
  548.              Prototype in:  vlib.h
  549.  
  550.              Description:   vlGetCols   determines  the  number  of  columns
  551.                             currently being displayed.
  552.  
  553.              Return Value:  Most systems will return  80 columns.   However,
  554.                             DesqView windows  defined at  unusual sizes will
  555.                             be detected,  as  will  132-column  (and  other)
  556.                             displays.
  557.  
  558.              Example:
  559.  
  560.              #include <stdio.h>
  561.              #include "vlib.h"
  562.  
  563.              void main(void)
  564.              {
  565.                printf("The monitor  is currently displaying  %d columns\n",
  566.                vlGetCols());
  567.              }
  568.  
  569.  
  570.           vlGetRows________________________________________________________
  571.  
  572.              Usage: int vlGetRows(void);
  573.  
  574.              Prototype in:  vlib.h
  575.  
  576.              Description:   vlGetRows   determines   the  number   of   rows
  577.                             currently being displayed.
  578.  
  579.              Return Value:  Most systems  will  return  25 rows.    However,
  580.                             DesqView windows  defined at unusual sizes  will
  581.                             be detected,  as will  43-column, 50-column (and
  582.                             other) displays.
  583.  
  584.              Example:
  585.  
  586.              #include <stdio.h>
  587.              #include "vlib.h"
  588.  
  589.  
  590.                                           8
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.              void main(void)
  599.              {
  600.                printf("The  monitor  is  currently  displaying  %d rows\n",
  601.                vlGetRows());
  602.              }
  603.  
  604.  
  605.           vlIsDV___________________________________________________________
  606.  
  607.              Usage: int vlIsDV(void);
  608.  
  609.              Prototype in:  vlib.h
  610.  
  611.              Description:   vlIsDV  determines whether DesqView is installed
  612.                             and active.
  613.  
  614.              Return Value:  If  DesqView  is active,  vlIsDV  returns  TRUE;
  615.                             otherwise, FALSE is returned.
  616.  
  617.              Example:
  618.  
  619.              #include <stdio.h>
  620.              #include "vlib.h"
  621.  
  622.              void main(void)
  623.              {
  624.                printf("DesqView %s active\n", vlIsDV() ? "is" : "is not");
  625.              }
  626.  
  627.  
  628.           vlIsEgaVga_______________________________________________________
  629.  
  630.              Usage: int vlIsEgaVga(void);
  631.  
  632.              Prototype in:  vlib.h
  633.  
  634.              Description:   vlIsEgaVga  determines whether an enhanced color
  635.                             adapter is installed.
  636.  
  637.              Return Value:  If   an  EGA   or  VGA  adapter   is  installed,
  638.                             vlIsEgaVga  returns  TRUE; otherwise,  FALSE  is
  639.                             returned.
  640.  
  641.              Example:
  642.  
  643.              #include <stdio.h>
  644.  
  645.                                           9
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.              #include "vlib.h"
  654.  
  655.              void main(void)
  656.              {
  657.                printf("An EGA or VGA monitor %s installed.\n", vlIsEgaVga()
  658.                ? "is" : "is not");
  659.              }
  660.  
  661.  
  662.           vlIsShift
  663.           vlIsRShift
  664.           vlIsLShift_______________________________________________________
  665.  
  666.              Usage: int vlIsLshift(void);
  667.                     int vlIsRshift(void);
  668.                     int vlIsShift(void);
  669.  
  670.              Prototype in:  vlib.h
  671.  
  672.              Description:   vlIsShift,  vlIsLShift and vlIsRShift return the
  673.                             status  of  the  shift keys  as  appropriate for
  674.                             each function.
  675.  
  676.              Return Value:  If the appropriate  shift key is being  pressed,
  677.                             the function returns TRUE;   otherwise, FALSE is
  678.                             returned.
  679.  
  680.              Example:
  681.  
  682.              #include <stdio.h>
  683.              #include "vlib.h"
  684.  
  685.              void main(void)
  686.              {
  687.                printf("A shift key %s being pressed.\n", vlIsShift() ? "is"
  688.                : "is not"); 
  689.              }
  690.  
  691.  
  692.           vlIsMono_________________________________________________________
  693.  
  694.              Usage: int vlIsMono(void);
  695.  
  696.              Prototype in:  vlib.h
  697.  
  698.  
  699.  
  700.                                           10
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.              Description:   vlIsMono determines  if the  current video  mode
  709.                             is monochrome.
  710.  
  711.              Return Value:  If  the  current  video   mode  is   monochrome,
  712.                             vlIsMono   returns  TRUE;  otherwise,  FALSE  is
  713.                             returned.
  714.  
  715.              Example:
  716.  
  717.              #include <stdio.h>
  718.              #include "vlib.h"
  719.  
  720.              void main(void)
  721.              {
  722.                printf("The monitor %s monochrome video mode.\n", vlIsMono()
  723.                ? "is" : "is not");
  724.              }
  725.  
  726.           vlCursorOff_____________________________________________________
  727.  
  728.              Usage: void vlCursorOff(void);
  729.  
  730.              Prototype in:  vlib.h
  731.  
  732.              Description:   Turns  off the  text mode  cursor.   Many  Bios'
  733.                             have  bugs in this area, especially when dealing
  734.                             with  very old  Hercules adapters  any  many EGA
  735.                             adapters.  No attempt to address these bugs  has
  736.                             been attempted in  ViewLib.  In the worst  case,
  737.                             the  cursor   won't  disappear.    This  routine
  738.                             automatically calls vlCursorSave.
  739.  
  740.              Example:
  741.  
  742.              #include "vlib.h"
  743.  
  744.              void main(void)
  745.              {
  746.                vlCursorOff();
  747.              }
  748.  
  749.           vlCursorSave____________________________________________________
  750.  
  751.              Usage: void vlCursorSave(void);
  752.  
  753.              Prototype in:  vlib.h
  754.  
  755.                                           11
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.              Description:   Saves the current cursor  information for  later
  764.                             retrieval.  Only one cursor can  be saved.  Each
  765.                             call to  vlCursorSave overwrites the last cursor
  766.                             saved.  This information  is extracted from  the
  767.                             Bios  data area,  an area  which is  not used by
  768.                             the rare video adapter.  
  769.  
  770.              Example:
  771.  
  772.              #include "vlib.h"
  773.  
  774.              void main(void)
  775.              {
  776.                vlCursorSave();
  777.              }
  778.  
  779.           vlCursorRestore_________________________________________________
  780.  
  781.              Usage: void vlCursorRestore(void);
  782.  
  783.              Prototype in:  vlib.h
  784.  
  785.              Description:   Restores the last  cursor information saved.  If
  786.                             vlCursorSave()  was  not previously  called, the
  787.                             cursor's contents are undefined.
  788.  
  789.              Example:
  790.  
  791.              #include "vlib.h"
  792.  
  793.              void main(void)
  794.              {
  795.                vlCursorRestore();
  796.              }
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.                                           12
  811.  
  812.