Amiga Format 91/af091a.adf/af91a3.lzx/ReqEd/ReqEd.doc

Text File | 2018-05-24 | 14KB | 370 lines

                    -----------
                    RedEd v1.12
                    -----------

                    by

                David J Benn

                 12th September 1996


CONTENTS
--------
° Introduction
° Working with ReqEd
° Menu Summary
° Code Generation
° Limitations
° Known Bugs
° Future Work
° Contacting the Author
° Final Word


Introduction
------------
ReqEd is a freeware requester editor for use in conjunction with creating
ACE BASIC programs.

A requester (in this context, a window containing gadgets and text) can
be designed on-screen via menus and the mouse. Code, in the form of an
ACE subprogram, is then generated to render it, await gadget activity and
clean up.

The programmer can add code to act upon specific gadget activity and
possibly return information to the main program.

The motivation for this utility came from working with resource editors,
GUI designers and code generators on other platforms (eg. ResEdit, Resource
Workshop, ProtoGen) which make the creation of GUI elements much simpler
than using pencil and paper or trying to keep a design in one's head while
juggling coordinates to use when writing code.

ReqEd was written in ACE BASIC version 2.3, a freeware Amiga BASIC compiler,
developed by yours truly.

The program can be started from the Workbench or shell. No special
installation is required.


Working with ReqEd
------------------
When ReqEd is started, you are presented with an empty, bordered window
and two menus: Project and Window. The former allows you to create, open
and save requester projects as well as to toggle the Tool Bar. I'll come
back to this in a little while. The Window menu's items are mainly used for
setting attributes of the requester window. It also contains an item which
switches the program from layout to preview mode.

In layout mode, window attributes can be modified, gadgets and text can be
drawn, moved, resized and modified ad infinitum. These changes are reflected
by appropriate changes in the window display. Gadgets are displayed as bevel
boxes which look just like the gadgets they represent, but no text is shown
in these "layout objects". Text is represented by layout guides which
indicate font height and horizontal text extent. If the main window has been
given a title bar, and an object is being created, moved or resized, the
layout object's coordinates will appear in the window's title bar (left,
top, right, bottom).

Immediately apparent when you start ReqEd is that the mouse pointer has
become a cross-hair. This makes drawing, moving and resizing layout objects
a little easier than it would be with the standard arrow pointer. The cross-
hair pointer is only active when the main window is active.

When the program is switched to preview mode however the window and its
contents are displayed in WYSIWYG fashion. That is, preview mode shows you
what would result if you compiled and ran the code generated by ReqEd (with
a call to the subprogram added to the code) by rendering the gadgets and
text specified in layout mode.

The Tool Bar consists of a number of buttons which represent different GUI
objects: button gadget, string gadget, longint gadget, potx (horizontal
slider) and poty (vertical slider) gadgets, text, plateau and panel. The
latter two are raised and recessed bevel-boxes respectively.

The Tool Bar is used to select one of these objects to layout on the main
window. When a tool gadget is selected (eg. String), the corresponding button
is shadowed until either you draw a rectangle (by holding down the left mouse
button and moving the mouse, then releasing the mouse button) in the main
window or you click the left mouse button once anywhere outside the main
window.

Static text, button text, string/longint gadget default values or maximum
slider values are then requested. For static text, an ASL font requester is
invoked so that font, style and background+foreground color can be determined.

Layout objects can be resized by clicking on a border and dragging the mouse.
Objects are resized from one edge at a time. Note that static text cannot be
resized since its height and length depends upon the actual text and font
used, so it is these that must be modified (see below).

Moving an object is achieved by clicking anywhere within the object's borders
(the borders are 3 pixels wide) and dragging the mouse. Once the object has
been moved to the desired location, release the mouse button.

