home *** CD-ROM | disk | FTP | other *** search
/ AMIGA PD 1 / AMIGA-PD-1.iso / Programme_zum_Heft / Programmieren / Kurztests / ACE / archive / ace_reqed.lha / ReqEd / ReqEd.doc < prev    next >
Text File  |  1995-02-20  |  14KB  |  370 lines
  1.  
  2.                     -----------
  3.                     RedEd v1.11
  4.                     -----------
  5.  
  6.                     by
  7.  
  8.                 David J Benn
  9.                     
  10.                  20th February 1995
  11.  
  12.  
  13. CONTENTS
  14. --------
  15. ° Introduction
  16. ° Working with ReqEd
  17. ° Menu Summary
  18. ° Code Generation
  19. ° Limitations
  20. ° Known Bugs
  21. ° Future Work
  22. ° Contacting the Author
  23. ° Final Word
  24.  
  25.  
  26. Introduction
  27. ------------
  28. ReqEd is a freeware requester editor for use in conjunction with creating 
  29. ACE BASIC programs.
  30.  
  31. A requester (in this context, a window containing gadgets and text) can 
  32. be designed on-screen via menus and the mouse. Code, in the form of an 
  33. ACE subprogram, is then generated to render it, await gadget activity and 
  34. clean up.
  35.  
  36. The programmer can add code to act upon specific gadget activity and 
  37. possibly return information to the main program.
  38.  
  39. The motivation for this utility came from working with resource editors, 
  40. GUI designers and code generators on other platforms (eg. ResEdit, Resource 
  41. Workshop, ProtoGen) which make the creation of GUI elements much simpler 
  42. than using pencil and paper or trying to keep a design in one's head while 
  43. juggling coordinates to use when writing code.
  44.  
  45. ReqEd was written in ACE BASIC version 2.3, a freeware Amiga BASIC compiler, 
  46. developed by yours truly.
  47.  
  48. The program can be started from the Workbench or shell. No special 
  49. installation is required.
  50.  
  51.  
  52. Working with ReqEd
  53. ------------------
  54. When ReqEd is started, you are presented with an empty, bordered window
  55. and two menus: Project and Window. The former allows you to create, open
  56. and save requester projects as well as to toggle the Tool Bar. I'll come
  57. back to this in a little while. The Window menu's items are mainly used for 
  58. setting attributes of the requester window. It also contains an item which 
  59. switches the program from layout to preview mode.
  60.  
  61. In layout mode, window attributes can be modified, gadgets and text can be
  62. drawn, moved, resized and modified ad infinitum. These changes are reflected
  63. by appropriate changes in the window display. Gadgets are displayed as bevel
  64. boxes which look just like the gadgets they represent, but no text is shown
  65. in these "layout objects". Text is represented by layout guides which 
  66. indicate font height and horizontal text extent. If the main window has been 
  67. given a title bar, and an object is being created, moved or resized, the 
  68. layout object's coordinates will appear in the window's title bar (left, 
  69. top, right, bottom).
  70.  
  71. Immediately apparent when you start ReqEd is that the mouse pointer has 
  72. become a cross-hair. This makes drawing, moving and resizing layout objects 
  73. a little easier than it would be with the standard arrow pointer. The cross-
  74. hair pointer is only active when the main window is active.
  75.  
  76. When the program is switched to preview mode however the window and its 
  77. contents are displayed in WYSIWYG fashion. That is, preview mode shows you 
  78. what would result if you compiled and ran the code generated by ReqEd (with 
  79. a call to the subprogram added to the code) by rendering the gadgets and 
  80. text specified in layout mode.
  81.  
  82. The Tool Bar consists of a number of buttons which represent different GUI
  83. objects: button gadget, string gadget, longint gadget, potx (horizontal 
  84. slider) and poty (vertical slider) gadgets, text, plateau and panel. The 
  85. latter two are raised and recessed bevel-boxes respectively.
  86.  
  87. The Tool Bar is used to select one of these objects to layout on the main 
  88. window. When a tool gadget is selected (eg. String), the corresponding button 
  89. is shadowed until either you draw a rectangle (by holding down the left mouse 
  90. button and moving the mouse, then releasing the mouse button) in the main 
  91. window or you click the left mouse button once anywhere outside the main 
  92. window.
  93.  
  94. Static text, button text, string/longint gadget default values or maximum 
  95. slider values are then requested. For static text, an ASL font requester is 
  96. invoked so that font, style and background+foreground color can be determined.
  97.  
  98. Layout objects can be resized by clicking on a border and dragging the mouse. 
  99. Objects are resized from one edge at a time. Note that static text cannot be 
  100. resized since its height and length depends upon the actual text and font 
  101. used, so it is these that must be modified (see below).
  102.  
  103. Moving an object is achieved by clicking anywhere within the object's borders 
  104. (the borders are 3 pixels wide) and dragging the mouse. Once the object has 
  105. been moved to the desired location, release the mouse button.
  106.  
  107. If the object you are trying to move is embedded within a larger object (eg. a
  108. button inside a plateau's borders) and the larger object is selected when the 
  109. mouse pointer is inside the inner object's borders, release the left mouse 
  110. button and click again. You should now find that the object you wish to move 
  111. is selected. Clicking yet another time will shift the focus back to the larger 
  112. object. This phenomenon is a consequence of the method by which ReqEd matches 
  113. layout objects against mouse coordinates and the way in which the object list 
  114. is modified upon object selection. This can also affect the deletion and 
  115. modification of layout objects (see below). By toggling the objects as 
  116. described above, it is possible to predict which object will active with the 
  117. next mouse click. The need for such toggling when moving, deleting or modify-
  118. ing layout objects will be removed in a future release.
  119.   
  120. Deleting layout objects is achieved by first holding down the delete or 
  121. backspace keys before clicking anywhere within the object's borders. A message 
  122. box will be invoked to check whether you really want to complete the deletion.
  123.  
  124. Modifying layout objects is achieved by first holding down the return key 
  125. before clicking anywhere within the object's borders. A message box will be 
  126. invoked to check whether you really want to complete the modification. If so, 
  127. the text (and possibly font, style and color) or other value for the object 
  128. can then be modified via requesters. Note that neither plateaus nor panels may 
  129. be modified in this way since they have no text attribute.
  130.  
  131.  
  132. Menu Summary
  133. ------------
  134. When in layout mode:
  135.  
  136.   Project
  137.  
  138.       New      - Creates a new requester project, first checking whether 
  139.             the current project needs to be saved.
  140.  
  141.       Open...      - Opens an existing requester project (choose a file with
  142.             a .req extension), first checking whether the current 
  143.             project needs to be saved.
  144.  
  145.       Save...      - Saves the current requester project creating two files:
  146.             the project file (with a .req extension) and the code
  147.             file (with a .b extension). ReqEd asks for the file name
  148.             (without extension) and desired subprogram name. If no
  149.             changes have been made since the last invocation of Save
  150.             or Save As, no save will take place.
  151.               
  152.        Save As... - Same as Save option except that new file and sub names are 
  153.             always requested and a save _always_ takes place. Once the 
  154.             new file and requester names have been specified, they are 
  155.             used thereafter by the Save option.
  156.    
  157.       Tool Bar  - Toggles the Tool Bar window on or off.
  158.  
  159.       About...  - Displays an about box.
  160.  
  161.       Quit      - Quits ReqEd, first checking whether the current project 
  162.             needs to be saved.
  163.  
  164.  
  165.   Window
  166.  
  167.       Redraw      - If the requester window is resized, layout imagery can be 
  168.             destroyed. Selecting this item causes the window's contents
  169.             to be redrawn.
  170.  
  171.       Preview      - View the actual requester that has been created from
  172.             actions taken in layout mode.
  173.  
  174.  
  175.       Set ID... - Specify the ID number of the requester window.
  176.  
  177.      Set Title... - Specify the title text for the requester window's title
  178.             bar. To remove the title bar, enter no characters (not
  179.             even spaces) into the input requester. Entering spaces
  180.             will give you a blank title bar. Note that if certain
  181.             window attributes (see below) are activated (eg. sizing
  182.             gadget, close gadget, moveable) a title bar will appear
  183.             regardless of what you specify via the Set Title option.
  184.     
  185.   The remainder of the items in this menu toggle various window attributes.
  186.   See ref.doc in the ACE distribution under WINDOW for more about these 
  187.   attributes (or "type" values).
  188.  
  189.  
  190. When in preview mode:
  191.  
  192.   Project
  193.  
  194.       Exit        - Returns to layout mode.
  195.  
  196.  
  197. Code Generation
  198. ---------------
  199. When a project is saved, ReqEd produces an ACE source file containing a 
  200. subprogram with code to do the following:
  201.  
  202.     ° Open a window,
  203.     ° Render text, bevel-boxes and gadgets,
  204.     ° Wait for gadget activity and determine which gadget is activated,
  205.     ° Close gadgets and window.
  206.  
  207. You are, of course, free to modify this code in whatever way you wish. Helpful
  208. comments are generated to delineate functional sections. Here's a typical SUB
  209. generated by ReqEd:
  210.  
  211.     SUB MyReq
  212.     SHORTINT theGadget, n
  213.         WINDOW 9,"",(155,54)-(455,179),10
  214.         {* RENDER GADGETS, BEVEL-BOXES AND TEXT *}
  215.         FONT "topaz.font",8 : STYLE 6 : COLOR 1,0 : PENUP : SETXY 46,18
  216.         PRINT "This is a test requester";
  217.         FONT "ruby.font",12 : STYLE 2 : COLOR 1,3 : PENUP : SETXY 91,48
  218.         PRINT "Simple eh?";
  219.         GADGET 255,ON,"Quit",(115,85)-(163,103),BUTTON
  220.         {* GADGET HANDLING CODE STARTS HERE *}
  221.         GADGET WAIT 0
  222.         theGadget = GADGET(1)
  223.         {* CLEAN UP *}
  224.         FOR n=255 TO 255 STEP -1
  225.             GADGET CLOSE n
  226.         NEXT
  227.         WINDOW CLOSE 9 
  228.     END SUB
  229.  
  230. When called, this SUB would render a window with a close gadget and title bar 
  231. (but no title), two static text items, and a "Quit" button. The code would then
  232. wait for any gadget to be activated (including the window's close gadget). The
  233. gadget's ID is then retrieved before the gadgets and window are closed.
  234.  
  235. Examination of the above code reveals a couple of points of interest. First, 
  236. PENUP and SETXY (turtle graphics commands) are used to position text at a 
  237. pixel level which LOCATE cannot do. Second, gadget IDs start from 255 and go 
  238. down to 1, the assumption being that in the rest of your application you will 
  239. be starting the gadget count from 1. Unless you use a _lot_ of gadgets in a 
  240. requester, you are unlikely to cause any clashes with gadgets used elsewhere 
  241. in your program.
  242.  
  243. Here's an example of how the above subprogram can be modified to handle gadgets
  244. in a more substantial fashion:
  245.  
  246.     CONST true = -1&, false = 0&
  247.  
  248.     SUB MyReq
  249.     SHORTINT theGadget, n
  250.     LONGINT finished
  251.         WINDOW 9,,(155,54)-(455,179),10
  252.         {* RENDER GADGETS, BEVEL-BOXES AND TEXT *}
  253.         FONT "topaz.font",8 : STYLE 6 : COLOR 1,0 : PENUP : SETXY 46,18
  254.         PRINT "This is a test requester";
  255.         FONT "ruby.font",12 : STYLE 2 : COLOR 1,3 : PENUP : SETXY 91,48
  256.         PRINT "Simple eh?";
  257.         GADGET 255,ON,"Quit",(115,85)-(163,103),BUTTON
  258.         {* GADGET HANDLING CODE STARTS HERE *}
  259.         finished = false
  260.         '..Loop until close gadget is clicked.
  261.         REPEAT
  262.             GADGET WAIT 0
  263.             theGadget = GADGET(1)
  264.             CASE
  265.           theGadget = 256 : finished = true
  266.               theGadget = 255 : MsgBox "You clicked the Quit gadget","Continue"
  267.             END CASE
  268.         UNTIL finished
  269.         {* CLEAN UP *}
  270.         FOR n=255 TO 255 STEP -1
  271.             GADGET CLOSE n
  272.         NEXT
  273.         WINDOW CLOSE 9 
  274.     END SUB
  275.  
  276. Other possible modifications include returning the knob position of a slider
  277. gadget or the value entered into a string or longint gadget, back to the main
  278. program. This could be done either by assigning a value to the subprogram, eg:
  279.  
  280.     MyReq = GADGET(3)    '..return slider's knob position.
  281.  
  282. or by using SHARED variables or pass-by-reference parameters. See ace.doc's
  283. section on Subprograms for more about these mechanisms.
  284.  
  285. More complex gadget handling may need to be farmed off to another subprogram,
  286. passing such parameters to it as the gadget's ID (and perhaps other informat-
  287. ion).
  288.  
  289. You are, of course, free not to use a subprogram at all, instead choosing to
  290. use the code generated by ReqEd in a (GOSUB'd) subroutine or as inlined code
  291. (ie. in the main program somewhere). I recommend the use of SUBs for the sake
  292. of modularity however.
  293.     
  294.     
  295. Limitations
  296. -----------
  297. ° The font used in gadgets cannot yet be specified and so defaults to that
  298.   set in preferences. The next release of ACE will enable ReqEd to allow a
  299.   gadget's text font to be specified.
  300.  
  301. ° ReqEd currently always provides a default value of zero for LONGINT gadgets.
  302.   This can of course be removed from the generated code.
  303.   
  304. ° Currently, string and longint gadgets may only return their results when the 
  305.   return key has been pressed. The next version of ACE will allow the string
  306.   or long integer value of these gadgets to be retrieved at any time. In like
  307.   manner, the knob position of slider gadgets in ACE may only be accessed when
  308.   the knob has been moved, but this value will be made accessible at any time, 
  309.   in the next release of ACE. Future releases of ReqEd will take advantage of 
  310.   these new capabilities as they appear.
  311.  
  312.  
  313. Known Bugs
  314. ----------
  315. ° None known.
  316.  
  317.  
  318. Future Work
  319. -----------
  320. Likely additions to ReqEd include:
  321.  
  322. ° Automatic redrawing of window contents when layouts become obscured through 
  323.   window resizing.
  324.  
  325. ° File and font requester defaults based upon previous values.
  326.  
  327. ° Autogrid. This will allow objects to be aligned more easily by increasing
  328.   the coarseness of layout object movement.
  329.  
  330. ° Ability to copy and paste existing objects.
  331.  
  332. ° Simple drawing tools and pixel editor for additional button/other imagery.
  333.  
  334. ° Vertical and horizontal centering of layout objects.
  335.  
  336. ° Greater control over gadget attributes (eg. borderless button setting). 
  337.  
  338.  
  339. Contacting the Author
  340. ---------------------
  341. You can reach me via:
  342.  
  343.     Internet:    D.Benn@appcomp.utas.edu.au
  344.     
  345.     CompuServe:    100033,605
  346.  
  347.     Phone:        (003) 261 461 [AH]
  348.             (003) 243 529 [wk]    
  349.  
  350.     Snail Mail:    c/- Dept. of Applied Computing and Mathematics,
  351.             University of Tasmania at Launceston,
  352.             Newnham Drive, Newnham, Tasmania, 7248,
  353.             Australia.
  354.  
  355. If you are a Web surfer you might want to check out the ACE Home Page. The URL is:
  356.  
  357.     http://www.appcomp.utas.edu.au/users/dbenn/
  358.  
  359.  
  360. Final Word
  361. ----------
  362. Thanks to Peter Zielinski for finding and modifying ReqEd's icon, for testing
  363. an early version and for making suggestions for improvement (eg.mouse pointer 
  364. coordinates display). Basil Barnes viewed an even earlier version of the program
  365. and made useful suggestions (eg. copy and paste of layout objects).
  366.  
  367. I hope you find ReqEd useful. All comments are welcome.
  368.  
  369.                     ---oOo---
  370.