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