If the object you are trying to move is embedded within a larger object (eg. a
button inside a plateau's borders) and the larger object is selected when the
mouse pointer is inside the inner object's borders, release the left mouse
button and click again. You should now find that the object you wish to move
is selected. Clicking yet another time will shift the focus back to the larger
object. This phenomenon is a consequence of the method by which ReqEd matches
layout objects against mouse coordinates and the way in which the object list
is modified upon object selection. This can also affect the deletion and
modification of layout objects (see below). By toggling the objects as
described above, it is possible to predict which object will active with the
next mouse click. The need for such toggling when moving, deleting or modify-
ing layout objects will be removed in a future release.

Deleting layout objects is achieved by first holding down the delete or
backspace keys before clicking anywhere within the object's borders. A message
box will be invoked to check whether you really want to complete the deletion.

Modifying layout objects is achieved by first holding down the return key
before clicking anywhere within the object's borders. A message box will be
invoked to check whether you really want to complete the modification. If so,
the text (and possibly font, style and color) or other value for the object
can then be modified via requesters. Note that neither plateaus nor panels may
be modified in this way since they have no text attribute.


Menu Summary
------------
When in layout mode:

  Project

      New      - Creates a new requester project, first checking whether
            the current project needs to be saved.

      Open...      - Opens an existing requester project (choose a file with
            a .req extension), first checking whether the current
            project needs to be saved.

      Save...      - Saves the current requester project creating two files:
            the project file (with a .req extension) and the code
            file (with a .b extension). ReqEd asks for the file name
            (without extension) and desired subprogram name. If no
            changes have been made since the last invocation of Save
            or Save As, no save will take place.

       Save As... - Same as Save option except that new file and sub names are
            always requested and a save _always_ takes place. Once the
            new file and requester names have been specified, they are
            used thereafter by the Save option.

      Tool Bar  - Toggles the Tool Bar window on or off.

      About...  - Displays an about box.

      Quit      - Quits ReqEd, first checking whether the current project
            needs to be saved.


  Window

      Redraw      - If the requester window is resized, layout imagery can be
            destroyed. Selecting this item causes the window's contents
            to be redrawn.

      Preview      - View the actual requester that has been created from
            actions taken in layout mode.


      Set ID... - Specify the ID number of the requester window.

     Set Title... - Specify the title text for the requester window's title
            bar. To remove the title bar, enter no characters (not
            even spaces) into the input requester. Entering spaces
            will give you a blank title bar. Note that if certain
            window attributes (see below) are activated (eg. sizing
            gadget, close gadget, moveable) a title bar will appear
            regardless of what you specify via the Set Title option.

  The remainder of the items in this menu toggle various window attributes.
  See ref.doc in the ACE distribution under WINDOW for more about these
  attributes (or "type" values).


When in preview mode:

  Project

      Exit        - Returns to layout mode.


Code Generation
---------------
When a project is saved, ReqEd produces an ACE source file containing a
subprogram with code to do the following:

    ° Open a window,
    ° Render text, bevel-boxes and gadgets,
    ° Wait for gadget activity and determine which gadget is activated,
    ° Close gadgets and window.

You are, of course, free to modify this code in whatever way you wish. Helpful
comments are generated to delineate functional sections. Here's a typical SUB
generated by ReqEd:

    SUB MyReq
    SHORTINT theGadget, n
        WINDOW 9,"",(155,54)-(455,179),10
        {* RENDER GADGETS, BEVEL-BOXES AND TEXT *}
        FONT "topaz.font",8 : STYLE 6 : COLOR 1,0 : PENUP : SETXY 46,18
        PRINT "This is a test requester";
        FONT "ruby.font",12 : STYLE 2 : COLOR 1,3 : PENUP : SETXY 91,48
        PRINT "Simple eh?";
        GADGET 255,ON,"Quit",(115,85)-(163,103),BUTTON
        {* GADGET HANDLING CODE STARTS HERE *}
        GADGET WAIT 0
        theGadget = GADGET(1)
        {* CLEAN UP *}
        FOR n=255 TO 255 STEP -1
            GADGET CLOSE n
        NEXT
        WINDOW CLOSE 9
    END SUB

When called, this SUB would render a window with a close gadget and title bar
(but no title), two static text items, and a "Quit" button. The code would then
wait for any gadget to be activated (including the window's close gadget). The
gadget's ID is then retrieved before the gadgets and window are closed.

Examination of the above code reveals a couple of points of interest. First,
PENUP and SETXY (turtle graphics commands) are used to position text at a
pixel level which LOCATE cannot do. Second, gadget IDs start from 255 and go
down to 1, the assumption being that in the rest of your application you will
be starting the gadget count from 1. Unless you use a _lot_ of gadgets in a
requester, you are unlikely to cause any clashes with gadgets used elsewhere
in your program.

Here's an example of how the above subprogram can be modified to handle gadgets
in a more substantial fashion:

    CONST true = -1&, false = 0&

    SUB MyReq
    SHORTINT theGadget, n
    LONGINT finished
        WINDOW 9,,(155,54)-(455,179),10
        {* RENDER GADGETS, BEVEL-BOXES AND TEXT *}
        FONT "topaz.font",8 : STYLE 6 : COLOR 1,0 : PENUP : SETXY 46,18
        PRINT "This is a test requester";
        FONT "ruby.font",12 : STYLE 2 : COLOR 1,3 : PENUP : SETXY 91,48
        PRINT "Simple eh?";
        GADGET 255,ON,"Quit",(115,85)-(163,103),BUTTON
        {* GADGET HANDLING CODE STARTS HERE *}
        finished = false
        '..Loop until close gadget is clicked.
        REPEAT
            GADGET WAIT 0
            theGadget = GADGET(1)
            CASE
          theGadget = 256 : finished = true
              theGadget = 255 : MsgBox "You clicked the Quit gadget","Continue"
            END CASE
        UNTIL finished
        {* CLEAN UP *}
        FOR n=255 TO 255 STEP -1
            GADGET CLOSE n
        NEXT
        WINDOW CLOSE 9
    END SUB

Other possible modifications include returning the knob position of a slider
gadget or the value entered into a string or longint gadget, back to the main
program. This could be done either by assigning a value to the subprogram, eg:

    MyReq = GADGET(3)    '..return slider's knob position.

or by using SHARED variables or pass-by-reference parameters. See ace.doc's
section on Subprograms for more about these mechanisms.

More complex gadget handling may need to be farmed off to another subprogram,
passing such parameters to it as the gadget's ID (and perhaps other informat-
ion).

You are, of course, free not to use a subprogram at all, instead choosing to
use the code generated by ReqEd in a (GOSUB'd) subroutine or as inlined code
(ie. in the main program somewhere). I recommend the use of SUBs for the sake
of modularity however.


Limitations
-----------
° The font used in gadgets cannot yet be specified and so defaults to that
  set in preferences. The next release of ACE will enable ReqEd to allow a
  gadget's text font to be specified.

° ReqEd currently always provides a default value of zero for LONGINT gadgets.
  This can of course be removed from the generated code.

° Currently, string and longint gadgets may only return their results when the
  return key has been pressed. The next version of ACE will allow the string
  or long integer value of these gadgets to be retrieved at any time. In like
  manner, the knob position of slider gadgets in ACE may only be accessed when
  the knob has been moved, but this value will be made accessible at any time,
  in the next release of ACE. Future releases of ReqEd will take advantage of
  these new capabilities as they appear.


Known Bugs
----------
° None known.


Future Work
-----------
Likely additions to ReqEd include:

° Automatic redrawing of window contents when layouts become obscured through
  window resizing.

° File and font requester defaults based upon previous values.

° Autogrid. This will allow objects to be aligned more easily by increasing
  the coarseness of layout object movement.

° Ability to copy and paste existing objects.

° Simple drawing tools and pixel editor for additional button/other imagery.

° Vertical and horizontal centering of layout objects.

° Greater control over gadget attributes (eg. borderless button setting).


Contacting the Author
---------------------
You can reach me via:

    Internet:    [e-mail]

    CompuServe:    100033,605

    Phone:        [phone] [AH]
            [phone] [wk]

    Snail Mail:    c/- Dept. of Applied Computing and Mathematics,
            University of Tasmania at Launceston,
            Newnham Drive, Newnham, Tasmania, 7248,
            Australia.

If you are a Web surfer you might want to check out the ACE Home Page. The URL is:

    http://www.appcomp.utas.edu.au/users/dbenn/


Final Word
----------
Thanks to Peter Zielinski for finding and modifying ReqEd's icon, for testing
an early version and for making suggestions for improvement (eg.mouse pointer
coordinates display). Basil Barnes viewed an even earlier version of the program
and made useful suggestions (eg. copy and paste of layout objects).

I hope you find ReqEd useful. All comments are welcome.

                    ---oOo---