home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 9 / FreshFishVol9-CD2.bin / bbs / util / breq-1.16.lha / BReq / BReq.man < prev    next >
Text File  |  1994-09-09  |  8KB  |  210 lines
  1.  
  2.  
  3.  
  4. BREQ()                  Some Programmer's Manual                  BREQ()
  5.  
  6.  
  7. NAME
  8.     BReq - opens  custom  screen with two gadgets for startup
  9.            options on either NTSC or PAL screen.
  10.  
  11. SYNOPSIS
  12.     BReq [ATEXT/K,BTEXT/K,BLANK/K,BUTTONS/K,DEFAULT/K,
  13.           REVERSE/S,SYSA/K,SYSB/K,TIMEOUT/K]
  14.  
  15. DESCRIPTION
  16.     BReq  opens  a    custom screen allowing two options to the
  17.     user.  The  options are named on two gadgets and by using
  18.     either mouse  or keyboard  selection the user can execute
  19.     a  system call or  exit from BReq.  The system call sends
  20.     one  string to the  system  which  can be declared on the
  21.     command line.    The  exit option  does no more than cause
  22.     BReq to exit  returning  the user to the calling shell or
  23.     script.
  24.  
  25.     BReq also  recognizes whether it is running under NTSC or
  26.     PAL  screen modes and will adjust the  screen, window and
  27.     gadgets accordingly.
  28.  
  29.     The default system gadget (top) executes
  30.  
  31.     "sys:loadbsd sys:vmunix -a"
  32.  
  33.     And  may be  declared  differently on the command line as
  34.     indicated below.
  35.  
  36.     This may seem almost entirely useless but, if used during
  37.     startup it  allows  the user the  ability to avoid a long
  38.     startup  sequence to  setup the  system with options  not
  39.     dependent  on  that startup  sequence  or  with different
  40.     options at some point in the startup script.
  41.  
  42. REQUIREMENTS
  43.     The  best  machine  ever created (for the unknowing, that
  44.     would  be  the    Amiga).  The Author has attempted to make
  45.     BReq independent of OS2.0+ specific code but, since there
  46.     is no access to 1.3 versions of  the  OS available to the
  47.     author    it  is impossible to  verify  that BReq will work
  48.     with versions of AmigaOS other than 2.0+
  49.  
  50. OPTIONS
  51.        The options for BReq are as follows:
  52.  
  53.        ATEXT="Top gadget comment"
  54.         Allows user to give the top gadget a trailing comment.
  55.         Default: " "
  56.        BTEXT="Bottom gadget comment"
  57.         Allows user to give bottom gadget a trailing comment.
  58.         Default: " "
  59.        BLANK=seconds
  60.         After an  idle time of seconds duration the screen is
  61.         blanked by setting registers 0 and 1 to black.   Upon
  62.         activity  either by the  keyboard or mouse the screen
  63.         will return to its previous mode.  The value  must be
  64.         given as an integer.
  65.         Default: 180 (3 minutes)
  66.        BUTTONS=top_button|bottom_button
  67.         This gives    each of the two  gadgets a separate title
  68.         different than the default. To make two blank buttons
  69.         use BUTTONS=" |".
  70.         Default: NetBSD|ADOS
  71.        DEFAULT=A/B
  72.         This  makes  the default  response of BReq either the
  73.         top  (A)  gadget  or  the  bottom (B)  gadget.   This
  74.         option  only  makes sense  when used with the TIMEOUT
  75.         option (see "TIMEOUT" below)
  76.         Default: A
  77.        REVERSE
  78.         REVERSE is a boolean  switch causing the screen to be
  79.         black  and    the gadgets to be white.
  80.         Default: FALSE
  81.        SYSA="string"
  82.         This  option  allows the user to select a system call
  83.         other than the above mentioned  default.   The string
  84.         may be  any valid  program string  as would be issued
  85.         from the  command line.   The string must be enclosed
  86.         in double quotes. This string is  attached to the top
  87.         gadget.
  88.         Default: "sys:loadbsd sys:vmunix -a"
  89.        SYSB="String"
  90.         Same as option SYSA.
  91.         Default: NULL
  92.        TIMEOUT=seconds
  93.         This option allows the user to select a timeout value
  94.         in seconds where in this period of time  if  no valid
  95.         response is  received from the user BReq will execute
  96.         the DEFAULT response (see DEFAULT above)
  97.         Default: 31536000 (one year)
  98.  
  99. RESPONSES
  100.        Valid responses using the mouse    should be obvious.  Valid
  101.        responses from the keyboard are
  102.  
  103.        v, y   (selects top gadget)
  104.        b, n   (selects bottom gadget)
  105.        RETURN (selects default response)
  106.        ESC    (selects opposite to default response)
  107.  
  108.        These were chosen as such to be compatible in some respect
  109.        with standards and with the previous versions of BReq.
  110.  
  111. SYNTAX
  112.        BReq [options]
  113.  
  114. EXAMPLES
  115.        BReq SYSA="echo Hello, world"
  116.  
  117.        Will cause the calling shell to echo "Hello, world" should
  118.        the user  select the top gadget.   Selection of the bottom
  119.        gadget will cause BReq to exit silently.
  120.  
  121.        BReq BUTTONS=Echo|Silent
  122.  
  123.        BReq  will open the BReq screen with two  gadgets entitled
  124.        "Echo" and "Silent".
  125.  
  126.        BReq REVERSE
  127.  
  128.        BReq will open a custom screen which  is black with  white
  129.        outlined gadgets.
  130.  
  131.        BReq BUTTONS=Echo|Silent SYSA="echo Hello"
  132.  
  133.        BReq will  open    as previously with the two gadgets titled
  134.        "Echo" and "Silent".  Selection of the "Echo" (top) gadget
  135.        will  cause  BReq to issue  the command to echo the string
  136.        "Hello"  to  the calling shell afterwhich BReq  will close
  137.        the  screen  and  exit.    Selection  of the "Silent" gadget
  138.        (bottom) will make BReq close the screen and exit silently.
  139.  
  140.        BReq BUTTONS=Echo|Silent SYSA="echo Hello" TIMEOUT=90
  141.  
  142.        Same as previous example  except that if BReq does not re-
  143.        ceive  a  valid    response inside  of  90 seconds BReq will
  144.        execute the default option (gadget A).
  145.  
  146.        BReq DEFAULT=B TIMEOUT=900 BLANK=30
  147.  
  148.        BReq  opens  normally and without interaction by way  of a
  149.        valid response, BReq will  blank the  screen in 30 seconds
  150.        and exit silently in 900 seconds (fifteen minutes)
  151.  
  152. DIAGNOSTICS
  153.        BReq returns non-zero values for any error. See the source
  154.        code for error explaination.
  155.  
  156. AUTHOR
  157.        Eric R. Augustine: uairk@mcl.mcl.ucsb.edu (til OCT94)
  158.               voodoo@well.sf.ca.us
  159.  
  160. BUGS
  161.        This is copyrighted  freeware  and  as such comes  with no
  162.        warantee  or  assurances whatsoever.  Any damage that is a
  163.        result  of  BReq's use  is not  the responsibility  of the
  164.        author.
  165.  
  166.        The  BUTTONS option  gives odd errors if the string is not
  167.        "normal".  BUTTONS="|  for  instance  will  make BReq send
  168.        garbage to the  default    system call in combination with a
  169.        command line change to the system call. BUTTONS=" | " will
  170.        cause BReq to exit silently as will BUTTONS="| ".  I can't
  171.        see  any advantage  to requesting button  titles like this
  172.        anyhow.    See  the OPTIONS  section above for  making blank
  173.        buttons.
  174.  
  175. TODO
  176.        Add a NoClick  flag  to stop that  annoying click from the
  177.        floppy drive.  Also, make the blanker more interesting.
  178.  
  179. LAST WORDS
  180.        BReq is Copyright (c)1994 by Eric R. Augustine. Being free
  181.        ware it may be handed  out,  passed on and out however you
  182.        feel as long as all original documentation and  source are
  183.        included and  that its  distribution  is not  done for the
  184.        gain of profit.    If you find BReq useful, have any suggest
  185.        ions, flames  or have  discovered a  bug or two the author
  186.        can  be contacted at  the above internet  e-mail addresses
  187.        All  comments,  suggestions,  bug  reports  and flames are
  188.        welcome.
  189.  
  190. CREDITS
  191.        Thanks to Samu Nuojua (author of the excellent SNMA macro-
  192.        assembler) for  catching a  bug and testing the BReq's PAL
  193.        recognition.
  194.  
  195.        Thanks to Anders Bjerin.  Reading the includes gave little
  196.        general help in getting the structures right.  The ACM did
  197.        though - that and insight into IDCMP.
  198.  
  199.        Thanks to Nico Francois for his great package "ReqTools"..
  200.        Even if I haven't used ReqTools in this current version it
  201.        offered    my initial leap  into this sort of programming on
  202.        the Amiga.
  203.  
  204.        Amiga - for making such an amazing machine..
  205.  
  206.        And of course, thanks to Markus Wild - for bringing NetBSD
  207.        to the Amiga.
  208.  
  209.  
  210.