home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 594b.lha / Precognition_rel1 / Precognition.doc < prev    next >
Text File  |  1991-12-09  |  12KB  |  305 lines
  1.                   Precognition: A step beyond Intuition
  2.  
  3.                         Release 1, December 1991
  4.  
  5.  
  6. Precognition is an interface builder program for Intuition that allows
  7. you to create attractive, 3D-style interfaces like Workbench 2.0, but
  8. under AmigaDos 1.3!
  9.  
  10. You use Precognition as if it were a structured drawing or paint program,
  11. i.e.  simply drag the desired gadgets on to the window, size and move
  12. them using the mouse.  When you're done, Precognition writes the C code
  13. to generate that window.
  14.  
  15. Unlike other Amiga interface-building programs, Precognition not only
  16. writes the declarations for the gadgets,  but also writes the code for
  17. opening and closing the window, and the event loop itself. (For any
  18. non-trivial interface, the event loop is usually the hardest part to
  19. write.)
  20.  
  21. Precognition is also a set of programming utilities for use with
  22. Intuition that make manipulating gadgets easier.  The code generated by
  23. the Precognition Interface builder relies heavily on the Precognition
  24. utilities.
  25.  
  26. FOR ADVANCED AMIGA PROGRAMMERS:  Unlike Intuition, Precognition is not a
  27. separate process on the Amiga.  It is merely a collection of functions
  28. which manipulate gadgets and windows.  i.e.  it's designed to extend
  29. Intuition, not replace it.
  30.  
  31.  
  32.                    Starting the Program from Workbench
  33.  
  34. Simply double-click the Precognition icon.
  35.  
  36.  
  37.                     Starting the Program from the CLI
  38.  
  39. Set the stack to AT LEAST 40,000.  Then type "Precognition"
  40.  
  41.  
  42.                        Interlace vs. Non-Interlace
  43.  
  44. Precognition normally opens a screen with the same resolution as the
  45. Workbench screen.  You can force the screen to be (or not to be)
  46. interlaced via the tooltype "INTERLACE=".  Use "INTERLACE=YES" for
  47. interlace, "INTERLACE=NO" for non-interlace.
  48.  
  49.  
  50.                          The Application Window
  51.  
  52. Occupying most of the screen is a window titled "Application".  This is
  53. the window which you are designing.  You will add gadgets and graphics to
  54. this window by dragging them over from the "Gadgets" and "Graphics"
  55. windows.
  56.  
  57. To change the properties of the application window, select "Window
  58. Properties" from the "Edit" menu.  This will bring up the Window
  59. Properties requestor.  Using this requester, you can change the window
  60. title, the variable name, and the window gadgets (close, drag,
  61. front/back, resize).
  62.  
  63.  
  64.                             The Gadget Window
  65.  
  66. At the lower right side of the screen, there will be the "Gadgets" window
  67. which contains a set of buttons labelled with the different gadget types.
  68. To add one of these gadgets to the application window, simply move the
  69. mouse over the name of the gadget you wish,  press and hold the left
  70. mousebutton.  A gadget icon will be attached to your mouse pointer. Drag
  71. the gadget icon into the application window, and release the left
  72. mousebutton.
  73.  
  74.  
  75.                            The Graphics Window
  76.  
  77. To the left of the "Gadgets" window is the "Graphics" window which
  78. contains a set of buttons labelled with the different window graphics
  79. which can be added to the window.  S Currently, there aren't very many
  80. graphics. S  You add these to the window the same way you add a gadget,
  81. i.e. drag them.
  82.  
  83.  
  84.                             Selecting Objects
  85.  
  86. To move, resize, or edit an object in the application window, you must
  87. first select it.  To select an object, move the mouse pointer over that
  88. object, and press and release the left mousebutton.  The object should
  89. now be displayed in inverse video.
  90.  
  91. Multiple objects can be selected at the same time by holding down either
  92. shift key while pressing the left mousebutton.
  93.  
  94. Objects can be selected by lasso-ing them.  Hold the left mousebutton
  95. down on an area of the window where there are no objects.  Now move the
  96. mouse.  A selection box will follow your mouse.  When you release the
  97. mouse, any and all objects completely within the selection box will be
  98. selected.
  99.  
  100.  
  101.                      Changing the Size of an Object
  102.  
  103. To change the size of an object, move the mouse pointer to the edge or
  104. corner of the object, press and hold the left mousebutton.  The pointer
  105. image should change to a triangular arrow.  Now drag the corner or edge
  106. of the object to its new size and release the left mousebutton.
  107.  
  108. You can cancel a size-change by pressing by pressing the right
  109. mousebutton before releasing the left mousebutton.
  110.  
  111. NOTE: The size of some objects cannot be changed, e.g. a CheckBox is a
  112. fixed size.
  113.  
  114. If the pointer image becomes a hand you're not close enough to the edge
  115. of the object, or else this object does not size.
  116.  
  117. NOTE: You can only change the size of one object at a time.
  118.  
  119.  
  120.                              Moving Objects
  121.  
  122. You move objects on the application window the same way you move icons on
  123. the workbench screen.
  124.  
  125. To move one or more objects, first select the objects, and then move the
  126. mouse pointer to the  center  of one of the objects, press and hold the
  127. left mousebutton.  The pointer image will become a hand. Now drag the
  128. objects to their new location, and release the left mousebutton.
  129.  
  130. You can cancel a size-change by pressing by pressing the right
  131. mousebutton before releasing the left mousebutton.
  132.  
  133. If the pointer image becomes a triangular arrow instead of a hand you're
  134. too close to the edge of the object.
  135.  
  136.  
  137.                             Editing an Object
  138.  
  139. To edit the properties of an object, select the object, and then select
  140. Object Properties from the Edit menu.  This will bring up the object's
  141. property requestor.  This requestor will allow you to change the variable
  142. name for this object, its displayable title (if any), its size and
  143. location, and any other property which is applicable.
  144.  
  145.  
  146.                             Aligning Objects
  147.  
  148. You can align a set of objects by selecting those objects, and then
  149. selecting the appropriate option from the Align submenu of the Edit menu.
  150.  
  151.  
  152.                                 Grid Snap
  153.  
  154. You can also force alignment by turning on the Grid Snap.  Selecting Grid
  155. Snap Controls from the Edit menu will display the Grid Snap requestor,
  156. which allows you to set the grid snap parameters.
  157.  
  158. There are actually two separate grid snaps:
  159.  
  160.    Location Snap will force the upper-left corner of an object to be
  161.    on a grid when you drag it.
  162.  
  163.    Size Snap will force the corner or edge of an object to be on a
  164.    grid when you size it.
  165.  
  166.  
  167.                             Deleting Objects
  168.  
  169. To delete one or more objects, select those objects, and then select
  170. Delete from the Edit menu.
  171.  
  172. WARNING: Once you delete an object, its gone for good.
  173.  
  174. Sooner or later I'll get around to adding Cut/Copy/Paste instead of
  175. Delete.  (Sigh. So many improvements, so little time...)
  176.  
  177.  
  178.                              Generating Code
  179.  
  180. To generate code for the application window, select "Write Code" from the
  181. "Project" menu.  This will bring up a file requester for the C source
  182. code. Type or select a filename, and press the "OK" gadget.  Precognition
  183. will then write the C source code declarations for your window.
  184.  
  185. The name of the C function source code which Precognition generates will
  186. be "do_<Window_Name>()" where <Window_Name> is the variable name of the
  187. application window.  (Unless you change it, the application window is
  188. named "window", and so the function name is "do_window()".)
  189.  
  190.  
  191.                        About the Generated Code...
  192.  
  193. Precognition does not generate standard Intuition variables and function
  194. calls.  (This is because 1.3 Intuition does not have built-in 3-D buttons
  195. and scrolling lists and such)  Instead Precognition generates code which
  196. use special Precognition data types and functions.  In order for your
  197. program to use these functions, you must link your code with the file
  198. "Precognition.o", which contains all the special Precognition calls.
  199.  
  200. Throughout the code you will say lines which say "/* YOUR CODE HERE */".
  201. These are the areas which you the programmer must fill in.  Precognition
  202. inserts these statements to indicate that a User-interface event has
  203. occurred, and you should take the appropriate action.  EXAMPLE: If
  204. you create a window with an "OK" button, Precognition will generate the
  205. following statements:
  206.  
  207.       if (Respond( (Interactor*) &OK_button, &event) & CHANGED_STATE)
  208.       {  /* OK_button was hit. */
  209.          ; /* YOUR CODE HERE */
  210.       }
  211.  
  212. You, the programmer, need to supply the code to take the appropriate
  213. action when the OK button is pressed.  (Precognition doesn't know what
  214. you want to happen when "OK" is hit.)
  215.  
  216. The code as written should be compilable and linkable, although it
  217. won't do anything except have pretty buttons until you fill in the
  218. /* YOUR CODE HERE */ areas.  (NOTE: If you do not include a closebox
  219. on your window, then the event loop is infinite until you modify the
  220. code.)  Also included is the file "std_main.c" which supplies an
  221. example of a standard Amiga "main.c" file, including opening the
  222. appropriate libraries.
  223.  
  224. There's not a whole lot of documentation in the header files, and I
  225. apologize for that.  But I know that I won't have much free time in the
  226. next few months, and I wanted to get this release out the door.  So
  227. here's a few clues to get you started.
  228.  
  229. Precognition uses an OO paradigm via pointers-to-functions, which allows
  230. the same function to do different things to different objects
  231. ("polymorphism"). e.g.
  232.  
  233.    SetLocation(&BoolGadget, 10, 10 );
  234.  
  235. sets the location of a boolean gadget to be 10,10 in its window, while
  236.  
  237.    SetLocation( &pcgWindow, 10, 10 );
  238.  
  239. sets the location of the window to be 10, 10 on its screen.
  240.  
  241. All header files (most header files?) have an 'object genealogy' at the
  242. top of the file which describes the parents of the object.  e.g.
  243.  
  244.    Object<GraphicObject<OutlineBox
  245.  
  246. Says that object class OutlineBox is a descendent of class GraphicObject,
  247. which is a descendent of class Object.  Any function you can call on an
  248. Object or a GraphicObject, you can call on an OutlineBox.  To find out
  249. what operations an object supports, look at the prototypes in the objects
  250. header files, and all parent header files.
  251.  
  252.  
  253.                     Pre-Planned Product Improvements
  254.  
  255. This section describes the bells and whistles I plan on adding, but
  256. haven't gotten around to yet.
  257.  
  258.    * Cut/Copy/Paste
  259.  
  260.    * Radio Buttons
  261.  
  262.    * The ability to load and save a Precognition window in a non-source
  263.      code form.
  264.  
  265.    * More Graphic types, including a text object.
  266.  
  267.    * a Precognition shareable library.
  268.  
  269. How many out there would like to see a 2.0 version of Precognition (one
  270. that generated GadTools and/or BOOPSI calls instead of custom
  271. Precognition calls)?  How many would rather see Precognition stay 1.3
  272. compatible?  (I've only got so much free time folks, so please don't
  273. saying "both!")
  274.  
  275.  
  276.                             About the Author
  277.  
  278. ("He's a mild mannered defense contractor by day, but by night he turns
  279. into AMIGA MAN!")
  280.  
  281. I wrote Precognition over the course of the last year (1991) to
  282.  
  283.    * make programming Intuition easier (for me).
  284.  
  285.    * to experiment with object-oriented programming.  OO works very well
  286.      on user interface software.
  287.  
  288.    * to try and duplicate as much as possible the functionality of the
  289.      NeXT interface builder.  (I've never used the NeXT IB, but I've read
  290.      about it and saw a demo.  It looks slick.)
  291.  
  292. You can get in touch with me on USENET via:
  293.  
  294.    Lee_Robert_Willis@cup.portal.com
  295.  
  296. I'm also a member a few other Amiga BBS, but USENET is the only one I
  297. check regularly.
  298.  
  299. Or, when all else fails, you can reach me via U.S mail at:
  300.  
  301.       Lee Willis
  302.       590 Eleanora Dr.
  303.       Cuyagoga Falls, Ohio USA
  304.       44223-2732
  305.