home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d9xx / d911 / gadoutline.lha / GadOutline / readme.txt < prev    next >
Text File  |  1993-10-03  |  9KB  |  185 lines
  1.  
  2. GadOutline Library v2.0
  3. ~~~~~~~~~~~~~~~~~~
  4. Copyright (C)1993 by Dianne Hackborn.
  5.  
  6. =========================================================================
  7. This program is shareware.  If you like it and use it in your
  8. programs, please consider becoming a registered by sending $20 me.
  9. (My address is below.)  This will allow me to provide answers to
  10. questions you may have about its use and the resources to continue to
  11. develop the library.
  12.  
  13. There is admittedely a very limited amount of documentation on the
  14. library right now.  It was originally written for use in my own
  15. programs and, while it has grown quite a bit beyond that, I can not
  16. justify putting in the time to write up extensive documentation that
  17. I don't need.  This will change if there is a good response to the
  18. library [read: money :)], but for now I can not guarantee anything
  19. beyond what is already here.  If you do decided to register, however,
  20. I will be able to provide you with more support.
  21.  
  22. This library is freely distributable as long as all of its files are
  23. included with no modifications.  By becoming registered, you will be
  24. allowed to include a subset of the library distribution with your program
  25. if you so desire.  The library is provided as-is, with no warranties of
  26. any kind.
  27.  
  28. People interested in using this in a commercial product should
  29. contact me to discuss it.  [I'm not greedy.  Really. ;)]
  30. =========================================================================
  31.  
  32. INTRODUCTION
  33.  
  34. Gadoutline.library is intended to provide you with a means of
  35. describing the general layout of your GUI in a font-independant
  36. manner, and take care of the details of determining the exact
  37. placement of the individual elements of the display and the drudgery
  38. of creating and managing all of the gadgets.  In addition, it
  39. provides a very generalized mechanism for tracking the state of all
  40. of its gadgets to support automatic resizing and closing and opening
  41. of a window without loss of context, automatic hotkey support, a
  42. vector based drawing module that can be used for everything from
  43. drawing frames around groups of gadgets to creating custom images
  44. for BOOPSI gadgets to adding complex drawings and textual information
  45. to a window, the ability to transparently use both GadTools and
  46. BOOPSI gadgets, and to use new GadTools and BOOPSI gadgets without
  47. having to write a single line of code.
  48.  
  49. WHAT IS A "GADOUTLINE?"
  50.  
  51. The library draws its name from the primary data structure used to
  52. describe the entire gadget layout - a ULONG array 'outline' which is
  53. composed of individual 'commands.'  A command is used to define a
  54. single element of the display - a gadget, the wrapper around a group
  55. of gadgets, or an image - and additional 'control' commands are used
  56. to control how groups are organized, provide additional information to
  57. the library, and mark the end of the array.  This array is an entirely
  58. static structure; the library only uses it to determine the dynamic
  59. data which is needed by the layout and after that it is never
  60. referenced again.  This brings a number of important consequences:
  61.  
  62.     - An application almost never refers to the elements of the
  63.       outline in terms of pointers.  While ultimately all of the
  64.       commands are referenced as normal pointers to C structures, the
  65.       application almost entirely refers to the commands and their
  66.       associated gadgets in terms of an ID code which is assigned to
  67.       the command.  Every command must have either a unique ID code,
  68.       or the special "none" code of 0, and everything from assigning
  69.       hotkeys to setting a gadget's attributes uses this unique ID
  70.       code to determine which command is being refered to.
  71.  
  72.     - Almost all of the information needed to create a gadget is
  73.       localized into one place in the outline array, making it much
  74.       easier to see what a gadget actually is.  In addition, the layout
  75.       of the gadgets is primarily determined by their position in the
  76.       array, so it is relatively easy to understand their
  77.       relationship to the rest of the window.  Moving the layout
  78.       around is as easy as using cut and paste in your text editor.
  79.       
  80.     - Defining connections between objects no longer requires
  81.       absolute pointers to them.  Instead, you simply include the
  82.       command ID along with the rest of the definition of your
  83.       gadget, and the library takes care of resolving the pointer when
  84.       the gadget is actually created.
  85.     
  86.     - All of the tags used to define the orginal layout are
  87.       dynamically tracked by the library as the gadgets are changed
  88.       and your program makes changes, so that the layout and all of its
  89.       objects can be restored to their previous state even when closing
  90.       a window and opening it on a new screen.  And because all of
  91.       the library's state tracking is based on the object's tags, new
  92.       kinds of gadgets are automatically tracked by the library.
  93.  
  94. With the addition of a "translation" callback hook, automatic
  95. localization can easily be implemented, or it is even possible to
  96. design a method of removing all absolute memory references within the
  97. static outline so that it could, for example, be loaded off disk when
  98. needed by the application.
  99.  
  100. THE EXAMPLE PROGRAMS
  101.  
  102.     Included with this archive are the example programs example1,
  103.     example2 and example3.  In addition, my separate public screen
  104.     manager program "PSM" [yes, I'm naming-impaired ;)] should be
  105.     available, which provided a full demonstration of a working
  106.     application with multiple windows.  The most useful of these is
  107.     probably example3, which is fully commented and plays some tricks
  108.     with the library to allow you to see how it does a full layout of
  109.     the outline by forcing one every time the window resizes.
  110.     
  111.     Example1 is probably only useful to see a simple implementation of
  112.     a shared IDCMP port, and PSM has a more complicated, complete
  113.     implementation of this.
  114.     
  115.     Example2 is only notable for its utterly garish display and
  116.     unreadable source code. :)
  117.  
  118. WHERE TO GO NOW
  119.  
  120.     The two main sources of documentation are the autodocs and the
  121.     header file.  If you have AmigaGuide, read the file "GadOutline"
  122.     in the includes directory.  This is the fully linked AmigaGuide
  123.     version of the autodocs, with appropriate connections to the
  124.     header file [and the system header files, too, if you have them in
  125.     your AmigaGuide search path.]
  126.     
  127.     Otherwise, the autodocs are suppled as a plain text file in
  128.     "GadOutline.doc".
  129.     
  130.     The first entries you will probably want to read are
  131.     AllocGadOutlineA(), GO_GetGOIMsg(), GO_GetCmdInfo(),
  132.     GO_InterpretTypedSize() and GO_OpenWindowA(), and just follow
  133.     their links.
  134.     
  135. WHAT ISN'T HERE
  136.  
  137. Before putting any more work into this library, I would like to see
  138. what the response is going to be in order to judge whether it is
  139. worth it.  This doesn't mean that it is in any way incomplete as it
  140. is; in fact, the reason that I'm releasing it now is because I have a
  141. bunch of projects that I would like to work on and have been waiting
  142. for the library to be usable.  However, it does mean that the only
  143. things implemented at the moment are what that I need.  So:
  144.  
  145.     - BOOPSI support is barely implemented and has been tested even
  146.       less.  There are a couple of small things that definately need
  147.       to be implemented to fully support BOOPSI, and will probably be
  148.       added at some point, but for now creating images and attaching
  149.       button gadgets is about all you can expect.  That part does
  150.       work pretty well, however. ;)
  151.       
  152.     - Gadgets in window borders aren't supported.
  153.     
  154.     - The only real documentation is what is in the autodocs and the
  155.       header file gadoutline.h.  About the only real overview on how
  156.       everthing works is the program example3.c.  This hopefully will
  157.       be enough to get a basic, usable understanding of how it works.
  158.       And, if you want more...  well, register. :)
  159.       
  160.     - There is absolutely no documentation on the vector drawing
  161.       commands beyond what is in the header file, and currently no
  162.       programmer interface to them besides the integrated support in
  163.       the outline draw groups, boxes and images.
  164.       
  165.     - No V39 specific support.  Someday...
  166.  
  167. HOW TO REACH ME
  168.  
  169. EMail -     BIX: dhack@bix.com
  170.             SCHOOL: hackbod@xanth.cs.orst.edu
  171.  
  172. SnailMail - Dianne Hackborn
  173.             2895 Los Altos Drive
  174.             Meridian, ID 83642
  175.             
  176. THANKS TO
  177.  
  178.     David Junod, Michael Cianflone, Gary Milliorn, John Basile and
  179.     Doug Keller for their comments and suggestions.
  180.  
  181. FINALLY
  182.  
  183.     Have fun, and I hope you find the library useful.  All comments,
  184.     suggestions and bug reports are more than welcome.
  185.