home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD1.img / d1xx / d137 / vgad / vgad.doc < prev    next >
Text File  |  1988-03-19  |  9KB  |  204 lines
  1.                                     Vgad
  2.  
  3.                       A gadget making tool for the Amiga
  4.  
  5.                         Written and Copyright (C) 1987
  6.                            by:  Stephen Vermeulen
  7.                                 3635 Utah Dr. N.W.,
  8.                                 Calgary, Alberta,
  9.                                 CANADA, T2N 4A6
  10.                                 (403) 282-7990.
  11.  
  12.                          Version 1.00,  14-Dec-1987
  13.  
  14.                 =============================================
  15.                  This program may be freely redistributed
  16.                  provided that no charge is made for such
  17.                  distribution appart from reasonable media
  18.                  costs.  This program may not be distributed
  19.                  with any commercial product without the
  20.                  prior written approval of the Author.
  21.                 =============================================
  22.  
  23. Introduction:
  24.  
  25.      This little utility was brought to light by the need to create
  26.      windows full of gadgets quickly from finnished art work.  The
  27.      philosophy that was adopted (since I am such a lousy artist) was
  28.      that the Artist should create the ENTIRE window (including gadget
  29.      layout and imagery) and then the Programmer would convert that
  30.      finished art work to the appropriate SHORT[]/Image/Gadget/Window
  31.      structures.
  32.  
  33.      This approach was tried using a commercial product and the idea
  34.      was found to be sound; however, the approach taken in that product
  35.      necessitated the careful window layout being shattered into
  36.      brushes which would then be separately (and painstakingly)
  37.      loaded and repositioned.  This seemed like a major Government make
  38.      work project so Vgad was born.
  39.  
  40.      Vgad provides none of the fancy frills associated with other gadget
  41.      editors; it takes a very simple direct approach that you might find
  42.      does the job very quickly.  The idea is: the Artist creates all the
  43.      imagery in two pictures (standard IFF pics).  One picture contains the
  44.      normal state (non-selected) and the other contains the fully
  45.      selected state (all gadgets simultaneously depressed).  The Programmer
  46.      then runs Vgad on these two pictures and quickly boxes each gadget
  47.      in turn.  Once this has been done (typically just a few minutes)
  48.      Vgad will have produced a C-source code file containing all
  49.      the necessary data and control structures.  The Programmer does a
  50.      few more edits of this .c file and the associated .h file and
  51.      compiles it...  And as they say: "the rest is left as an example
  52.      for the interested reader."
  53.  
  54. Running Vgad:
  55.  
  56.      Vgad can only be run from the CLI at this time.  The command to
  57.      run it is either:
  58.  
  59.           Vgad
  60.  
  61.      which will print a copyright message and version number, along with
  62.      the command syntax; or:
  63.  
  64.           Vgad normal.pic selected.pic prefix file.c file.h
  65.  
  66.      which will start the ball rolling.  The various command arguments are:
  67.  
  68.      normal.pic:
  69.  
  70.          This is the normal (quiescent) state picture of the window.  This
  71.          is a standard IFF graphic, which should normally be rendered on
  72.          one of the standard screen sized pages.  This graphic may have
  73.          any number of colours (ie. bitplanes) that the standard screen
  74.          mode will allow - but exercise restraint: the Amiga is a
  75.          MultiTasking machine so don't waste memory!
  76.  
  77.          To make this picture, just call up your favourite graphics editor
  78.          (Express Paint etc.) and start doodling.  Better yet, call your
  79.          local starving Amiga artist and get him to make the picture :-)
  80.  
  81.      selected.pic:
  82.  
  83.          This is another standard IFF graphic.  This one contains the
  84.          selected state (highlighted) imagery for all the gadgets in
  85.          the normal.pic.  This can be very easily made by editing a copy
  86.          of the normal.pic and just using a rectangular complement tool
  87.          to do the appropriate highlighting.  Alternatively, you can get
  88.          your Amiga artist to make all sorts of fancy anternate imagery
  89.          (since this is what Vgad does) for each of the gadgets.
  90.  
  91.          It is important that these two pictures are aligned in the same
  92.          way on their pages because Vgad will assume that the normal and
  93.          selected images for each gadget are in the same place on the two
  94.          pictures.
  95.  
  96.      prefix:
  97.  
  98.          The prefix is a single text string that you want to use as the
  99.          identifier for all the structures that are produced by Vgad from
  100.          the two pictures.  This string allows you to make the various
  101.          structure names unique and to easily include the output from
  102.          several runs of Vgad in one program without name conflicts.
  103.  
  104.          Vgad will construct the names of all the structures it generates
  105.          from this prefix string by the following type of printf statement:
  106.  
  107.             printf("%s%d_%s", prefix, no, postfix);
  108.  
  109.          The "postfix" string depends on the type on the structure to be
  110.          generated.  Examples include "gadget" for a Gadget structure,
  111.          "image", "window"...   The "no" integer variable is the number
  112.          of the structure.  For example this is the 3rd Image structure or
  113.          this is the 5th Gadget structure, and so on.
  114.  
  115.      file.c
  116.  
  117.          This is the file to which Vgad will write the C source code output.
  118.          Currently all structures are written to this one file.  Ideally,
  119.          one would want to write the image data to its own file since that
  120.          is the only data that must be in CHIP ram.  This file can become
  121.          quite large so you should make certain that there is enough free
  122.          space on the destination device.
  123.  
  124.      file.h
  125.  
  126.          This file is a header file that you can include from your own
  127.          source code to define all the structures that are contained in
  128.          file.c.  This file will not be very large; there is typically a
  129.          ratio of about 50:1 between the file.c and file.h sizes.
  130.  
  131. Usage:
  132.  
  133.      Once Vgad is up and running all you will see is a screen filled with
  134.      your normal.pic.  There are no menus or gadgets attached anywhere on
  135.      this screen.
  136.  
  137.      Vgad gets its instructions in from you in two ways.  The first is by
  138.      you boxing an area on the screen.  The boxing process is the fairly
  139.      standard: push select button down, drag the mouse around until the box
  140.      is the correct size and then release the select button.  If you made
  141.      a mistake in the area boxed, just box it again, Vgad only remembers
  142.      the last area boxed.  There is one twist to the boxing of areas, this
  143.      is modeled after Express Paint, that is while you are rubberbanding
  144.      a box you can DRAG the entire box (without changing its size) anywhere
  145.      on the screen by just holding down a shift key while moving the mouse.
  146.  
  147.      The second source of commands is the keyboard.  Vgad understands the
  148.      following keys:
  149.  
  150.          b   make a boolean Gadget of the currently boxed area,
  151.          i   make an Image of the currently boxed area,
  152.          l   make a longint Gadget of the currently boxed area,
  153.          p   make a proportional Gadget of the currently boxed area,
  154.              (not implemented in this version)
  155.          s   make a string Gadget of the currently boxed area,
  156.          w   make a Window of the currently boxed area
  157.  
  158.          q   quit, exit Vgad.
  159.  
  160.      So the actual use of Vgad goes something like this:
  161.  
  162.          1.  run Vgad
  163.          2.  box an area
  164.          3.  press a key to indicate what to do with the area just boxed
  165.          4.  are we done?
  166.              4.a  if yes press 'q'
  167.              4.b  if not goto 2.
  168.  
  169.      And that is really all there is to it.  You will have to do some
  170.      editing of the output file to modify some of the flags, particularly
  171.      in the Window structure, and you will have to chain the gadgets
  172.      togeather and to the window(s).  But that is about it.  I have included
  173.      a small do-nothing example called "test" (test.norm, test.sel, test.c,
  174.      and test.h) where I have flagged the changes that had to be done to
  175.      the raw file.c output of Vgad to get a running program.  Have a look
  176.      at it to see what to do.  Test just hangs around until a Delay(500L)
  177.      times out and then closes, just giving you time to click on the gadgets
  178.      to see that they are alt-image boolean gadgets.
  179.  
  180. Compiling output:
  181.  
  182.      Vgad source code has been compiled under Manx 3.4a with the various
  183.      patches that have appeared.  I can see no reason why it should not
  184.      compile under Lattice 3.1 or higher; however, this I have not tested.
  185.      When linking the image data must end up in CHIP ram so with Manx the
  186.      appropriate linker command is:
  187.  
  188.         ln +cd file.o -lc
  189.  
  190.      the +cd flag being necessary to put the image data (actually all
  191.      initialized data) in CHIP ram.  You will probably need to do something
  192.      similar if you are using Lattice.
  193.  
  194. Bugs:
  195.  
  196.      None known at the current time.  Image generation for proportional
  197.      gadgets is not yet supported.
  198.  
  199. Comments and Suggestions:
  200.  
  201.      These are always welcome and invited.  If you want a modification
  202.      send me a letter describing it and if I get around to it I will send
  203.      the result off to Fred Fish.
  204.