home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d571 / gwin.lha / Gwin / Gwin.doc < prev    next >
Text File  |  1991-12-22  |  78KB  |  2,046 lines
  1.  
  2.      17 Nov 1991                      GWIN            by Howard C. Anderson
  3.  
  4.  
  5.                        GWIN GRAPHICS SYSTEM - Version 2.0
  6.                           AMIGA SHARED LIBRARY VERSION
  7.  
  8.                           Author:  Howard C. Anderson
  9.                                1895 E. Auburn Dr.
  10.                                 Tempe, Az 85283
  11.                                  (602) 897-7425
  12.  
  13.      GWIN V2.0 (c) Copyright 1991 Howard C. Anderson  All rights reserved.
  14.      Software may be distributed for non-profit only.  This software is NOT
  15.                      shareware, i.e., don't send me money.
  16.  
  17.  
  18.      The  Amiga  is  a  great  computer  but  don't  you think the graphics
  19.      interface involves a lot of drudgery?    I  mean  it  takes  almost  a
  20.      hundred  lines  of  code to set up enough trash and trivia to draw one
  21.      straight line segment.  (Refer to "Inside the Amiga"  by  John  Thomas
  22.      Berry - the example in the "Using Intuition" chapter, "The Creation of 
  23.      a Window in a Custom Screen".) 
  24.  
  25.      If  you  encapsulate  the  low-level  routines,  you  can simplify the
  26.      interface and still provide access to most of the low-level  features.
  27.      In addition, you can eliminate the possibility of GURUs. The trade-off 
  28.      of  course  is  ease-of-use,  virtual  windowing,  automatic clipping,
  29.      greatly simplified mouse and keyboard interaction, freedom from GURUs, 
  30.      automatic menu generation,  speed  of  application  development,  etc.
  31.      versus speed  of  execution.    If  your application needs extra speed
  32.      though, you can still call the Amiga low-level routines while in GWIN. 
  33.      You at least save yourself a lot of setup time because you can get any 
  34.      of five types of Amiga screens and a  window  up  by  using  just  ONE
  35.      PROCEDURE CALL.  
  36.  
  37.      Who needs GWIN?    I  do.   I am a mathematician who's been a software
  38.      engineer for quite some time.  The first machine I worked on  was  the
  39.      Philco  2000.  It was one of the largest and most powerful machines in
  40.      existence at the time (It had 1/5 the memory of the Amiga 2000 here on 
  41.      my desk and was probably slightly faster than the Amiga  for  floating
  42.      point calculations.) Graphics on the Philco 2000 consisted exclusively 
  43.      of assembly  language  programs  to produce plots on printers.  At two
  44.      runs per day maximum for compiling - and debugging  provided  for  via
  45.      200 page  core  dumps  it was all drudgery and I loved it.  I loved it
  46.      less as time went  on  but  there  is  great  mystique,  glamour,  and
  47.      prestige  associated  with  writing  programs  that  no  one  else can
  48.      understand or debug.  Is it the desire  for  such  past  glories  that
  49.      accounts for  the  sorts  of interfaces we have these days???  Perhaps
  50.      there is not enough time to neatly package things???  Perhaps the only 
  51.      possible   flexible   software    interfaces    are    of    necessity
  52.      mind-warpers???   Maybe  everyone  but  me  has  time  to  muck around
  53.      endlessly wondering from whence the next  GURU  or  screen  shattering
  54.      misunderstanding will arise???  
  55.  
  56.      I  agree that you lose flexibility when you go up one level but you do
  57.      gain development efficiency.  The applications  I  have  in  mind  are
  58.      scientific  applications  such  as  interactive  graphing and mapping.
  59.      Several years ago, I used a system called the  Graphics  Compatibility
  60.      System (GCS)  that  was  developed by the government.  That system was
  61.      not particularly fast but it certainly made development of  scientific
  62.      graphics applications  MUCH easier and faster.  The source code of GCS
  63.  
  64.  
  65.                                       -1-
  66.  
  67.  
  68.      17 Nov 1991                      GWIN            by Howard C. Anderson
  69.  
  70.  
  71.      (in FORTRAN) is available through the National  Technical  Information
  72.      Center. It is a very large system.  Trying to compile it and run it on 
  73.      an  Amiga  would probably allow you to relive some of the past glories
  74.      mentioned above.  Instead,  I  designed  a  system  with  capabilities
  75.      similar  to  GCS but with additional Amiga-specific features and wrote
  76.      this simple graphics system in the  C  language.    The  result  is  a
  77.      graphics system  that  I  refer  to  as  GWIN  (Graphic WINdow).  GWIN
  78.      includes many of the virtual windowing features that were part of  the
  79.      GCS  philosophy  and  also  includes and simplifies use of many of the
  80.      strictly Amiga features such as menus and requesters.  The  underlying
  81.      architecture   of  GWIN  has  much  in  common  with  most  high-level
  82.      two-dimensional graphics  systems.    "Fundamentals   of   Interactive
  83.      Graphics  Computer  Graphics",  the classic text by Foley and Van Dam,
  84.      describes well the  sort  of  mathematical  transformations,  clipping
  85.      algorithms, etc.  that are part of the GWIN system.  
  86.  
  87.      Over  the  years  there  have been many higher level graphics systems:
  88.      PLOT10, GCS, GKS, CORE, etc.  Most of them presumably  have  been  too
  89.      massive to  adapt  for  use  on the Amiga system.  I am unaware of any
  90.      high-level graphics system that provides the range of features on  the
  91.      Amiga system that is provided by GWIN.  
  92.  
  93.      The  goal of GWIN is to allow a person to write interactive scientific
  94.      graphics applications programs in C without having to master  all  the
  95.      complexities of the Amiga graphics system.  
  96.  
  97.      Here  is  a  program  that  draws  one straight line segment in a high
  98.      resolution interlaced window using GWIN and then waits for the user to 
  99.      press the left mouse button before exiting: 
  100.  
  101.      #include "gwin.user.h"
  102.          main()
  103.          {
  104.          float x,y;
  105.             USTART("high2",0.,100.,0.,100.);
  106.             umove(G,20.,20.);
  107.             udraw(G,50.,50.);
  108.             ugrin(G,&x,&y);
  109.             UEND();
  110.          }
  111.  
  112.      Ahhhh... Isn't that better???  
  113.  
  114.      (NOTE: USTART and UEND are macros contained in gwin.user.h.  This is a 
  115.      change from previous versions of GWIN. More  will  be  said  regarding
  116.      these  two  macros  in  the "ustart" and "uend" procedure descriptions
  117.      below.  Another change is the use of the  variable  "G"  in  the  GWIN
  118.      procedure calls.  I tried to avoid this but shared Amiga libraries are 
  119.      reentrant.   G is a pointer to something similar to a "Graphics Status
  120.      Area" in the X-window system.  If I had found a safe way  to  hide  it
  121.      using  operating  system  "hooks"  I  would have but I don't think any
  122.      provision for this was made readily available in the  Amiga  operating
  123.      system.  I could cheat on the operating system to do it but that would 
  124.      not be safe in the long run.) 
  125.  
  126.      Other example programs are provided in the GWIN EXAMPLES directory.  
  127.  
  128.  
  129.  
  130.  
  131.                                       -2-
  132.  
  133.  
  134.      17 Nov 1991                      GWIN            by Howard C. Anderson
  135.  
  136.  
  137.                             GWIN THEORY OF OPERATION
  138.  
  139.  
  140.  
  141.      FLOATING POINT 
  142.  
  143.      GWIN is  intrinsically  floating point.  Most of the parameters passed
  144.      to and from GWIN routines MUST BE FLOATING POINT. There are exceptions 
  145.      however so I have  provided  the  type  of  each  parameter  with  the
  146.      description of the calling sequence of each routine.  
  147.  
  148.  
  149.  
  150.      COORDINATE SYSTEM 
  151.  
  152.      Normal  mathematical  xy  coordinate  system  is assumed with larger x
  153.      values to the right of the screen and larger y values at  the  top  of
  154.      the screen.  (The machine manufacturers tend to put the small y values 
  155.      at  the  top  of  the  screen  because  that  is where the raster scan
  156.      starts.   This  is  an  unfortunate  accident  of   the   history   of
  157.      television.   If  they  had  started  the  raster at the bottom of the
  158.      screen and gone up instead of  vice-versa  it  would  have  been  much
  159.      nicer.   (Surely  you  don't REALLY want to work in quadrant IV - with
  160.      NEGATED Y values???) GWIN corrects for this  historical,  perpetuated,
  161.      accident.  
  162.  
  163.  
  164.  
  165.      STARTUP 
  166.  
  167.      Graphics operations  are  begun with a USTART macro call.  USTART will
  168.      allow you to open any size window you choose on a  screen  whose  type
  169.      you may choose.  Screen types are: 
  170.  
  171.      low1  - 320x200 pixel, low resolution, non-interlaced, 32 colors.
  172.      low2  - 320x400 pixel, low resolution, interlaced, 16 colors.
  173.      high1 - 640x200 pixel, high resolution, non-interlaced, 32 colors.
  174.      high2 - 640x400 pixel, high resolution, interlaced, 16 colors.
  175.      ham   - 320x200 pixel, hold and modify, [4096 colors].
  176.  
  177.      low1.backdrop - Same as low1 but active region fills screen.
  178.      low2.backdrop - Same as low2 but active region fills screen.
  179.      high1.backdrop - Same as high1 but active region fills screen.
  180.      high2.backdrop - Same as high2 but active region fills screen.
  181.      ham.backdrop - Same as ham but active region fills screen.
  182.  
  183.      NOTE: I have made changes to attempt to accomodate Europeans using PAL 
  184.      instead  of  NTSC  television  standards  so you should be able to use
  185.      larger y values than the ones listed above if I was successful.    See
  186.      "ustart" procedure description for details.  
  187.  
  188.  
  189.      ACTIVE REGION 
  190.  
  191.      When  you  open  a screen and window with USTART, the active region of
  192.      the Amiga window is everything inside the borders.  This full area  is
  193.      always  thought  of  as  running from 0.0 to 100.0 in both the x and y
  194.      directions.  
  195.  
  196.  
  197.                                       -3-
  198.  
  199.  
  200.      17 Nov 1991                      GWIN            by Howard C. Anderson
  201.  
  202.  
  203.  
  204.      You may use udarea to select some subset of this area  as  the  active
  205.      region.  udarea calls are always relative to the original 0.0 to 100.0 
  206.      bounds.  Drawing is always restricted to the active region by internal 
  207.      clipping  routines  unless you have turned internal clipping off using
  208.      uset("ncli").  (See "Fundamentals of Interactive  Computer  Graphics",
  209.      Foley  and  Van  Dam,  section  on  "Viewports"  if  you  need further
  210.      information.) 
  211.  
  212.  
  213.  
  214.      VIRTUAL WINDOWING 
  215.  
  216.      Virtual windowing is automatic.  The  uwindo  command  allows  you  to
  217.      change the  size of the virtual window.  The default virtual window is
  218.      from 0.0 to 100.0 in the x  direction  and  0.0  to  100.0  in  the  y
  219.      direction.  
  220.  
  221.      Whatever  is  in  the  virtual  window  is  expanded  or contracted as
  222.      necessary and mapped onto the active region  determined  with  udarea.
  223.      By changing  uwindo and redrawing, you can pan and zoom.  (Clearly, we
  224.      are  not  talking  real-time  pan  and  zoom  here  of  course.)  (See
  225.      "Fundamentals  of  Interactive  Computer Graphics", Foley and Van Dam,
  226.      section on "Windows and Clipping" if you need further information.) 
  227.  
  228.  
  229.  
  230.      ROTATION OF COORDINATES 
  231.  
  232.      The coordinate system may be rotated through an angle theta (value 0.0 
  233.      through 360.0) relative to any point in the virtual  coordinate  space
  234.      through use of the urotate call.  The point about which the coordinate 
  235.      space  is  rotated  is  ALWAYS  with respect to the ORIGINAL UNROTATED
  236.      COORDINATE SYSTEM. This point becomes the new origin,  (0,0),  of  the
  237.      new rotated  coordinate  system.    There is no way provided to rotate
  238.      Amiga text.  The position at which the  text  is  to  appear  will  be
  239.      rotated  and the text will begin at the new position but it will still
  240.      be horizontal like this line you are now reading.  
  241.  
  242.  
  243.  
  244.      DRAWING 
  245.  
  246.      Umove, udraw, ucrcle, urect, and  uplygn  are  the  primary  line  and
  247.      polygon drawing  tools.  Umove moves the beam to the specified virtual
  248.      point.  Udraw draws a line from the current virtual beam  position  to
  249.      the virtual  beam  position  given  in  the  udraw  call.  Clipping is
  250.      performed as necessary.  Urect draws a rectangle and  has  some  speed
  251.      advantages over  uplygn.    Uplygn  draws  a  polygon of the specified
  252.      number of sides within a circumscribing circle of radius  provided  in
  253.      the call.    The  optional  "fill"  switch  set  via a uset call cause
  254.      polygons or rectangles to be  filled  when  drawn  and  causes  umove,
  255.      udraw, udraw, udraw, ... umove sequences to be filled.  Setting "nofi" 
  256.      with  a uset call turns off the filling operation and closes and fills
  257.      immediately any udraw sequence that has not yet been closed by a umove 
  258.      call.  
  259.  
  260.  
  261.  
  262.  
  263.                                       -4-
  264.  
  265.  
  266.      17 Nov 1991                      GWIN            by Howard C. Anderson
  267.  
  268.  
  269.  
  270.      TEXT 
  271.  
  272.      Ufont establishes the font that will be used for subsequent uprint and 
  273.      uprnt1 calls.  Any font that you have on your system may be used.  The 
  274.      default is the standard Amiga default font  which  at  the  moment  is
  275.      Topaz.   Its  default  size  is  selected  by you with the Preferences
  276.      tool.  
  277.  
  278.      Uprint will print a line of text at the given location  in  accordance
  279.      with the uset options "inte", "real", and "text". Uprnt1 prints a line 
  280.      of  text  at  the  current beam location and allows you to set "inte",
  281.      "real", and "text" for the duration of the call.  
  282.  
  283.  
  284.  
  285.      COLOR 
  286.  
  287.      The current drawing color is established by a upset("colo",color) call 
  288.      where color is a real number between 0 and the maximum color  for  the
  289.      particular screen  type you are using.  (GWIN does a modulus operation
  290.      if you forget and exceed the maximum  color.)  The  "colo"  option  to
  291.      upset  sets the A pen and the O pen so that lines, fills, and outlines
  292.      are all set to the designated color.  The "bcol" option to upset  sets
  293.      the  B  pen  so  that  the  background  color  for  text may be set as
  294.      desired.  The "ccol" option to upset sets the color that will fill the 
  295.      screen when the uerase screen clearing call is issued.  
  296.  
  297.  
  298.  
  299.      CLIPPING 
  300.  
  301.      Line and  polygon  clipping  are  automatic.    These  are   sometimes
  302.      suppressed  if  the item being drawn such as a polygon or rectangle is
  303.      seen to fall completely  inside  the  virtual  boundaries.    You  may
  304.      suppress clipping for speed IF YOU ARE ABSOLUTELY CERTAIN THAT NONE OF 
  305.      THE  THINGS  YOU DRAW WILL FALL OUTSIDE OF THE CURRENT VIRTUAL WINDOW.
  306.      If you blow it, ANYTHING can happen - loss  of  screen  synch,  GURUs,
  307.      etc.  Clipping  is disabled by the "ncli" option of uset.  Clipping is
  308.      reenabled by the "clip" option of uset.  
  309.  
  310.  
  311.  
  312.      RECTANGLE INTERIOR ONLY FILL 
  313.  
  314.      If you have a rectangle whose color you wish to change but you do  not
  315.      wish to  change  the color of the bounding box, use uset("rint").  Use
  316.      uset("rext") to include the exterior bounding box if you wish.  
  317.  
  318.  
  319.  
  320.      GRAPHICS INPUT 
  321.  
  322.      ugrin, ugrinc, ugrinl, ugrina, and uigrina are provided.  
  323.  
  324.      Each of these responds to the  window  close  gadget  by  returning  a
  325.      non-zero value.   (Unless the uset option "nclo" is set for ugrinc and
  326.      ugrinl in which case the CLOSEWINDOW event is returned to you via  the
  327.  
  328.  
  329.                                       -5-
  330.  
  331.  
  332.      17 Nov 1991                      GWIN            by Howard C. Anderson
  333.  
  334.  
  335.      event parameter.) 
  336.  
  337.      NOTE:  THE  ABOVE IS A CHANGE FROM PREVIOUS VERSIONS OF GWIN. You MUST
  338.      monitor the return value and issue a UEND() and  an  exit(0)  whenever
  339.      the returned  value is non-zero.  This change was required because the
  340.      GWIN library is opened from your program when  you  issue  the  USTART
  341.      procedure  call and the only way I can get the library closed properly
  342.      is to do it under control of  your  program.    The  examples  in  the
  343.      example directory all reflect any necessary code changes.  
  344.  
  345.      NOTE:  ANOTHER CHANGE FROM PREVIOUS VERSIONS OF GWIN is that return of
  346.      the event and keystroke for ugrinl, ugrinc, ugrina,  and  uigrina,  is
  347.      now handled  via  a  structure.   This was forced on me by the LATTICE
  348.      compiler.  It uses index register a4 as a base register for the object 
  349.      code.  The way I handle menu selections is to call  the  user-selected
  350.      function via  a function pointer.  Ugrinl, ugrinc, ugrina, and uigrina
  351.      are called using pragmas.  Pragmas save and restore registers.  When I 
  352.      call your menu function, the registers have  not  yet  been  restored.
  353.      When I used a4, LATTICE object code blew up.  I have restricted my use 
  354.      of registers  to  a0,  a1,  a2,  and  a3  now.  All examples have been
  355.      updated to reflect these changes.  
  356.  
  357.      Ugrin (GRaphic INput) returns the x and y location of the cursor  when
  358.      the left mouse button is pressed.  
  359.  
  360.      Ugrinc  (GRaphic  INput Character) returns the x and y location of the
  361.      cursor, the event type, and the keyboard character that was pressed if 
  362.      the  event  type  was  "VANILLAKEY".  Event  types  may  be   one   of
  363.      MOUSEBUTTONS,   VANILLAKEY,  CLOSEWINDOW  (only  if  you  have  called
  364.      uset("nclo")), or REFRESHWINDOW. If the event type was "MOUSEBUTTONS", 
  365.      the key returned is an "a" if it was a left  mouse  key  "down"  event
  366.      code and an "A" if it was a left mouse key "up" event code.  MOUSEMOVE 
  367.      events are NOT monitored by ugrinc.  
  368.  
  369.      Ugrinl  (GRaphic  INput  Locator)  returns the x and y location of the
  370.      cursor, the event type, and the keyboard character that was pressed if 
  371.      the event type was "VANILLAKEY". If the event type was "MOUSEBUTTONS", 
  372.      the key returned is an "a" if it was a mouse key "down" event code and 
  373.      an "A" if it was a mouse key "up" event code.   MOUSEMOVE  events  ARE
  374.      monitored  by  ugrinl and you are notified immediately of the last one
  375.      in the current message stack.  
  376.  
  377.      Ugrina (GRaphic INput All) is identical with ugrinl except it  returns
  378.      even if  no  event  occurred.  This allows you to continuously monitor
  379.      user activity while in a processing loop.  You can use this  to  allow
  380.      the  user  to  interrupt  a  process  if he desires (maybe he wants to
  381.      change his mind regarding the 30 hour Mandelbrot drawing...) 
  382.  
  383.      Uigrina (Integer GRaphic INput All) is identical with  uigrina  except
  384.      that   it   returns  integer  mouse  coordinates  with  no  coordinate
  385.      transformations performed.    This  allows  greatest  speed  since  it
  386.      bypasses all  floating  point  operations.    If  you  need speed, use
  387.      uigrina.  Coordinates returned are normal Amiga coordinates  with  the
  388.      origin at  the  top left corner of the screen.  (For a high-resolution
  389.      screen, 640x400 pixels, the x coordinate will be an integer from 0  to
  390.      639 and the y coordinate will be an integer from 0 to 399.) 
  391.  
  392.  
  393.  
  394.  
  395.                                       -6-
  396.  
  397.  
  398.      17 Nov 1991                      GWIN            by Howard C. Anderson
  399.  
  400.  
  401.  
  402.      EASY AMIGA MENUS 
  403.  
  404.      With  a  one  line  call  (uamenu), you can set up each menu item of a
  405.      hierarchical menu structure.  GWIN creates all  necessary  structures,
  406.      allocates all  necessary  space.    You pass a "function pointer" that
  407.      tells which of your functions will be called  when  the  user  selects
  408.      that menu item.  
  409.  
  410.  
  411.  
  412.  
  413.      EASY AMIGA YES/NO REQUESTER 
  414.  
  415.      With  a  one  line  call  (uyorn),  you  can  put  up an AMIGA boolean
  416.      requester containing your text.  When the user makes his  choice,  you
  417.      will receive a TRUE/FALSE return code.  
  418.  
  419.  
  420.  
  421.      EASY AMIGA STRING REQUESTER 
  422.  
  423.      With  a  one  line  call  (ugetstring), you can put up an amiga string
  424.      requester containing your prompt text.  The requester  will  wait  for
  425.      the user  to enter a text string.  The requester exits when a carriage
  426.      return is received.  
  427.  
  428.  
  429.  
  430.      SCREEN DUMP TO PRINTER 
  431.  
  432.      If you have an Epson LQ series printer, you can dump the screen  image
  433.      to the printer using uprscr.  
  434.  
  435.  
  436.  
  437.      ABORT 
  438.  
  439.      ANOTHER  CHANGE.  Abort  handling  via  an AMIGA library does not make
  440.      sense.  I have removed the abort handler.  If you catch your own abort 
  441.      signals, be sure to call UEND() if USTART has been issued.  
  442.  
  443.  
  444.      USER CLEANUP HANDLER 
  445.  
  446.      The routine usetcleanup allows you to pass a function pointer to  GWIN
  447.      that points  to  your  own  cleanup  routine.    When  GWIN exits, for
  448.      whatever reason, if you specified a cleanup routine, control  will  be
  449.      passed  to  your  cleanup routine after GWIN completes deallocation of
  450.      its memory allocations, release  of  its  libraries,  etc.    In  your
  451.      cleanup  routine,  you  may  then  release  any  storage  you may have
  452.      allocated, close any files, etc.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.                                       -7-
  462.  
  463.  
  464.      17 Nov 1991                      GWIN            by Howard C. Anderson
  465.  
  466.  
  467.                                     EXAMPLES
  468.  
  469.      Examples of the use of GWIN routines are located in the  gwin/examples
  470.      directory.   Execute these examples and study their source code to see
  471.      how to use GWIN calls.  
  472.  
  473.      One good thing about using an AMIGA shared library is that the  object
  474.      code storage requirements are greatly reduced.  Object code for all of 
  475.      the examples is now able to reside on the disk.  
  476.  
  477.      The examples and a brief description of each are as follows: 
  478.  
  479.           clipdemo 
  480.  
  481.                Demonstrates setup of a GWIN clipping window within an Amiga 
  482.                window.  
  483.  
  484.  
  485.           colormap2 
  486.  
  487.                Demonstrates changing  the  colormap.  Place cursor inside a
  488.                triangle, depress left mouse button and move cursor  around.
  489.                The  points  of  the  triangles correspond to Red, Green and
  490.                Blue. Distance from the  center  determines  how  much  Red,
  491.                Green or Blue.  
  492.  
  493.  
  494.           placeobject 
  495.  
  496.                Demonstrates  moving  and  placing  a  rectangle  of various
  497.                colors.  
  498.  
  499.  
  500.  
  501.           rubberbandline 
  502.  
  503.                Demonstrates a rubberband line.  Simple demo  intended  only
  504.                to illustrate how a rubberband line is generated.  
  505.  
  506.  
  507.  
  508.           text 
  509.  
  510.                Demonstrates  use of font selection and various text display
  511.                options.  
  512.  
  513.  
  514.  
  515.           graph 
  516.  
  517.                Accepts a list of numbers either from the keyboard  or  from
  518.                standard input.      The   numbers   are  assumed  to  be  Y
  519.                coordinates.   Integer  X  coordinates   are   automatically
  520.                assigned.  A  graph  is drawn.  Menu options allow switching
  521.                between line graph and bar graph modes.  If you place a list 
  522.                of numbers in a file (say  file1)  then  issue  the  command
  523.                "graph <file1", the numbers will be graphed.  
  524.  
  525.  
  526.  
  527.                                       -8-
  528.  
  529.  
  530.      17 Nov 1991                      GWIN            by Howard C. Anderson
  531.  
  532.  
  533.  
  534.  
  535.           request 
  536.  
  537.                Shows  how  to  use  a  requester  to  ask the user a yes/no
  538.                question.  
  539.  
  540.  
  541.  
  542.           screentypes 
  543.  
  544.                Demonstrates all 10 types of screens supported by GWIN.  
  545.  
  546.  
  547.  
  548.           three-d 
  549.  
  550.                Allows construction of three-dimensional figures.  You would 
  551.                need red/blue glasses to see  the  three-dimensional  effect
  552.                however.  
  553.  
  554.  
  555.  
  556.           menu 
  557.  
  558.                Demonstrates how to build and use menus in GWIN.  
  559.  
  560.  
  561.  
  562.           rubberbandbox 
  563.  
  564.                Demonstrates building boxes using a rubberband box.  
  565.  
  566.  
  567.  
  568.           spiceplot 
  569.  
  570.                For you Electrical Engineers who have access to some version 
  571.                of the "SPICE" program.  Spiceplot reads a SPICE output file 
  572.                from standard input, i.e., type: "spiceplot <spiceoutput" to 
  573.                see it  plot curves contained in the spiceoutput file.  Note
  574.                the format of the data in the spiceoutput file.    Spiceplot
  575.                is looking  for  the  lists  of node data.  Depress the left
  576.                mouse button and hold, drag, and release.  A rubberband  box
  577.                will  have appeared and the selected region will be expanded
  578.                to fill the screen.  Use the menu to restore the  curves  to
  579.                their original  scale.  As the cursor moves, the coordinates
  580.                are displayed.  
  581.  
  582.  
  583.  
  584.           speedy 
  585.  
  586.                Demonstrates how Amiga calls can be used within a screen and 
  587.                window initiated by GWIN. GWIN saved all of  the  effort  of
  588.                bringing  up a special screen and window while allowing full
  589.                use of all standard Amiga graphics functions.  Speedy  makes
  590.                use  of  direct Amiga graphics function calls to provide the
  591.  
  592.  
  593.                                       -9-
  594.  
  595.  
  596.      17 Nov 1991                      GWIN            by Howard C. Anderson
  597.  
  598.  
  599.                fastest possible graphics operations.  This means  that  for
  600.                special  purposes,  it  is  possible  to bypass the floating
  601.                point world/screen coordinate  transformations  that  are  a
  602.                part of  normal  GWIN  operation.    The function uigrina is
  603.                provided to allow  transformationless  return  of  x  and  y
  604.                cursor coordinates for greatest possible speed.  The slowest 
  605.                thing  in  "speedy" is perhaps the call to the random number
  606.                generator, "ran".  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.                                       -10-
  660.  
  661.  
  662.      17 Nov 1991                      GWIN            by Howard C. Anderson
  663.  
  664.  
  665.                                    USING GWIN
  666.  
  667.      I am using the MANX C compiler.  When I began this project I foolishly 
  668.      assumed that compilers on the Amiga produced compatible object modules 
  669.      as is done on Sun, Apollo, Multics, IBM,  etc.,  computer  systems  so
  670.      that  they  could  be  linked together with object modules produced by
  671.      other compilers.  Alas, Amiga does  not  have  a  standard  linker  so
  672.      Lattice and Manx each apparently wrote their own and defined their own 
  673.      standards  so  Lattice  C  object modules cannot be linked with MANX C
  674.      object modules.  
  675.  
  676.      I also did not expect the  compiled  objects  to  become  obsolete  so
  677.      quickly.   You cannot link MANX release 5.0 produced object files with
  678.      MANX release 3.6 object files.  I  released  version  1.1  of  GIN  to
  679.      provide  release  5.0  compatible  graphics object files that could be
  680.      used to create GWIN applications under the release 5.0 version of  the
  681.      MANX AZTEC  C  compiler.    Similarly, Lattice released Version 5.1 of
  682.      their compiler which produces object modules that, I have  been  told,
  683.      will  not  link  with object modules produced by version 5.0. (I would
  684.      have thought that non-upward compatibility  of  object  modules  would
  685.      have  rated  a  major  number  change  like release 6.0 or something.)
  686.      Reacting continually to all this vendor-induced recurrent obsolescence 
  687.      of object libraries seemed like a losing proposition.  
  688.  
  689.      I had investigated turning GWIN into an AMIGA  library  several  times
  690.      but  rejected  it because of the horrendous complexity associated with
  691.      making an AMIGA library.  Finally the answer appeared in premier issue 
  692.      of "The AmigaWorld  Tech  Journal"  in  an  article  entitled  "Shared
  693.      Libraries  for  the  Lazy"  by Jim Fiore. This article and the LibTool
  694.      program on the disk reduced the complexity to a level  just  below  my
  695.      pain threshold.  
  696.  
  697.      It was still a lot of work and I'm not entirely happy with some of the 
  698.      complexity I had to add back into the GWIN system but I think over all 
  699.      the trade-off  is  good.  Since GWIN is now a library, I won't have to
  700.      worry about all the changes that the MANX  and  LATTICE  people  make.
  701.      You  LATTICE  people  are  now  supported  (I  do  not  have a LATTICE
  702.      compiler) properly.  The down side is that you have  to  add  the  "G"
  703.      parameter  to  the  procedure  calls  and you have to check the return
  704.      codes from some of the routines to see what errors occurred within the 
  705.      GWIN library routines if something  goes  wrong.    (Libraries  cannot
  706.      communicate  directly  to  the screen so I cannot print error messages
  707.      from within the GWIN library.) 
  708.  
  709.  
  710.      MANX NOTES 
  711.  
  712.      I used version 5.0e of the MANX AZTEC compiler to build the library.  
  713.  
  714.      To use the GWIN library,  you  must  write  a  C  program  that  calls
  715.      procedures  in  the  GWIN  library,  and  compile  it  with  the  Manx
  716.      compiler.  (The makefile in the  gwin/examples  directory  shows  many
  717.      examples  of  compile  and  link  statements  that  accomplish what is
  718.      necessary.  
  719.  
  720.      I have simplified the problem of options regarding code size, floating 
  721.      point type, etc.  The GWIN library uses the  "Motorola  Fast  Floating
  722.      Point" format  and "large code" and "large data".  This seems to solve
  723.  
  724.  
  725.                                       -11-
  726.  
  727.  
  728.      17 Nov 1991                      GWIN            by Howard C. Anderson
  729.  
  730.  
  731.      all sorts of problems and reduces my maintenance problem.  
  732.  
  733.      Assume you have a program named "prog.c" that calls GWIN routines such 
  734.      as "ustart", "umove", etc.  Then to compile and  link  it,  you  would
  735.      execute the statements: 
  736.  
  737.              cc -mc -md -ff prog.c 
  738.  
  739.  
  740.      This will  result  in an object segment called "prog.o".  To link GWIN
  741.      in with your object segment, issue the link command: 
  742.  
  743.           ln prog.o -lmfl -lcl 
  744.  
  745.      This will result in the executable graphics module "prog".  
  746.  
  747.      When "prog" runs, it will look for the library "GWIN.library"  in  the
  748.      directory libs:.    You must copy the file "GWIN.library" to the libs:
  749.      directory to run GWIN applications because that is  where  the  system
  750.      looks to  load  shared  library  files.    The  GWIN shared library is
  751.      automatically loaded by the system when the USTART macro is executed.  
  752.  
  753.  
  754.      LATTICE NOTES 
  755.  
  756.      Similar to above.  You should copy the file  "gwin.lattice.user.h"  in
  757.      the examples directory to "gwin.user.h". This gets the correct LATTICE 
  758.      pragmas.   Also  copy  the file Makefile.lattice to the file Makefile.
  759.      You will then be able to use "make" to compile  the  example  programs
  760.      with the   LATTICE   compiler.      For  other  programs,  sumply  use
  761.      LATTICE-specific compilation and linking commands similar to the  ones
  762.      used in Makefile.lattice. Use large code, large data, and the Motorola 
  763.      Fast Floating  Point format.  Be sure to place GWIN.library in "libs:"
  764.      before running any program that calls GWIN procedures.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.                                       -12-
  792.  
  793.  
  794.      17 Nov 1991                      GWIN            by Howard C. Anderson
  795.  
  796.  
  797.                                 PROCEDURE CALLS
  798.  
  799.      USTART(mode,xmin,xmax,ymin,ymax);
  800.      char mode[255];
  801.      float x1,x2,y1,y2;
  802.  
  803.           Macro that you should use instead of ustart below.    This  macro
  804.           open  up  required  libraries,  defines  the G variable, opens up
  805.           screens and windows and sets up everything ready for use of other 
  806.           GWIN procedure  calls.    You  must  include  the  include   file
  807.           "gwin.user.h"  in  your  program because that is where the USTART
  808.           macro is defined and also where the G parameter is defined.   The
  809.           USTART  parameters  are the same as those defined in ustart below
  810.           since they are passed directly to ustart.  
  811.  
  812.  
  813.  
  814.      struct G_user_subset *ustart(mode,xmin,xmax,ymin,ymax);
  815.      char mode[255];
  816.      float x1,x2,y1,y2;
  817.  
  818.           You should use the USTART macro above instead of ustart  in  most
  819.           cases.  USTART  calls  ustart.    Ustart  returns  a pointer to a
  820.           G_user_subset structure that is used in subsequent GWIN procedure 
  821.           calls.  This structure is defined in gwin.user.h which should  be
  822.           included  in  each  application  program that you write that uses
  823.           GWIN procedures.  Creates a screen and a window within the screen 
  824.           within which all graphics operations will occur.  
  825.  
  826.           Mode is "low1", "low2", "high1", "high2",  or  "ham"  or  any  of
  827.           these with a ".backdrop" appended.  
  828.  
  829.           low1  - 320x200 pixel, low resolution, non-interlaced, 32 colors.
  830.           low2  - 320x400 pixel, low resolution, interlaced, 16 colors.
  831.           high1 - 640x200 pixel, high resolution, non-interlaced, 32 colors.
  832.           high2 - 640x400 pixel, high resolution, interlaced, 16 colors.
  833.           ham   - 320x200 pixel, hold and modify, [4096 colors].
  834.  
  835.           low1.backdrop - Same as low1 but active region fills screen.
  836.           low2.backdrop - Same as low2 but active region fills screen.
  837.           high1.backdrop - Same as high1 but active region fills screen.
  838.           high2.backdrop - Same as high2 but active region fills screen.
  839.           ham.backdrop - Same as ham but active region fills screen.
  840.  
  841.  
  842.           xmin determines the window x-pixel minimum value on the screen.
  843.           xmax determines the window x-pixel maximum value on the screen.
  844.           ymin determines the window y-pixel minimum value on the screen.
  845.           ymax determines the window y-pixel maximum value on the screen.
  846.  
  847.           EXAMPLES: 
  848.  
  849.           ustart("high2", 0.0, 640.0, 0.0, 400.0); 
  850.  
  851.           will create an Amiga window that fills the screen.  
  852.  
  853.  
  854.           ustart("high1", 0.0, 320.0, 0.0, 100.0); 
  855.  
  856.  
  857.                                       -13-
  858.  
  859.  
  860.      17 Nov 1991                      GWIN            by Howard C. Anderson
  861.  
  862.  
  863.  
  864.           will  create an Amiga window that fills the lower left quarter of
  865.           the screen.  
  866.  
  867.  
  868.           ustart("high2.backdrop", 0.0, 640.0, 0.0, 400.0); 
  869.  
  870.           will create a Amiga window that fills  the  entire  screen.    No
  871.           borders will be shown.  You can draw on the entire screen.  
  872.  
  873.           What  I  attempted  to do for you PAL users in Europe is to allow
  874.           you to enter ymax values outside of the above ranges.  I received 
  875.           a letter from Jerome Santini in France indicating that  I  should
  876.           check   GfxBase->NormalDisplayRows   and   use   either   it   or
  877.           GfxBase->NormalDisplayRows/2 for the maximum ymax  value.    This
  878.           data  is  undocumented in the "Amiga ROM Kernal Reference Manual:
  879.           Libraries and Devices" that was printed by Addison Wesley in  the
  880.           USA  in  1986.  My  dealer  didn't  have  anything  newer or more
  881.           complete.  I used the MANX debugger to  look  at  the  value  and
  882.           found it  was  always  200  here  on my machine.  If the value in
  883.           Europe is 256 then I should multiply by two rather than divide by 
  884.           two.  If the value in Europe is 512, I should do as Jerome  says.
  885.           But  if  it is 512, then I would expect the value here in the USA
  886.           to be 400 which it is not.  The only safe thing to do, to be sure 
  887.           you  COULD  get   higher   values,   was   to   use   the   value
  888.           GfxBase->NormalDisplayRows    for    the   maximum   ymax   value
  889.           corresponding to low-resolution screens  and  to  use  the  value
  890.           2*GfxBase->NormalDisplayRows   for   the   maximum   ymax   value
  891.           corresponding to  high-resolution  displays.    This  leaves  the
  892.           maximum  values  unchanged  from  the above limits in the USA and
  893.           hopefully accomodates you PAL users in  Europe.  Unfortunately  I
  894.           have no way  to  test this here.  It should work.  The only thing
  895.           that I would expect to go wrong is that  you  might  be  able  to
  896.           specify  a screen size that would be too large in the y direction
  897.           which would probably cause a problem.  Write to  me  if  you  PAL
  898.           users can't  get  a full size screen now.  The following examples
  899.           should now be valid in Europe: 
  900.  
  901.           ustart("low1", 0.0, 320.0, 0.0, 256.0); 
  902.  
  903.           ustart("high2", 0.0, 640.0, 0.0, 512.0); 
  904.  
  905.           ustart("high2.backdrop", 0.0, 640.0, 0.0, 512.0); 
  906.  
  907.  
  908.  
  909.      UEND(); 
  910.  
  911.           Macro that stops everything.  Call  this  when  you  are  through
  912.           doing graphics.  UEND closes the window, the screen, the graphics 
  913.           libraries, frees storage allocated by GWIN, etc.  Be sure to call 
  914.           this routine before exiting your application program.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.                                       -14-
  924.  
  925.  
  926.      17 Nov 1991                      GWIN            by Howard C. Anderson
  927.  
  928.  
  929.      uend(G); 
  930.  
  931.           You  should  use  UEND  above  instead of uend for most purposes.
  932.           UEND calls uend which actually closes  things  down.    The  UEND
  933.           macro also closes the GWIN library.  
  934.  
  935.  
  936.  
  937.  
  938.      udarea(G,xmin,xmax,ymin,ymax);
  939.      float xmin,xmax,ymin,ymax;
  940.  
  941.           Default  active  region  boundaries if uwindo is not called: Full
  942.           active window region selected by USTART.  
  943.  
  944.           Determines the active region of the full  display  region.    The
  945.           minimum and maximum values are expressed as percents of the x and 
  946.           y full  screen  limits.    Udarea may be called at any time after
  947.           USTART and may be used to  define  the  active  sub-area  of  the
  948.           screen.   All input values to this procedure must be in the range
  949.           [0.0,100.0]. The xmin value must be less than the xmax value  and
  950.           the ymin value must be less than the ymax value.  
  951.  
  952.           EXAMPLES: 
  953.  
  954.           udarea(G,0.0,100.0,0.0,100.0); 
  955.  
  956.           Allows use of the entire graphics region of the window.  
  957.  
  958.           udarea(G,10.,20.,10.,20.); 
  959.  
  960.           Allows  use  of  a  square sub-region of the full graphics region
  961.           defined by USTART. All graphics operations are clipped and scaled 
  962.           to  this   region   unless   you   turned   clipping   off   with
  963.           uset(G,"ncli").  
  964.  
  965.  
  966.  
  967.  
  968.      uwindo(G,xmin,xmax,ymin,ymax);
  969.      float xmin,xmax,ymin,ymax;
  970.  
  971.           Default   virtual   window   boundaries  if  uwindo  not  called:
  972.           [0.0,100.0] x and [0.0,100.0] y.  
  973.  
  974.           Determines the virtual window boundaries.  Everything inside  the
  975.           bounds  will be mapped and plotted into the current active region
  976.           of the screen as determined by USTART or udarea.  Any real values 
  977.           may be used for the values input to this procedure.  Xmin must be 
  978.           less than xmax and ymin must be less than ymax.   Calls  to  this
  979.           procedure  allow  pan  and  zoom  operations  (not like real-time
  980.           smooth pan and zoom however.   You  must  clear  the  screen  and
  981.           redraw everything to see the panned or zoomed image.) 
  982.  
  983.           EXAMPLES: 
  984.  
  985.           uwindo(G,0.,100.,0.,100.); 
  986.  
  987.  
  988.  
  989.                                       -15-
  990.  
  991.  
  992.      17 Nov 1991                      GWIN            by Howard C. Anderson
  993.  
  994.  
  995.           Sets  the  virtual  window  to  [0.0,100.0]  x and [0.0,100.0] y.
  996.           Every part of your image that has coordinates falling  into  this
  997.           square will be mapped and plotted to the active graphics region.  
  998.  
  999.           uwindo(G,-50.,150.,-50.,150.); 
  1000.  
  1001.           Backs  away  or  zooms  out  from  the  previous  window setting.
  1002.           Everything that was drawn with the previous window setting  would
  1003.           be  drawn  twice  as  small in the center of the screen with this
  1004.           window setting.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.      umove(G,x,y);
  1010.      float x,y;
  1011.  
  1012.           Moves the beam (invisibly) to the  specified  virtual  coordinate
  1013.           point  (with  respect  to the virtual window set up in uwindo.) X
  1014.           and y may assume any legal floating point values.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.      udraw(G,x,y);
  1020.      float x,y;
  1021.  
  1022.           Draws a line using  the  current  color  from  the  current  beam
  1023.           position  to  the new beam position designated in the udraw call.
  1024.           Updates the current beam position to the new position.  X  and  y
  1025.           are  floating  point  numbers and are with respect to the virtual
  1026.           window set up in uwindo.  They  may  assume  any  legal  floating
  1027.           point values.    The  resulting line will be clipped as necessary
  1028.           unless you turned clipping off with uset(G,"ncli").  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.      uwhere(G,&x,&y);
  1034.      float x,y;
  1035.  
  1036.           Returns the virtual coordinates of  the  current  beam  position.
  1037.           Note that this procedure uses ADDRESSES of the variables.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.      urect(G,x1,y1,x2,y2);
  1043.      float x1,y1,x2,y2;
  1044.  
  1045.           Draws  a  rectangle  outline  in the current color whose opposite
  1046.           corner points are (x1,y1) and (x2,y2). Fills the  rectangle  with
  1047.           the current  color  if the uset "fill" option is in effect.  This
  1048.           routine is much faster than calling  a  four-sided  polygon  with
  1049.           uplygn.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.                                       -16-
  1056.  
  1057.  
  1058.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1059.  
  1060.  
  1061.  
  1062.      uplygn(G,x,y,n,r);
  1063.      float x,y,n,r;
  1064.  
  1065.           Draws a regular n-sided polygon whose circumscribing circle is of 
  1066.           radius "r" and whose center is at (x,y). Fills the polygon if the 
  1067.           uset "fill"  option  is in effect.  Current color (previously set
  1068.           by the upset "colo" option) is applied.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.      ucrcle(G,x,y,r);
  1074.      float x,y,r;
  1075.  
  1076.           Draws a circle of radius "r" centered at (x,y).  Uses  the  Amiga
  1077.           Ellipse  or  AreaEllipse  routine  unless  the circle exceeds the
  1078.           bounds of the viewing area.  When  this  occurs,  the  circle  is
  1079.           merely a  clipped  30  sided  polygon.    If  you  need  a higher
  1080.           resolution circle in this case, call uplygn with more sides.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.      uoutln(G); 
  1086.  
  1087.           Draws a border around the current active graphics region  in  the
  1088.           current color.    If  the uset "fill" option is on, the region is
  1089.           filled with the current color.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.      uerase(G); 
  1095.  
  1096.           Erases the current active graphics region as defined  by  udarea.
  1097.           The  region  is  filled with the "ccol" or "clear color" that was
  1098.           set with upset.  (The default is black.) 
  1099.  
  1100.  
  1101.  
  1102.  
  1103.      uadjust(G,x,y,&xadj,&yadj);
  1104.      float x,y,xadj,yadj;
  1105.  
  1106.           This converts the coordinate (x,y) to  display  coordinates  then
  1107.           converts  the  display  coordinates  back  to our current virtual
  1108.           coordinates and provides them to you as  (xadj,yadj).  Since  the
  1109.           display  coordinates are discrete and the virtual coordinates are
  1110.           not, there are times when you need to know what  the  mapping  is
  1111.           doing with  your  coordinates.    This  allows  you  to  "adjust"
  1112.           coordinates to the discrete coordinate space.  An  example  would
  1113.           be if you wanted two lines side by side and didn't want to try to 
  1114.           calculate  the  mapping  from  your  virtual  coordinates  to the
  1115.           display's discrete coordinates.  Uadjust can be  used  to  figure
  1116.           out  the  mapping  since it "adjusts" your virtual coordinates to
  1117.           the virtual equivalent of the nearest discrete point  in  display
  1118.           space.  
  1119.  
  1120.  
  1121.                                       -17-
  1122.  
  1123.  
  1124.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.      urotate(G,x,y,theta);
  1132.      float x,y,theta;
  1133.  
  1134.           Rotates  the  virtual  coordinate  system  through an angle theta
  1135.           (value 0.0 through 360.0) relative to  the  point  (x,y)  in  the
  1136.           virtual coordinate  space.    (x,y) is ALWAYS with respect to the
  1137.           ORIGINAL UNROTATED COORDINATE  SYSTEM.  The  origin  of  the  new
  1138.           coordinate  system  (0,0)  is  located  at  (x,y) of the original
  1139.           unrotated coordinate system.  There is no way provided to  rotate
  1140.           Amiga text.   The position at which the text is to appear will be
  1141.           rotated and the text will begin at the new position but  it  will
  1142.           still be horizontal like this line you are reading.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.      ugrin(G,&x,&y);
  1148.      float x, y;
  1149.  
  1150.           Graphic  input  routine for responding to MOUSEBUTTONS. When this
  1151.           procedure is called, your application waits for the user to press 
  1152.           the left mouse button.  When  he  does,  ugrin  returns  to  your
  1153.           program with the virtual coordinates of the point selected by the 
  1154.           user.  Use this for selecting things with the mouse button.  Also 
  1155.           use  this if you want the display to pause long enough for you to
  1156.           see what you have drawn!  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.      ugrinc(G,&x,&y,&uuev);
  1162.      float x, y;
  1163.      struct uuevent uuev;
  1164.  
  1165.           Graphic  input  routine  for  responding  to   MOUSEBUTTONS   and
  1166.           VANILLAKEY.   Ugrinc  returns the x and y location of the cursor,
  1167.           the  event  type  (uuev.event),  and   the   keyboard   character
  1168.           (uuev.key)  that  was pressed if the event type was "VANILLAKEY".
  1169.           If the event type was "MOUSEBUTTONS", the uuev.key returned is an 
  1170.           "a" if it was a mouse key "down" event code and an "A" if it  was
  1171.           a mouse  key "up" event code.  MOUSEMOVE events are NOT monitored
  1172.           by ugrinc.  
  1173.  
  1174.           NOTE: Uuev is defined and allocated in gwin.user.h.  Creation  of
  1175.           the  uuevent  structure  was necessary because of a limitation of
  1176.           the LATTICE compiler.  I would have preferred to have a call that 
  1177.           looked like this: ugrinc(G,&x,&y,&event,&keystroke).  
  1178.  
  1179.           Note that  the  definition  of  the  variables  MOUSEBUTTONS  and
  1180.           VANILLAKEY     reside     in     the     Amiga    include    file
  1181.           "intuition/intuition.h" and this file should be included  if  you
  1182.           wish to  check  the  EVENT for these types.  (For what its worth,
  1183.           MOUSEBUTTONS  is  defined  as  "8",  VANILLAKEY  is  defined   as
  1184.           "0x00200000L".) 
  1185.  
  1186.  
  1187.                                       -18-
  1188.  
  1189.  
  1190.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1191.  
  1192.  
  1193.  
  1194.           Ugrinc  also  informs  you of the "WINDOWCLOSE" event if the uset
  1195.           option "nclo" is in effect.    (If  its  opposite,  "clos",  (the
  1196.           default)  is  in  effect,  the  program  closes  everything  down
  1197.           automatically and exits.) 
  1198.  
  1199.           Ugrinc also informs you of "REFRESHWINDOW" events.  If  the  user
  1200.           resizes the  window, the display is destroyed.  You should redraw
  1201.           the entire display upon receiving this event.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.      ugrinl(G,&x,&y,&uuev);
  1207.      float x, y;
  1208.      struct uuevent uuev;
  1209.  
  1210.  
  1211.           Same  as  ugrinc  above  except  ugrinl  also  reports  MOUSEMOVE
  1212.           (locator) events.    If  the  user  moves  the  mouse,  the (x,y)
  1213.           coordinate of the current mouse  position  in  virtual  space  is
  1214.           provided to  you.    This is useful for making running coordinate
  1215.           displays on the  screen.    (I  have  been  doing  speech  signal
  1216.           processing  and  find  it useful for displaying microseconds from
  1217.           the beginning of a segment of speech as I move the cursor  within
  1218.           the waveform.   The microsecond display updates in real-time as I
  1219.           move the cursor.) Now not EVERY MOUSEMOVE event is provided - you 
  1220.           wouldn't have time to respond to them all  -  but  the  last  one
  1221.           reported in  a series is reported to you.  It provides all of the
  1222.           ones that you could hope to use.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.      ugrina(G,&x,&y,&uuev);
  1228.      float x, y;
  1229.      struct uuevent uuev;
  1230.  
  1231.           Same as ugrinl except that ugrina does not enter  a  wait  state.
  1232.           Ugrinc returns immediately with whatever events were generated by 
  1233.           the user  if  any.  Ugrina can be used within processing loops to
  1234.           give the user the option to abort a 5 hour Mandelbrot drawing for 
  1235.           example.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.      uigrina(G,&ix,&iy,&uuev);
  1241.      int ix, iy;
  1242.      struct uuevent uuev;
  1243.  
  1244.           Same as ugrina except that uigrina does  not  make  a  coordinate
  1245.           transformation  of  the  returned  ix,  and  iy cursor coordinate
  1246.           data.   They  are  returned  as  integers  that  are  the  cursor
  1247.           coordinate   position  data  normally  reported  by  Amiga.  This
  1248.           increases the speed with which cursor tracking can occur.    This
  1249.           is  useful  if  you are calling Amiga graphics functions directly
  1250.           for speed.  
  1251.  
  1252.  
  1253.                                       -19-
  1254.  
  1255.  
  1256.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.      ufont(G,name,size);
  1264.      char name[255];
  1265.      float size;
  1266.  
  1267.           Sets the current font and font size that will be used  by  uprint
  1268.           and uprnt1.   FONTNAME may be the name of a font in the directory
  1269.           "sys:fonts" that you wish to use or it may be the full path  name
  1270.           of a font on any disk you have mounted.  An example of the former 
  1271.           would be  ufont(G,"topaz",11.0).   An example of the latter would
  1272.           be 
  1273.  
  1274.           ufont(G, "df1:SlavicFonts/cyrillic/moskva.font", 11.0 ); 
  1275.  
  1276.           from Fish disk 202. You can use any font that is in  Amiga  form.
  1277.           Many fonts are available on the Fish disks for example.  
  1278.  
  1279.           GWIN searches  the  sys:fonts  directory first.  If the requested
  1280.           font is not  found,  GWIN  then  searches  the  disks.    If  the
  1281.           requested  font  is  still  not found, GWIN blinks the screen and
  1282.           writes an error message to the window in which you  started  your
  1283.           application.  
  1284.  
  1285.           Fonts provided by Amiga are in "sys:fonts".  Available font sizes 
  1286.           can  be obtained by listing the directory of the same name as the
  1287.           font.  For example allowable sizes for the "ruby" font are  12.0,
  1288.           15.0,  and  8.0  as  can  be  seen  when  you  list the directory
  1289.           sys:fonts/ruby.  The numbers that are printed are  the  allowable
  1290.           font sizes.  
  1291.  
  1292.           For example, the ones on my system are: 
  1293.  
  1294.           FONT                           AVAILABLE SIZES
  1295.  
  1296.           sys:fonts/curtools             16.0
  1297.           sys:fonts/frettools            10.0
  1298.           sys:fonts/ruby                 12.0, 15.0, 8.0
  1299.           sys:fonts/timetools            15.0
  1300.           sys:fonts/diamond              12.0, 20.0
  1301.           sys:fonts/garnet               16.0, 9.0
  1302.           sys:fonts/sapphire             14.0, 19.0
  1303.           sys:fonts/topaz                11.0
  1304.           sys:fonts/emerald              17.0, 20.0
  1305.           sys:fonts/opal                 12.0, 9.0
  1306.           sys:fonts/tab                  8.0
  1307.  
  1308.  
  1309.  
  1310.  
  1311.      uprint(G,x,y,data);
  1312.      float x,y;
  1313.      char data[255];
  1314.  
  1315.           Prints  the  data  in  "data"  beginning  at the virtual location
  1316.           (x,y).  "data" may be a character string or a real number.    The
  1317.  
  1318.  
  1319.                                       -20-
  1320.  
  1321.  
  1322.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1323.  
  1324.  
  1325.           uset options "text", "real", and "inte" determine how "data" will 
  1326.           be interpreted.  If "text" is in effect, "data" is expected to be 
  1327.           a character string.  If "real" or "inte" are in effect, "data" is 
  1328.           expected to  be  a real number.  It will be converted to a string
  1329.           and printed as either a real number or an integer  in  accordance
  1330.           with whether "real" or "inte" is in effect.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.      uprnt1(G,option,data);
  1336.      char option[4],data[255];
  1337.  
  1338.           Same  as  uprint except it prints at the current beam position as
  1339.           set by umove or some other drawing operation.  OPTION is  "text",
  1340.           "real",  or  "inte".  The  provided  option  is in effect for the
  1341.           duration of the uprnt1 call only.  Data must  be  either  a  text
  1342.           string or  a  real number.  (The "inte" option truncates the real
  1343.           number and prints an integer.) The beam position  is  updated  to
  1344.           the position  of  the  end of the string that was printed.  It is
  1345.           positioned properly for the beginning of the next string that you 
  1346.           may wish to print with uprnt1.  You can use uwhere  to  find  the
  1347.           virtual  location  of  this  point if you need to know where that
  1348.           point is.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.      uprscr(G); 
  1354.  
  1355.           Dumps the screen image to the printer.  Works for an Epson LQ-850 
  1356.           and presumably will work for other similar printers.   Output  is
  1357.           sent to "par:", the parallel port.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.      uzvtodconv(G,x,y,&xt,&yt,&ix,&iy);
  1363.      float x,y;
  1364.      float xt,yt;
  1365.      long ix,iy;
  1366.  
  1367.           Converts  virtual coordinates (x,y) to screen display coordinates
  1368.           yielding floating point (xt,yt) and fixed point (ix,iy) values.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.      uzdtovconv(G,ix,iy,&x,&y);
  1374.      long ix,iy;
  1375.      float x,y;
  1376.  
  1377.           Converts  screen   display   coordinates   (ix,iy)   to   virtual
  1378.           coordinates (x,y).  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.                                       -21-
  1386.  
  1387.  
  1388.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1389.  
  1390.  
  1391.      uyorn(G,bodytext,positivetext,negativetext,width,height);
  1392.      char bodytext[],positivetext[],negativetext[];
  1393.      float width,height;
  1394.  
  1395.           Puts up  yes/no requester.  Returns true/false value depending on
  1396.           the choice made by the user.  Bodytext is the text of the yes  or
  1397.           no question  you  wish to ask the user.  Positivetext is the text
  1398.           that  will  be  displayed  with  the  positive   selection   box.
  1399.           Negativetext is the text that will be displayed with the negative 
  1400.           selection box.    Width  and  height  are the width and height in
  1401.           "percentage coordinates", i.e., a width and height  of  100  will
  1402.           fill the  whole screen.  A width and height of 50.0 will fill the
  1403.           upper left quarter of the screen.  The requester is always  drawn
  1404.           beginning at the upper lefthand corner of the screen so width and 
  1405.           height are measured from that point.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.      uimove(G,ix,iy);
  1411.      long ix,iy;
  1412.  
  1413.           If  you  wish to bypass floating point and know exactly where you
  1414.           want your pixels to begin, use this command.  (Or you  could  use
  1415.           the  Amiga "Move" command because GWIN merely calls Move with the
  1416.           coordinates you pass in.) 
  1417.  
  1418.  
  1419.  
  1420.  
  1421.      uidraw(G,ix,iy);
  1422.      long ix,iy;
  1423.  
  1424.           If you know exactly where you want your pixels to fall, use  this
  1425.           command.  If  you  get  it wrong though anything can happen.  The
  1426.           Amiga does not respond well to data drawn outside of  the  bounds
  1427.           of the  screen.    It  is  possible to overwrite important things
  1428.           accidentally and cause GURUs.  This  command  merely  passes  the
  1429.           integer data (ix,iy) to the Amiga "Draw" command.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.      uamenu(G,gwinmenu0,gwinmenu1,gwinmenu2,text,comchr,mutex,flags,routine);
  1435.      long gwinmenu0,gwinmenu1,gwinmenu2,mutex;
  1436.      USHORT flags;
  1437.      char comchr;
  1438.      char text[255];
  1439.      long routine();
  1440.  
  1441.           Uamenu makes  creating  menus  easy.   The first three parameters
  1442.           define the menu that you are setting up.  Amiga menus have  three
  1443.           levels.   The  top  level (I'm calling it level 0) appears in the
  1444.           title bar when the right mouse button  is  depressed.    The  top
  1445.           level merely  gives the NAME of the menu.  It is highlighted when
  1446.           the mouse is placed over it.  A level 0 menu  cannot  select  any
  1447.           activity.   It  is  there  to  allow you to select a level 1 menu
  1448.           item.  A level 1 menu item can either cause an action to occur or 
  1449.  
  1450.  
  1451.                                       -22-
  1452.  
  1453.  
  1454.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1455.  
  1456.  
  1457.           cause a level 2 menu to appear depending upon whether a  level  2
  1458.           menu is   attached.     Lets  consider  the  triplet  (gwinmenu0,
  1459.           gwinmenu1, gwinmenu2).  If the  values  are  (1,  0,  0)  we  are
  1460.           referring to  the first level 0 menu in the title bar.  (2, 0, 0)
  1461.           refers to the second level 0 menu in the title bar,  and  so  on.
  1462.           If the values are (3, 1, 0) we are referring to the first level 1 
  1463.           item in  the  third level 0 menu.  If the values are (3, 2, 4) we
  1464.           are referring to the fourth level 2 item in the  second  level  1
  1465.           menu in  the  third  level  zero  menu.   (Please see the example
  1466.           program "testmenu.c".) 
  1467.  
  1468.           Menus items can be referred to in any order.  GWIN will  fill  in
  1469.           with "dummy"  names and actions if necessary.  GWIN allocates all
  1470.           storage necessary for the menus - and cleans up when you exit.  
  1471.  
  1472.           Text is the text that will appear in the menu bar.  
  1473.  
  1474.           Comchr is an Amiga "command character."  This is a character that 
  1475.           allows the menu item to be selected by depressing  the  character
  1476.           while holding  down  the  right  "Amiga" key.  Saves the user the
  1477.           trouble of having to actually use the menus if he  remembers  the
  1478.           "command character."    If  "comchr" is chosen to be ' ', i.e., a
  1479.           blank, there will be no "command character" associated  with  the
  1480.           designated menu  item.   A command character appears to the right
  1481.           of the text within the menu item preceded by a symbol  indicating
  1482.           the right Amiga key.  
  1483.  
  1484.           Mutex contains  mutual  exclusion bits.  These bits may be set to
  1485.           indicate which other menu items on  this  same  level  should  be
  1486.           deselected when  this  menu item is selected.  If mutex is set to
  1487.           0, no mutual exclusion occurs.  For most normal menus you  should
  1488.           set  mutex  to 0. Setting bit 0 to 1 means that the first item in
  1489.           the menu list is excluded by selecting this item.  Setting bit  5
  1490.           to  1  means  that the fifth item in the menu list is excluded by
  1491.           selecting this item, etc.  
  1492.  
  1493.           Flags contains flag bits that  provide  additional  control  over
  1494.           menus and  menu  items.  If you are addressing a level zero menu,
  1495.           only two flag bits are active: 
  1496.  
  1497.                MENUENABLED - When set means that  the  menu  is  ready  for
  1498.                action.  When not set the menu and its items are disabled.  
  1499.  
  1500.                MIDRAWN - When set means that the menu is display.  The menu 
  1501.           is not displayed when MIDRAWN is not set.  
  1502.  
  1503.           If  you  are  addressing  a  level  one  or  level  two menu, the
  1504.           following flags have meaning: 
  1505.  
  1506.           CHECKIT - Places a check mark in front of  an  item  when  it  is
  1507.                selected.   If  you use this flag, you should leave room for
  1508.                the check mark by having 3 or 4 leading blanks in the "text" 
  1509.                parameter.  
  1510.  
  1511.           CHECKED - Places a check mark in front of an item when  the  menu
  1512.                first comes up.  
  1513.  
  1514.           ITEMTEXT  -  Indicates  that  the  menu  item is text rather than
  1515.  
  1516.  
  1517.                                       -23-
  1518.  
  1519.  
  1520.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1521.  
  1522.  
  1523.                graphics.  The current version of  GWIN  allows  text  only.
  1524.                You must set this flag.  
  1525.  
  1526.           COMMSEQ -  Indicates  that  there  is a command key sequence.  If
  1527.                comchr is set non-blank, you should set COMMSEQ if you  wish
  1528.                the command key to appear in the menu bar.  
  1529.  
  1530.           ITEMENABLED -  Enables  menu  item.   You must set ITEMENABLED in
  1531.                this version of GWIN.  
  1532.  
  1533.                One of the following three menu highlighting flags must be set: 
  1534.  
  1535.           HIGHCOMP - Complements all bits of this menu item's menu bar when 
  1536.                it is selected.  Gives a visual indication to the user.  
  1537.  
  1538.           HIGHBOX - Draws a box outside this item's select box.  
  1539.  
  1540.           HIGHNONE - Specifies no highlighting.  
  1541.  
  1542.  
  1543.           Routine is a function pointer that points to  the  function  that
  1544.           you  wish control transferred to when this menu item is selected.
  1545.           This is a function in your program that you design to  carry  out
  1546.           the activity selected by the user.  
  1547.  
  1548.  
  1549.           UAMENU EXAMPLES: 
  1550.  
  1551.           The following are examples of valid uamenu calls: 
  1552.  
  1553.         uamenu(G,1,0,0,"test1",' ',0,MIDRAWN|MENUENABLED,0); 
  1554.  
  1555.         uamenu(G,1,1,0,"test2",' ',0,MIDRAWN|ITEMTEXT|HIGHCOMP 
  1556.                   |ITEMENABLED,function110); 
  1557.  
  1558.         uamenu(G,1,1,1,"test3",'B',0,MIDRAWN|ITEMTEXT|HIGHCOMP 
  1559.                   |COMMSEQ|ITEMENABLED,function111); 
  1560.  
  1561.         uamenu(G,1,2,0," test4",'C',0,MIDRAWN|ITEMTEXT|HIGHCOMP 
  1562.                   COMMSEQ|CHECKIT|ITEMENABLED,function120); 
  1563.  
  1564.  
  1565.  
  1566.  
  1567.      usetrgb(G,colorindex,redvalue,greenvalue,bluevalue);
  1568.      float colorindex,redvalue,greenvalue,bluevalue;
  1569.  
  1570.           Sets  the  color  register indirectly pointed to by colorindex to
  1571.           have the designated red, green and blue values.  See appendix  to
  1572.           see   which   Amiga   color  registers  are  pointed  to  by  the
  1573.           colorindex.  The red green  and  blue  values  are  converted  to
  1574.           integers and each must be in the range 0 to 15.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.      ugetrgb(G,colorindex,&redvalue,&greenvalue,&bluevalue);
  1580.      float colorindex;
  1581.  
  1582.  
  1583.                                       -24-
  1584.  
  1585.  
  1586.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1587.  
  1588.  
  1589.      float redvalue,greenvalue,bluevalue;
  1590.  
  1591.           Retrieves  the  red,  green and blue values of the color register
  1592.           indirectly pointed to by colorindex.  
  1593.  
  1594.  
  1595.  
  1596.  
  1597.      ugetstring(G,x,y,width,prompt,text);
  1598.      float x,y,width;
  1599.      char prompt[],text[];
  1600.  
  1601.           Puts a requester on the screen and waits for the user to type  in
  1602.           a string.    X and y gives the coordinates of the upper left hand
  1603.           corner of the requester  box.    These  coordinates  are  virtual
  1604.           coordinates.   Width  gives  the  width of the requester box as a
  1605.           virtual x coordinate distance.  Prompt is a text string that  you
  1606.           provide  that  lets  the user know what sort of data (string) you
  1607.           are expecting from him.    "Text"  should  be  declared  in  your
  1608.           calling program  as  a length 255 character array.  Prompt may be
  1609.           up to 255 characters.  (They probably won't all fit on the screen 
  1610.           if you use them all.) The font assumed within  the  requester  is
  1611.           "topaz.font",  size 8. (It comes with the machine, I expect it to
  1612.           be available...) 
  1613.  
  1614.  
  1615.  
  1616.  
  1617.      usetcleanup(G,cleanup_routine);
  1618.      long cleanup_routine();
  1619.  
  1620.           This allows you to have your own cleanup routine.  It is possible 
  1621.           for the user to exit a GWIN-based application by clicking on  the
  1622.           close window  gadget.    (Unless  the  "nclo"  uset  option is in
  1623.           effect.) If you had done memory allocation in your application or 
  1624.           left the sound on, etc, having your own  cleanup  routine  allows
  1625.           you to  clean  those  things up.  When the close window gadget is
  1626.           selected, GWIN cleans up all of its  storage  allocation,  window
  1627.           and screen allocations, closes libraries it opened, etc.  Control 
  1628.           is then passed to your cleanup routine if you specified one via a 
  1629.           usetcleanup call.   Cleanup_routine is a function pointer to your
  1630.           cleanup routine.  For an example, see routines  in  the  examples
  1631.           directory.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.      uset(G,option);
  1637.      char option[4];
  1638.  
  1639.  
  1640.           OPTION: 
  1641.  
  1642.           "fill"    Turns on polygon fill mode.
  1643.  
  1644.           "nofi"    Turns off polygon fill mode.  Closes and fills
  1645.                current polygon. (DEFAULT)
  1646.  
  1647.  
  1648.  
  1649.                                       -25-
  1650.  
  1651.  
  1652.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1653.  
  1654.  
  1655.           "text"    Sets text mode for uprint.  Uprint assumes input
  1656.                was a character string.  (DEFAULT)
  1657.  
  1658.           "inte"    Sets "integer" mode for uprint.  Uprint assumes
  1659.                input was a floating point number that should be
  1660.                truncated and displayed as an integer.
  1661.  
  1662.           "real"    Sets "real" mode for uprint.  Uprint assumes input
  1663.                was a floating point number that should be displayed
  1664.                as a floating point number.
  1665.  
  1666.           "clip"    Turns polygon and line clipping on.   (DEFAULT)
  1667.  
  1668.           "ncli"    Turns polygon and line clipping off.  Use this
  1669.                only when you are absolutely certain that your
  1670.                drawing will be confined to the active graphics
  1671.                region!
  1672.  
  1673.           "rint"    If polygon "fill" mode is on and "rint" is on,
  1674.                then only the interior of rectangles plotted
  1675.                using urect will be filled.  Their borders will be unchanged.
  1676.  
  1677.           "rext"    If polygon "fill" mode is on and "rext" is on,
  1678.                then the whole polygon including the border will
  1679.                be filled with the current color when urect is called.
  1680.  
  1681.           "clos"    Allows ugrin, ugrinl, and ugrinc to close down
  1682.                the GWIN graphics system and exit back to the
  1683.                system if the user selects the close window
  1684.                gadget.  (DEFAULT)
  1685.  
  1686.           "nclo"    Allows ugrinl, ugrinc, and ugrina to report the
  1687.                CLOSEWINDOW event to your program.  No shutdown
  1688.                of the GWIN system results.  It is then up to
  1689.                you to issue the UEND() call.  This option allows
  1690.                you to handle the problem of freeing storage
  1691.                areas you may have allocated in your main
  1692.                program among other things.  NOTE:  Ugrin exits any time the
  1693.                CLOSEWINDOW gadget is selected by the user.  The "nclo" option
  1694.                has no effect on ugrin.
  1695.  
  1696.           "comp"    Color "complement" mode.  The color with which to
  1697.                draw is selected by calling upset(G,"colo",xx).  The
  1698.                number xx is mapped to an Amiga "color register".
  1699.                Let's say that xx maps to color register rr.
  1700.                (See appendix for GWIN color mapping information.)
  1701.                Each color register contains red/green/blue values
  1702.                that determine the color drawn when that color register
  1703.                is used.  When "comp" is in effect, instead of using
  1704.                color register rr for drawing, each pixel in the
  1705.                display bitmap that would have been drawn using rr is
  1706.                examined to see what color register generated it and
  1707.                then the complement of that register number is
  1708.                substituted for that pixel.  Each pixel that would
  1709.                have been drawn using rr changes color.  If you draw
  1710.                a line or an object once using complement mode, the
  1711.                line or object appears.  If you draw it again, it
  1712.                disappears and the screen image returns to its exact
  1713.  
  1714.  
  1715.                                       -26-
  1716.  
  1717.  
  1718.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1719.  
  1720.  
  1721.                original state.  Complement mode is used for drawing
  1722.                rubberband lines, rubberband boxes, and placing objects.
  1723.                I have arranged the color map so that if the background
  1724.                color of the region over which you are drawing in
  1725.                complement mode is black (the default), then the
  1726.                colors drawn in complement mode will be what you expect,
  1727.                i.e., red will be red, blue will be blue, etc.
  1728.                This requires black to be assigned to color register
  1729.                zero and the current drawing color to be placed in register
  1730.                15 or 31 depending upon the number of colors allowed for
  1731.                the type of screen you have chosen.  This is why certain
  1732.                colors (such as red) are repeated in the colormap.
  1733.  
  1734.           "ncom"    Turns complement mode off.
  1735.  
  1736.  
  1737.  
  1738.  
  1739.      upset(G,option,value);
  1740.      char option[4];
  1741.      float value;
  1742.  
  1743.  
  1744.  
  1745.           OPTION    VALUE                   ACTION
  1746.  
  1747.           "colo"    0.0 through 31.0        Set current color for drawing.  See
  1748.                                        Appendix 1 for color map.  (Sets
  1749.                                        "A" pen and "O" pen.)
  1750.  
  1751.           "acol"    0.0 through 31.0        Set current color for A pen only.
  1752.  
  1753.           "ocol"    0.0 through 31.0        Set current color for O pen only.
  1754.  
  1755.           "bcol"    0.0 through 31.0        Set current color for background
  1756.                                        color.  Background refers to text
  1757.                                        background.
  1758.  
  1759.           "ccol"    0.0 through 31          Set current color for clearing
  1760.                                        active graphics region when uerase is
  1761.                                        called.
  1762.  
  1763.           "fsty"    0.0 through 16.0        Set font style.  Amiga allows
  1764.                                        the following font style settings
  1765.                                        to be applied to font sets that
  1766.                                        allow such settings:
  1767.  
  1768.                                        0.0 = DEFAULT
  1769.                                        1.0 = Underlined
  1770.                                        2.0 = bold
  1771.                                        4.0 = italic
  1772.                                        8.0 = wider
  1773.  
  1774.                                        Add the values of each of the above
  1775.                                        that you wish to choose and use
  1776.                                        the result as "VALUE" when you
  1777.                                        call upset with the "fsty" option.
  1778.  
  1779.  
  1780.  
  1781.                                       -27-
  1782.  
  1783.  
  1784.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1785.  
  1786.  
  1787.                                    APPENDIX 1
  1788.  
  1789.  
  1790.             GLOBAL VARIABLES AND CONSTANTS IN GWIN MODULE ACCESSIBLE
  1791.      FROM PROGRAMS WHICH USE THE GWIN LIBRARY AND INCLUDE THE FILE gwin.user.h:
  1792.  
  1793.      #define SCR_MAX 2
  1794.      #define WIN_MAX 50
  1795.      #define MAXVECTORS 1000
  1796.  
  1797.      struct RastPort *rport1;
  1798.      struct Window *win[WIN_MAX];
  1799.      struct Screen *scr[SCR_MAX];
  1800.  
  1801.      struct GfxBase *GfxBase;
  1802.      struct IntuitionBase *IntuitionBase;
  1803.      struct DiskfontBase *DiskfontBase;
  1804.  
  1805.      Rport1  is  the  raster  port pointer that you would use if you issued
  1806.      your own Amiga graphics routine call.  It is  possible  while  in  the
  1807.      GWIN system  to call Amiga graphics routines.  You must then of course
  1808.      insure that your graphics figures do not exceed the established  pixel
  1809.      boundaries.   You  should not find it necessary to make such calls and
  1810.      they are discouraged generally - but if you need to, want to, and  are
  1811.      willing to assume the GURU risks, feel free.  
  1812.  
  1813.      Win[0] is  the  pointer  to  the window that GWIN is using.  (Multiple
  1814.      windows are not allowed within  GWIN  at  present.    You  could  open
  1815.      another  window  of  your  own  for  your  own  purposes  using Scr[0]
  1816.      presumably - at your risk.) It is available for use if  you  need  it.
  1817.      Hopefully you  won't.    Don't  close the window yourself in any case.
  1818.      GWIN closes everything and releases all allocated space when you  call
  1819.      UEND() or when you select the close gadget.  
  1820.  
  1821.      Scr[0] is  the  pointer  to  the screen that GWIN is using.  (Multiple
  1822.      screens are not allowed at present.) It is available for  use  if  you
  1823.      need it.  Hopefully you won't.  Don't close the screen yourself in any 
  1824.      case.   GWIN  closes  everything  it  opened and releases all space it
  1825.      allocated when you call UEND().  
  1826.  
  1827.      The MAX_VECTOR variable refers to the maximum number of sides that can 
  1828.      be handled by uplygn.  You will NOT need a 1000  sided  polygon.    It
  1829.      will  merely  look  like  a  VERY  slowly drawn circle and a 100 sided
  1830.      polygon is a nearly perfect approximation.  You  could  also  bump  up
  1831.      against  this limit if you do too many udraws in a row without doing a
  1832.      umove while in fill mode.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.                                       -28-
  1848.  
  1849.  
  1850.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1851.  
  1852.  
  1853.                             COLOR TRANSLATION TABLE.
  1854.  
  1855.      Use these values for color_value in upset(G,"colo",color_value)  calls
  1856.      to obtain the corresponding color.  
  1857.  
  1858.      black = 0.0;
  1859.      red = 1.0;
  1860.      green = 2.0;
  1861.      blue = 3.0;
  1862.      cyan = 4.0;
  1863.      yellow = 5.0;
  1864.      magenta = 6.0;
  1865.      white = 7.0;
  1866.      darkred = 8.0;
  1867.      darkgreen = 9.0;
  1868.      darkblue = 10.0;
  1869.      orange = 11.0;
  1870.      lime = 12.0;
  1871.      forestgreen = 13.0;
  1872.      aqua = 14.0;
  1873.      red2 = 15.0;
  1874.      violet = 16.0;
  1875.      brickred = 17.0;
  1876.      grey = 18.0;
  1877.      goldorange = 19.0;
  1878.      skyblue = 20.0;
  1879.      redorange = 21.0;
  1880.      brown = 22.0;
  1881.      pink = 23.0;
  1882.      purple = 24.0;
  1883.      tann = 25.0;
  1884.      bluegreen = 26.0;
  1885.      darkbrown = 27.0;
  1886.      lightaqua = 28.0;
  1887.      cadyellow = 29.0;
  1888.      white2 = 30.0;
  1889.      red3 = 31.0;
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.                                       -29-
  1914.  
  1915.  
  1916.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1917.  
  1918.  
  1919.                    ACTUAL COLOR REGISTER ASSIGNMENTS IN GWIN
  1920.  
  1921.      Normally you     would't     use     these.        You    would    use
  1922.      upset(G,"colo",(float)color_number) where color_number is given in the 
  1923.      color translation table above.  The "actual color register" numbers in 
  1924.      this table  would  be  used  only  if  you  wished  to  directly  call
  1925.      SetAPen(rport1,number)   or   other   similar   Amiga  call  directly.
  1926.      (Allowable but discouraged.) 
  1927.  
  1928.       black = 0;
  1929.       blue = 1;
  1930.       red = 2;
  1931.       green = 3;
  1932.       cyan = 4;
  1933.       magenta = 5;
  1934.       lime= 6;
  1935.       yellow = 7;
  1936.       aqua = 8;
  1937.       darkblue = 9;
  1938.       darkgreen = 10;
  1939.       darkred = 11;
  1940.       forestgreen = 12;
  1941.       orange = 13;
  1942.       white = 14;
  1943.       red2 = 15;
  1944.  
  1945.       violet = 16;
  1946.       brickred = 17;
  1947.       grey = 18;
  1948.       goldorange = 19;
  1949.       skyblue = 20;
  1950.       redorange = 21;
  1951.       brown = 22;
  1952.       pink = 23;
  1953.       purple = 24;
  1954.       tann = 25;
  1955.       bluegreen = 26;
  1956.       darkbrown = 27;
  1957.       lightaqua = 28;
  1958.       cadyellow = 29;
  1959.       white2 = 30;
  1960.       red3 = 31;
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.                                       -30-
  1980.  
  1981.  
  1982.      17 Nov 1991                      GWIN            by Howard C. Anderson
  1983.  
  1984.  
  1985.      ERROR RETURN CODES 
  1986.  
  1987.      Since AMIGA libraries cannot write to the screen, the following return 
  1988.      code values are used to indicate problems: 
  1989.  
  1990.      RETURN VALUE   GWIN PROCEDURE  MEANING
  1991.  
  1992.      1              abort_          User abort.  (I'm not sure that this is
  1993.                                     possible now.)
  1994.  
  1995.      2              USTART, udarea  Illegal values of screen size entered.
  1996.                                     Error occurs when:
  1997.                                     xmax <= xmin || ymax <= ymin
  1998.  
  1999.      3              uwindo          Illegal parameters passed to uwindo.  The
  2000.                                     error occurs when:
  2001.                                     (xmax-xmin) <= 0.0 || (ymax-ymin) <= 0.0
  2002.  
  2003.      4              ugrin           A CLOSEWINDOW event has occurred.  You
  2004.                     ugrinc          must call UEND().
  2005.                     ugrinl
  2006.                     ugrina
  2007.                     uigrina
  2008.  
  2009.      5              uplygn          Illegal parameters passed to uplygn.
  2010.                                     Largest legal polygon has 2000 or less
  2011.                                     sides.  You have requested a polygon
  2012.                                     with more than 2000 sides.
  2013.  
  2014.      6              uamenu          Negative menu number was passed to
  2015.                                     uamenu.  You cannot use negative
  2016.                                     menu numbers.
  2017.  
  2018.      7              usetrgb         A value greater than 15.0 was entered for
  2019.                                     red, green or blue.  Cannot have color
  2020.                                     values greater than 15.0.
  2021.  
  2022.      8, 9, 10       ustart          Internal, required libraries not found.
  2023.                                     These are intuition.library,
  2024.                                     graphics.library and diskfont.library.
  2025.                                     The result of failure of one of these is
  2026.                                     that ustart will return a NULL value
  2027.                                     for G.
  2028.  
  2029.      11             ustart          Internal, screen cannot be opened.
  2030.                                     Ustart checks xmin, xmax, ymin, ymax
  2031.                                     for validity.  The USTART (macro)
  2032.                                     returns NULL.
  2033.  
  2034.      12, 13, 14,    ustart          Internal, window could not be opened.
  2035.      15, 16, 17                     Check xmin, xmax, ymin, ymax for
  2036.                                     validity.  The USTART macro returns
  2037.                                     NULL.
  2038.  
  2039.      100            All procedures  The G structure is invalid.  Either the
  2040.                                     pointer is incorrect or the data has
  2041.                                     been overwritten.
  2042.  
  2043.  
  2044.  
  2045.                                       -31-
  2046.