home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d1xx / d107 / prosuite.lha / ProSuite / ProSuite.doc < prev    next >
Text File  |  1987-10-31  |  12KB  |  273 lines
  1.  
  2. Introduction to the Amiga Programmer's Suite Book 1.01, by RJ Mical
  3. Copyright (C) 1986, 1987, Robert J. Mical
  4. 20 October 1987
  5.  
  6.  
  7.  
  8. Welcome to the Amiga Programmer's Suite, Book 1.  Presented here 
  9. are several tools for Amiga developers.  I hope you find them useful.  
  10.  
  11.  
  12. The Amiga Programmer's Suite is an evolving entity.  It's being 
  13. designed with several goals in mind.  
  14.  
  15. First and foremost, the intent is to make programmers' lives easier by 
  16. creating mechanisms that every programmer wants sooner or later; an 
  17. example of this is the FileIO Requester, which is a mechanism that 
  18. creates a requester and allows the user to browse through the Amiga 
  19. filesystem using an Intuition interface.  Such a tool is very 
  20. complicated to design, for it requires a good amount of Exec, 
  21. AmigaDOS and Intuition knowledge, combined with a familiarity of 
  22. user-interface techniques and touch of graphic design.  The prospect 
  23. of doing the work involved in creating a fully-capable requester 
  24. such as this has boggled the minds of many designers and made them soft.  
  25. Now, by using the Programmer's Suite, designers can include this 
  26. requester in their programs, making the programs easier and more 
  27. enjoyable to use while costing the developer very little effort.
  28.  
  29. The second intent of the Programmer's Suite is to give new Amiga 
  30. tools to the developer.  The XText mechanism is an example of this.  
  31. XText gives programmers a new, powerful way to create text on the Amiga.  
  32. Another example is DoRequest(), which manages requesters automatically.  
  33. These are tools that are part of the Amiga system and may one day 
  34. appear in the Amiga ROM Kernel.
  35.  
  36. The third intent of the Programmer's Suite is to provide a tutorial 
  37. on how to program the Amiga.  The source code and examples may be 
  38. used as a learning aide for the novitiate and the old-salt alike.  For 
  39. instance, in the FileIO Requester source many complicated system 
  40. problems are solved, to the edification of all (hopefully).  I myself 
  41. have learned quite a bit about the Amiga while creating these routines.  
  42. I hope you get something good from them too.
  43.  
  44.  
  45. So enjoy!  And, as always, go for the gold.  You know can do it.
  46.  
  47.  
  48.    - RJ Mical
  49.  
  50.  
  51.  
  52. P.S.  I'm currently compiling notes for Books 2 and 3.  If you have any 
  53. suggestions for these books, and if you have comments and criticisms about 
  54. Book 1, please send them to me at:
  55.  
  56.         RJ Mical
  57.         Suite 123
  58.         999C Edgewater Blvd.
  59.         Foster City, CA    94404
  60.  
  61.  
  62.  
  63.  
  64. =============================================================================
  65. === Copyright, Distribution, and Registration Notices =======================
  66. =============================================================================
  67.  
  68. The Amiga Programmer's Suite Book 1 is copyrighted but freely distributable.
  69. All copyright notices and all file headers must be retained intact.
  70. The Amiga Programmer's Suite Book 1 may be compiled and assembled, and the 
  71. resultant object code may be included in any software product.  However, no 
  72. portion of the source listings or documentation of the Amiga Programmer's 
  73. Suite Book 1 may be distributed or sold for profit or in a for-profit 
  74. product without the written authorization of the author, RJ Mical.
  75.  
  76. You should register your copy with me.  Those who register will get:  
  77. updates which should include both bug fixes and enhancements; announcement 
  78. of and price break on future Suite books; pleasant sense of having done 
  79. a good thing. 
  80.  
  81. To register your copy, send $15 to RJ Mical at the below address
  82. (price subject to change without notice).  I will return a receipt 
  83. along with your registration number:
  84.  
  85.     APS Registration
  86.         RJ Mical
  87.         Suite 123
  88.         999C Edgewater Blvd.
  89.         Foster City, CA    94404
  90.  
  91.  
  92. The Amiga Programmer's Suite was created to help you do it to the 
  93. Amiga computer.  Bang on it well.  The author, RJ Mical, wishes that 
  94. if you use this code in your program, you give him some discreet mention
  95. somewhere.
  96.  
  97.  
  98.  
  99.  
  100. =============================================================================
  101. === Amiga Programmer's Suite Book 1 Contents ================================
  102. =============================================================================
  103.  
  104. ColorWindow
  105.     This is a procedure call that creates a window, called the ColorWindow,
  106.     which has gadgets that allow the user to change the colors of any 
  107.     screen.  After opening the ColorWindow, this routine interacts with 
  108.     the user until the user is satisfied with the current colors.
  109.  
  110.  
  111. DoRequest
  112.     This is a procedure call that creates a requester according to 
  113.     your specifications and manages the interaction with the 
  114.     requester for you.  When finished this routine returns control
  115.     to you with an identifier describing which gadget the user selected
  116.     to terminate the requester.
  117.  
  118.  
  119. FileIO Requester
  120.     This routine creates and manages the FileIO Requester.  The FileIO 
  121.     Requester is a powerful mechanism that gives the user an easy,
  122.     intuitive way to cruise the Amiga filesystem and select file names.
  123.  
  124.  
  125. SetWaitPointer
  126.     A short collection of data and procedure calls that allow 
  127.     the programmer to display one of several WaitPointers 
  128.     such as Workbench Z-cloud.
  129.  
  130.  
  131. XText
  132.     The XText routines have one purpose:  extra-fast text.  These routines 
  133.     give the programmer a way to do high-performance text.  Flash!
  134.  
  135.  
  136.  
  137.  
  138. =============================================================================
  139. === Programmer's Suite Technical Information ================================
  140. =============================================================================
  141.  
  142. All of the .c files in the Programmer's Suite will compile under either 
  143. Lattice or Aztec, and all of the .asm files will compile under either 
  144. Metacomco or Aztec.
  145.  
  146. There's a .doc file in each directory.  Contained in that file are 
  147. the programmer's notes and the autodoc headers for the functions.
  148.  
  149. Note that the C code is meant to be a tutorial and therefore isn't
  150. always optimized for performance.  Manx programmers who want maximum
  151. performance should dig in and switch the SHORTS to 16-bit, though with 
  152. the latest release of Manx C the difference between 16-bit int and 32-bit 
  153. int modes is less than before.
  154.  
  155. Be sure to see the section "Exercises for the Reader" below.
  156.  
  157. In most directories you can find these files:  makefile.lattice and 
  158. makefile.aztec.  If you are a make user you can rename one of these to 
  159. "makefile" and you'll be ready to go, though you will probably have to edit 
  160. the pathnames slightly to fit your own environment.  If you don't use 
  161. make, all the information you need to build your own make-like script 
  162. file is contained in the makefiles.  The Lattice .wth file is included 
  163. for your convenience.
  164.  
  165. I tried to keep the idiosyncracies of the languages out of the source 
  166. files, and succeeded almost completely.  Unfortunately, there's 
  167. one place where it matters whether you're using the Aztec assembler 
  168. or a standard assembler.  When compiling the XText routines, if you 
  169. use Aztec you must define the constant AZTEC in the xtext.i files.  
  170. If you don't use Aztec, you must make sure that AZTEC is not defined.
  171. If you use the most recent Manx release (3.40), you could rewrite
  172. this section of code to avoid making the declaration.
  173.  
  174. In general, it's a good idea to define the constants MANX and AZTEC
  175. when you are working with Aztec languages.  I believe that
  176. the Lattice folks guarantee that the constant LATTICE is defined
  177. for you.  For instance:
  178.  
  179.     #ifndef MANX
  180.     #define MANX
  181.     #endif
  182.  
  183.     #ifndef AZTEC
  184.     #define AZTEC
  185.     #endif
  186.  
  187.     main()
  188.     {
  189.     #ifdef MANX
  190.         printf("MANX found.\n");
  191.     #endif
  192.     #ifdef AZTEC
  193.         printf("AZTEC found.\n");
  194.     #endif
  195.     #ifdef LATTICE
  196.         printf("Error:  LATTICE found when MANX was wanted.\n");
  197.     #endif
  198.     }
  199.  
  200.  
  201. My makefiles refer to an executable AmigaDOS script file called "del",
  202. which tests for the existence of a file and deletes it if it exists.
  203. del looks like this:
  204.     .key file
  205.     if exists <file>
  206.     delete file
  207.     endif
  208. I use del to delete a previously-existing object file before attempting to
  209. compile a source file.  The advantage of this:  if the compilation fails,
  210. the link will fail too, and I am alerted that something went wrong.
  211. Often this isn't necessary, as I'm watching my window and see that 
  212. there's errors in a file.  However, when make compiles many files, 
  213. error messages may scroll out of the window and I may not be aware that
  214. something went wrong.  This way, I know which files failed and I can 
  215. invoke make again and observe the error messages directly.
  216.  
  217.  
  218.  
  219.  
  220. =============================================================================
  221. === Programmer's Suite Exercises for the Reader =============================
  222. =============================================================================
  223.  
  224. The following items have been left as exercises for the reader.  The 
  225. "features" listed below will probably be incorporated in a future revision
  226. of Book 1.
  227.  
  228. There are several ways that Book 1 could could be rewritten to support 
  229. the high-performance features of Manx.  Most notably, 16-bit ints aren't 
  230. supported; you'll have to do it yourself.  It was too much work for me 
  231. to support both a 32-bit Lattice version and a 16-bit Manx version of 
  232. this stuff, so I went with the default 32-bit.
  233.  
  234. If you use XText extensively, you might rewrite GetXTextSupport() to reuse 
  235. as much as possible from existing structures.  This might involve something 
  236. like passing the address of an existing XTextSupport structure (or NULL) to 
  237. the routine.
  238.  
  239. At 11K, the FileIO requester is overweight:  it has a *lot* of functionality, 
  240. and each feature costs; as a tutorial it sometimes does things in a 
  241. long-winded way for the sake of clarity; in fact the code has evolved over a 
  242. long period of time and so is no longer the most concise piece of code I've 
  243. ever written.  A good programmer could get in there and tighten 1 or 2K out 
  244. of the code easily.  This combined with switching to 16-bit integers could 
  245. result in easy big savings.  
  246.  
  247. Some of the routines have data that must be in chip memory.  The data that 
  248. must go into chip memory is collected in a "chipdata.c" file.  When using 
  249. the Lattice environment, the contents of this file can be located in chip 
  250. memory by using the ATOM tool on the chipdata.o file created by compiling 
  251. the chipdata.c file.  Under Manx, the only easy way to put some 
  252. pre-initialized data into chip memory is by putting *all* pre-initialized 
  253. data into chip memory.  This can be wasteful.  If you are a Manx user, you 
  254. might want to consider writing some chipdata transfer routine based on a 
  255. global Remember key.  
  256.  
  257. Most of the routines have string functions in a strings.c file.
  258. These string functions are usually redundant (both Lattice and Aztec have
  259. built-in string functions) and are included just for clarity; for example,
  260. the novice programmer will understand a function named CopyString() much 
  261. more readily than a function named strcpy().  You can strip out many of 
  262. the strings.c routines and save a few bytes.  To avoid editing all the 
  263. fileswhere string functions are called, you can create definitions such as:  
  264.     #define StringLength(s) strlen(s)
  265.     #define CopyString(s) strcpy(s)
  266.  
  267. The FileIO routines could use textual pattern matching when building the 
  268. name list, so that the program could specify, for instance, that only 
  269. those names ending in ".asm" would be displayed.  Probably the smartest 
  270. thing would be to duplicate AmigaDOS pattern matching, though you may 
  271. choose to do Unix-like pattern matching.  
  272.  
  273.