home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 432b.lha / EzLib / doc / README < prev    next >
Text File  |  1990-11-10  |  9KB  |  234 lines
  1.  
  2.                 Ez.lib and Ezlib.h
  3.       - two things that will make your programming life easier -
  4.  
  5.                   by
  6.                Dominic Giampaolo
  7.  
  8.  
  9.  
  10. 1. Introduction
  11.  
  12.     I have recently started into heavily programming the Amiga.  Since
  13. then, I've noticed that at times it can be *very* difficult to even get
  14. simple things done.  To that end I have started working on Ez.lib.
  15.  
  16.     Ez.lib is a link time library which has high level functions to
  17. accomplish many of the mundane tasks of writing an "Amiga" program.
  18.  
  19.     The Ezlib functions have been designed to simplify the normal process
  20. of creating windows, gadgets, screens and other things.  This is my first
  21. stab, but for the moment it serves my purposes quite well.  Hopefully it
  22. will do the same for you.
  23.  
  24.     Using Ez.lib is also straightforward.  You simply #include <ezlib.h> in
  25. your program, and link with ez.lib.  That's it!
  26.  
  27.  
  28. -----------------------------------------------------------------------
  29.  
  30.  
  31. 2.  What's included?
  32.  
  33.     There are routines to open screens, gadgets, windows, get string input,
  34. get yes or no answers, use disk fonts, open libraries, and of course
  35. closing all that stuff down.  Now when I say "opening screens and windows",
  36. I mean it - you'll see (read: no silly structures to painstakingly fill
  37. out).
  38.  
  39.     Probably the nicest function (IMHO) is the makescreen() call.  Here is
  40. all you need to do to open a HiRes, Interlaced, 3 bitplane screen:
  41.  
  42.  
  43.             struct Screen *screen;
  44.  
  45.             screen = makescreen(HIRES|LACE, 3);
  46.             if (screen == NULL)
  47.               no_screen();
  48.  
  49.  
  50.     That's it.  *Everything* is handled with a single function call.  You
  51. simply specify the modes you would like and the depth, then presto.
  52.  
  53.     Compare this to what would normally be required.  Notice you didn't
  54. even have to bother opening grahics.library or intuition.library!  The
  55. makescreen() call checks those trivial things and covers your butt.
  56.  
  57.     Of course it wouldn't be nice if you had to go through the rigamorole
  58. of closing and freeing all that stuff.    To that end, killscreen() takes
  59. care of you, and with a single call, everything is properly deallocated and
  60. closed down.
  61.  
  62.  
  63.     Now the first thing most people will say is, yeah great that's really
  64. nice, but what about { performance | size }?
  65.  
  66.     Performance really isn't an issue with these calls as you don't sit in
  67. a loop creating custom screens (at least I don't ;-).  And if it really
  68. does matter, the code simply has a few if/then combinations to make sure
  69. you get a valid screen.  Certainly nothing computationally intensive.
  70.  
  71.     Size wise, the extra code for checking various parameters doesn't
  72. amount to a hill of beans.  A demo program I wrote that uses *every*
  73. function in the library is still less than 9K - it accomplishes a fair
  74. amount too, and is one helluva lot easier to understand!
  75.  
  76.  
  77. -----------------------------------------------------------------------
  78.  
  79.  
  80. 3.  Let's go over roughly what is in Ez.lib
  81.  
  82.     These are short descriptions of what each function does.  The complete
  83.     docs for each function are in the doc directory.
  84.  
  85.       Function Name           What it does
  86.       -------------           ------------
  87.  
  88.     openlibs(which_ones)      Open the specified libraries.  Which
  89.                   libraries are opened depends on the
  90.                   argument you specify.  Can easily open
  91.                   multiple libraries at once, error
  92.                   checking each as it goes along.
  93.  
  94.  
  95.     makescreen(modes, depth)      Opens a screen of said modes and depth
  96.                   allocates any necessary bitmaps, etc...
  97.                   Can handle any Amiga screen mode and
  98.                   depth (not overscan though).
  99.  
  100.  
  101.     makewindow(screen,            Open a standard Intuition window with all
  102.            l_edge, t_edge,      the trimmings.  Put it at l_edge (left
  103.            width, height)      edge), t_edge (top edge) and give it
  104.                   width and height for dimensions.  If
  105.                   screen is non null, open it there.
  106.  
  107.  
  108.   makeboolgadget(win,             Create and add to your window an auto-
  109.          l_edge, t_edge,  sized boxed boolean gadget.  The top
  110.          text, id)      corner will be as specified and the width
  111.                   and height are figured dynamically.  The
  112.                   string will be centered in the gadget.
  113.  
  114.  
  115.     getstring(screen,             Pop up a window with a string gadget to
  116.           title, default)      get input from the user.  The window will
  117.                   have the given title, and you may give
  118.                   a default string to place in the string
  119.                   gadget.
  120.  
  121.  
  122.     getyn(window, string)         Use an AutoRequest() to get a yes or no
  123.                   answer from the user.  The string you
  124.                   specify is put in the requestor.
  125.  
  126.  
  127.      getfont(name, size)          Open a disk based font for use in a
  128.                   window or screen.  You specify the name
  129.                   of the font and its size, and the rest is
  130.                   taken care of.
  131.  
  132.  
  133.     There are also functions to close down/deallocate the items you open
  134. with these calls.  You are not required to use the "kill" routines, but
  135. they are guaranteed to be safe, and will free any previously allocated
  136. memory and generally be smart about closing down.
  137.  
  138.     In addition there are a few lower level calls that give more
  139. flexibility in the objects they create.  This is at the expense of a
  140. parameter or two extra which you must specify in the function call.  There
  141. are also two low level bitmap allocation/de-allocation routines.
  142.  
  143. -------------------------------------------------------------------------
  144.  
  145. 4.  General
  146.  
  147.     These functions certainly don't cover everything you will ever need to
  148. do on the Amiga, but they do make many things easier.  For example, you can
  149. now try out the graphics in your Amiga without having to worry about all
  150. the nitty gritty details.
  151.  
  152.     As a similar example, I wanted to write a program to draw Lissajous
  153. curves.  First I was daunted by having to drag out the RKM's and start
  154. going through the NewScreen structure, etc.  Now I simply call makescreen()
  155. once and I'm ready to start drawing the curves!  The entire source to draw
  156. the curves is now less than 1.4K - and the bulk of that is simply setting
  157. up tables to make the calculations faster.  The executable is around 6K.
  158.  
  159.     Using the getstring() function you can even create simple
  160. Intuition'ized programs without any more effort than it would take to call
  161. the same character/line oriented function (gets() or similar).
  162.  
  163.     And with the ability to trivially create boolean gadgets, what more can
  164. you ask for?  A completely Intuitioniz'ed calculator program could be
  165. created without much effort at all.
  166.  
  167.     As you can see, the functionality in Ez.lib will definately make many
  168. programs easier to write and debug.  You don't have to worry about making
  169. sure you properly allocated the bitplanes you needed, or making sure you
  170. did it right.  Instead, you concentrate on your code, knowing that the
  171. Ez.lib functions will cover the rest.
  172.  
  173. ----------------------------------------------------------------------
  174.  
  175.  
  176. 5.  Any thing else?
  177.  
  178.     Well, the real docs for all these functions are in the individual
  179. files in the doc directory.  The return values and methods for calling them
  180. are also documented there.  In addition, there are code fragments in the
  181. documentation that directly show the complete calling sequence for these
  182. functions.  Hopefully, using these functions is straightforward.
  183.  
  184.     I will probably continue to add functionality to the library as needed.
  185. I'd like to cover a lot more things (mainly other types of gadgets), but
  186. for now the library is sufficient to be usable.
  187.  
  188.     I'd like to thank Dan Drake and Bob Koon for both listening to me
  189. babble about this library and for giving me some good input.  Thanks guys.
  190.  
  191.     Finally I'd like to give credit to the _Amiga Transactor_ (god rest
  192. its soul :) for having had excellent articles from which I learned plenty
  193. (and from which some of this code came from!).  In addition, I would like
  194. to thank the many nameless folks who have distributed public domain source
  195. code for doing various things on the Amiga.  I've learned a lot from that
  196. code - thanks.    And finally the folks at Commodore who wrote the RKM's, if
  197. it wasn't for them, I'd still just be using WorkBench ;^)
  198.  
  199.  
  200.     If you are interested in contacting me about bugs, problems, or
  201. questions about EzLib, you can reach me in the following ways:
  202.  
  203.  
  204.      E-mail :   nick@chopin.uunet.uu.net  OR giampal@auvm.bitnet
  205.  
  206.      SNail Mail :   Dominic Giampaolo
  207.             4201 Mass. Ave.
  208.             Apt# 8067 West
  209.             Washington, D.C. 20016
  210.  
  211.     Of course I'd really like to hear back from you if you have anything
  212. (good or bad ;^) to say about these routines.
  213.  
  214.     Oh one final thing.  This code is totally free for you to do whatever
  215. you want with - excluding selling it for outrageous prices, saying that you
  216. wrote it, or any other generally evil things.  Essentially this is in the
  217. spirit of GNU - code for anyone to use and learn from (however this code is
  218. not under the GPL).
  219.  
  220. --dominic
  221. 08/09/90
  222.  
  223. ************************************************************************
  224.  
  225.  NOTE: The library that is included in the distribution is for Manx 3.6.
  226.        If you use Manx 5.0 or Lattice, you WILL have to recompile the
  227.        source and make library from the object files.  I don't know
  228.        Lattice, but I have included a Makefile for Manx, and it shouldn't
  229.        be too hard to do for Lattice.
  230.  
  231. ************************************************************************
  232.  
  233.  
  234.