home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / GadgetsForOS.LHA / BReq / BReq.man < prev    next >
Encoding:
Text File  |  1994-08-29  |  7.2 KB  |  202 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,SYSSTRING/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.
  69.         Default: NetBSD|ADOS
  70.        DEFAULT=A/B
  71.         This  makes  the default  response of BReq either the
  72.         top  (A)  gadget  or  the  bottom (B)  gadget.   This
  73.         option  only  makes sense  when used with the TIMEOUT
  74.         option (see "TIMEOUT" below)
  75.         Default: A
  76.        REVERSE
  77.         REVERSE is a boolean  switch causing the screen to be
  78.         black  and    the gadgets to be white.
  79.         Default: FALSE
  80.        SYSSTRING="string"
  81.         This  option  allows the user to select a system call
  82.         other than the above mentioned  default.   The string
  83.         may be  any valid  program string  as would be issued
  84.         from the  command line.   The string must be enclosed
  85.         in double quotes. This string is  attached to the top
  86.         gadget.
  87.         Default: "sys:loadbsd sys:vmunix -a"
  88.        TIMEOUT=seconds
  89.         This option allows the user to select a timeout value
  90.         in seconds where in this period of time  if  no valid
  91.         response is  received from the user BReq will execute
  92.         the DEFAULT response (see DEFAULT above)
  93.         Default: 31536000 (one year)
  94.  
  95. RESPONSES
  96.        Valid responses using the mouse    should be obvious.  Valid
  97.        responses from the keyboard are
  98.  
  99.        v, y   (selects top gadget)
  100.        b, n   (selects bottom gadget)
  101.        RETURN (selects default response)
  102.        ESC    (selects opposite to default response)
  103.  
  104.        These were chosen as such to be compatible in some respect
  105.        with standards and with the previous versions of BReq.
  106.  
  107. SYNTAX
  108.        BReq [options]
  109.  
  110. EXAMPLES
  111.        BReq SYSSTRING="echo Hello, world"
  112.  
  113.        Will cause the calling shell to echo "Hello, world" should
  114.        the user  select the top gadget.   Selection of the bottom
  115.        gadget will cause BReq to exit silently.
  116.  
  117.        BReq BUTTONS=Echo|Silent
  118.  
  119.        BReq  will open the BReq screen with two  gadgets entitled
  120.        "Echo" and "Silent".
  121.  
  122.        BReq REVERSE
  123.  
  124.        BReq will open a custom screen which  is black with  white
  125.        outlined gadgets.
  126.  
  127.        BReq BUTTONS=Echo|Silent SYSSTRING="echo Hello"
  128.  
  129.        BReq will  open    as previously with the two gadgets titled
  130.        "Echo" and "Silent".  Selection of the "Echo" (top) gadget
  131.        will  cause  BReq to issue  the command to echo the string
  132.        "Hello"  to  the calling shell afterwhich BReq  will close
  133.        the  screen  and  exit.    Selection  of the "Silent" gadget
  134.        (bottom) will make BReq close the screen and exit silently.
  135.  
  136.        BReq BUTTONS=Echo|Silent SYSSTRING="echo Hello" TIMEOUT=90
  137.  
  138.        Same as previous example  except that if BReq does not re-
  139.        ceive  a  valid    response inside  of  90 seconds BReq will
  140.        execute the default option (gadget A).
  141.  
  142.        BReq DEFAULT=B TIMEOUT=900 BLANK=30
  143.  
  144.        BReq  opens  normally and without interaction by way  of a
  145.        valid response, BReq will  blank the  screen in 30 seconds
  146.        and exit silently in 900 seconds (fifteen minutes)
  147.  
  148. DIAGNOSTICS
  149.        BReq returns non-zero values for any error. See the source
  150.        code for error explaination.
  151.  
  152. AUTHOR
  153.        Eric R. Augustine: uairk@mcl.mcl.ucsb.edu (til Sep94)
  154.               voodoo@well.sf.ca.us
  155.  
  156. BUGS
  157.        This is copyrighted  freeware  and  as such comes  with no
  158.        warantee  or  assurances whatsoever.  Any damage that is a
  159.        result  of  BReq's use  is not  the responsibility  of the
  160.        author.
  161.  
  162.        Timeout and  Blank can be off by  a second at times.  It's
  163.        not known  whether or not  this error grows over time but,
  164.        testing    with  timeouts of  fifteen minutes  BReq has been
  165.        found to be reasonably close.
  166.  
  167.        Also, a lack of access to a real PAL machine has made test-
  168.        ing the    PAL/NTSC  switching a little  difficult.  PAL has
  169.        been simulated with software ("pal" by Nico Francois).
  170.  
  171. TODO
  172.        Add a NoClick  flag  to stop that  annoying click from the
  173.        floppy drive.  Also, make the blanker more interesting.
  174.  
  175. LAST WORDS
  176.        BReq is Copyright (c)1994 by Eric R. Augustine. Being free
  177.        ware it may be handed  out,  passed on and out however you
  178.        feel as long as all original documentation and  source are
  179.        included and  that its  distribution  is not  done for the
  180.        gain of profit.    If you find BReq useful, have any suggest
  181.        ions, flames  or have  discovered a  bug or two the author
  182.        can  be contacted at  the above internet  e-mail addresses
  183.        All  comments,  suggestions,  bug  reports  and flames are
  184.        welcome.
  185.  
  186. CREDITS
  187.        Thanks to Anders Bjerin.  Reading the includes gave little
  188.        general help in getting the structures right.  The ACM did
  189.        though - that and insight into IDCMP.
  190.  
  191.        Just a quick thanks to Nico Francois for his great package
  192.        "ReqTools"... Even if I haven't used ReqTools in this cur-
  193.        rent version it offered    my initial leap into this sort of
  194.        programming on the Amiga.
  195.  
  196.        Amiga - for making such an amazing machine..
  197.  
  198.        And of course,  Markus Wild - for  bringing  NetBSD to the
  199.        Amiga.
  200.  
  201.  
  202.