// simpleObserverSwarm2

             ADDING PROBES AND PROBE DISPLAYS ON OBJECTS


Now we add a very useful observation object. Probes are just what
their name implies - probe-like access directly to the internals
of any object in Swarm. The Probe Library allows one to, effectively
break the hiding away of information within objects inaccesibly.

A Probe can be attached to any object in Swarm, and all of its internal
state and methods can be accessed and manipulated from the outside.
This is both incredibly useful and incredibly dangerous.

However, probes are essential. We can never anticipate in advance
everything what we might want to know about an object's state. And 
it would be inefficient to provide a "get" method for every internal 
variable on every object. Hence probes.

Probing is based on ProbeMaps. There is a probeMap for every class in 
the system, although they don't really exist until someone asks for one. 
ProbeMaps establish the mapping from an object's class to the location of 
variables in an instance's internal data-structure.

Therefore, every aspect of internal state is potentially observable 
in swarm.

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

main.m

Again, nothing new here - we build the ObserverSwarm and start it.


ObserverSwarm.h and ObserverSwarm.m

In createBegin, we create an empty probeMap for the ObserverSwarm class, 
so that we can customize it to look only at the variables and methods we 
are interested in. Without customizing, one gets *everything*. We customize 
the probeMap to show us the one variable of interest, displayFrequency, and 
then install the probeMap in the probeLibrary. Fro now on, anytime anyone 
wants to probe the ObserverSwarm class, they will get this map.

In buildObjects, we create "probeDisplays", probes attached to graphic 
widgets that will show object's internal state on the terminal screen. 
ProbeDisplays can be typed into, to change object's state, and the objects 
methods can be invoked, asking them to do things. by creating a ProbeDisplay 
on the ModelSwarm, all of the models' parameters are displayed on the screen, 
where they can be altered. 

This is where we halt the process with a stop message to the control panel. 
Once we have displayed the Model parameters, we give the user a chance to 
alter them before going on to actually construct the model.

We then go on to the normal construction of ObserverSwarm objects. At the end 
of buildObjects, however, we send a message to the worldRaster object, which 
enables it to make a probeDisplay for any object that it knows about on the 
screen. Thus, we will be able to "click" on the bugs that we've been running, 
and get to look inside of them and/or change their state.



ModelSwarm.h and ModelSwarm.m

We add probeMaps within the ModelSwarm. All of the Model's parameters will 
be available for inspection and alteration.



Running the model....

  Once you have started the model running, stop it by clicking on the 
controlPanel stop button, and then click on one of the bugs on the screen. 
You will get a window listing its internal state, (not much more than xPos, 
yPos). We did *not* create a custom probeMap for the Bug class, so you will 
see a complete probeMap for it, with both variables and methods shown. 

  Some of the entries listed in the probeDisplay for the Bug are also objects. 
If you click on the string "Grid2d" in the slot for the "world" variable with 
the right mouse-button, you will get a probeDisplay for a Grid2d.

  In the upper left corner of a probeDisplay you will see the class-name 
of the object being probed, highlited in blue. If you click the right 
mouse-button on that name, you will create another kind of probeDisplay. 
It looks similar to the previous one, except that there is a new button in 
the upper right corner with some connected green boxes. If you click on this 
with the left mouse-button, you will extend the probeDisplay to show the
super class of the object. It too will have the green-box button, which you 
can click on again, and so on, to see the object's inheritance hierarchy all 
the way up to "Object" the root of all Swarm objects.

  For instance, a "Bug" is a subclass of "SwarmObject," which is a subclass 
of "CreateDrop," which is a subclass of "CreateDrop_s," which is a subclass 
of "Customize_s," which is a subclass of "Object_s," which is a subclass of 
"Object."  You can see what methods and variables an object has by virtue of 
inheriting from all of its super classes. 

  To get rid of any pobeDisplay, or any frame in a probeDisplay, just click 
the red circle-and-X button in the upper right-hand corner of the display. 

  The probeDisplays will also allow you to alter the internal contents
of an object. For instance you can alter the X and Y coordinates of
a Bug. When the simulation is stopped, click with the left mouse-button
in the field for the xPos in the probeDisplay for a bug. The entry
becomes highlited, and you can type in some other (legal) value.  Type 
"return" to enter the value. You can do the same for the "yPos" value. 
Be sure to hit "return" after you have changed an entry. When you restart 
the simulation, the bug will appear at the new coordinate values. 

  You should not attempt to change entries that do not change during
the simulation, like a Bug's pointer to it's foodSpace, or its idea 
of the size of its world.

 With the probeDisplays, you can also invoke methods on objects. You 
could have changed the X and Y coordinates of the Bug by entering values 
in the argument slots next to the setX: and Y: labels in the Bug's 
probeDisplay, and then psuhing the setX: button. 

Try this: 

  Click with the right mouse-button on the string "FoodSpace" in
the Bug's probeDisplay. You will get a probeDisplay on the foodSpace.
This probeDisplay has one entry: a method probe on the "seedFoodWithProb:
method of FoodSpace. If you enter 1.0 ("return"!) into the argument
slot to the right of the button, and then click the button, when
you start the simulation again, you will have reseeded the foodSpace 
with food at every site.

  You can try pulling up probeDisplays on any object in the simulation
this way, altering their variables and invoking their methods. 

  Thus, the probe mechanism is a very powerful tool for observing the
detailed state of a simulation, and for interacting with any object
in the artificial world of the simulation. 




NEXT -> simpleExperBug


