Swarm GUI Notes

[Manor Askenazi]

                Swarm GUI Notes
                ---------------

In order to introduce some of the more subtle aspects of the Swarm GUI
the following tutorial ensures that the user experiments with all the 
bells and whistles of the interface in one Heatbug session. Even if you 
have played with heatbugs before, we recommend that you run through this 
checklist - you may have missed some GUI-capabilities (especially the 
ones described in points 7 through 22).

-----------------------------------------------------------------------

--------

1. Run heatbugs.

--------

   /-----------------------\
   |Changing the Variables |
   \-----------------------/

2. Move the cursor onto the entry for the variable numBugs in the 
   HeatbugModelSwarm and click the first mousebutton (the leftmost
   button).

   The entry should now appear selected so that if you type a replacement
   value the previous one is completely overwritten.
 
   If you only wish to change a subsection of the string simply move the
   cursor to the appropriate location and use the delete key as required.
   You can also re-select an area for deletion by pressing MB1 (the first
   mouse button) and moving the cursor over the text.

3. Press <Return>.
    
   The borders of the entry should change to red until you release the
   Return key. This is done to inform the user that the change in the
   variable has been recorded. If the user does not press return the 
   variable will not be updated!!!

4. Press Tab.

   The next variable in the list should now be selected.

5. Press Shift-Tab. 

   You should be back on numBugs.

--------

6. Press go on the ControlPanel. Wait a while then press stop.

--------

   /------------------------------\
   |Zooming/Highlighting the Graph|
   \------------------------------/

7. Go to the Unhappiness graph. Click MB1. Move the cursor diagonally,
   and click MB1 again.

   You should see that the area included within the rectangular region
   you have selected has now been zoomed into.

   You can repeat this operation to zero in on some interesting point
   in the graph, or you can press MB3 (the rightmost mousebutton to 
   return to the previous zoom level).

8. Put the cursor over the entry in the graph legend that says "u".
   
   You should see that the line in the graph has now changed color.
   This is useful when you have a graph with many lines and you want
   to inspect one of the lines and how it changes relative to the 
   others...

--------

   /--------------------------------------------------------\
   | Getting a Probe To a Bug, a Variable or a Return Value |
   \--------------------------------------------------------/


9.  Go to the heatworld window. Click MB3 on a bug.

    A window should appear which is a ProbeDisplay onto the selected bug.
 
10. Press MB3 over the entry area for the variable world. 

    Since the heatspace variable is an object, you should now get a 
    ProbeDisplay onto the world object.
  
    Click on the little square button at the top righthand corner of this
    new probe to dismiss it. 

11. On the probe you generated for the heatbug, go to the top lefthand 
    corner. You will see a well with the word heatbug in it. Press MB3
    with the cursor above that area. 

    You should get a probe onto the same heatbug, with a slightly different
    interface. In particular, you will notice an additional green button
    at the toplefthand corner of the probe. This button allows you to look
    at the methods and instance variables due to the superclasses of heatbug.

    Press this "superclass" button.

    Do this repeatedly until you get to the highest possible class (namely
    Object).

-------

12. Before we proceed, dismiss the original ProbeDisplay onto the selected 
    heatbug. (To avoid confusion later). You should be left with the 
    CompleteProbeDisplay you have just created in step 11.

-------

13. Now click on the copy button in the Object class of the heatbug's 
    CompleteProbeDisplay.

    You will see a return value appear on the left of the button.

    Since this return value is an object we can probe it using the MB3
    button, so if you click MB3 over this value you should get a ProbeDisplay
    onto this object which is a copy of the original bug.

14. Once you have made a copy of the original bug, dismiss the 
    CompleteProbeDisplay to that original bug. Note that pressing on the
    red-square button on any class but the lowest in the hierarchy will 
    simply cause that particular class to be removed, not the entire window!

-------

   /-----------------------------------\
   | Drag&Drop Capabilities on Objects |
   \-----------------------------------/

15. Press go on the control panel.

    Note that although the simulation is proceeding, the x and y value in
    the newly made copy of the heatbug are not changing. In other words, 
    we have made a new bug but it has not been added into the simulation!

    We will now attempt to add this bug into the simulation but first we
    will make three changes on the bug so as to make it more recognizable
    when it appears in the simulation.

16. Change the x and y coordinates to be (10,10).

17. Change the bugColor entry to be 65 (which in this particular simulation
    means white).

    Note that the original value of color will have read: 64 '@'      
    This is because the bugColor variable is defined as a Color type (which
    is essentially an unsigned char).

    Many programmers use chars/unsigned chars to represent small numbers. 
    Therefore, by default we display both forms of the variable (as a number 
    and as a character). There are ways to customize which form is required 
    (see the documentation on the VarProbe class for details).

18. Now go to the 'well area' described earlier (at the toplefthandcorner
    of the ProbeDisplay. If you click MB1 on this area (and keep the button
    depressed) you will see a little rectangular representation of the but
    appear underneath your cursor.

19. Move this little object-representation over the argument-entry for the
    addHeatbug method on the HeatbugModelSwarm. When the bug is over this 
    entry the text within it should turn green. This means that if you 
    release MB1 the bug will be placed as an argument to this method.

    If you do this you will see that the entry now contains a value.

20. Now, since there is an argument for the method addHeatbug, you should be
    able to press the button for this method (normally you would get a beeping
    noise).

21. If you press go on the control panel you should now see this bug appear at
    the toplefthandcorner of the heatworld.

22. In general, any entry which contains an object can be MB1-clicked to get
    a drag&drop representation of the object. An MB3 click should get you a
    probe to the object.