Development Howtos

Howto communicate using the manager

The Manager allows different components of McBilliards to communicate in an indirect way. Throughout this document we will use M to denote an object of type Manager in McBilliards.

Basic Communication

Objects in McBilliards can send and recieve messages. Here a message is just an object of any type. Objects are sent using the command

M.mcbSend(obj);

Objects are recieved by functions of the form

public void mcbReceive(ObjectType obj){...do something...}

Sending a message: In order to send a message, your class only needs access to the Manager. The class can call
```
M.mcbSend(obj);
```
for an object of type ObjectType to send a message to all McBilliards components that implement
```
public void mcbReceive(ObjectType obj){...do something...}
```
that the manger knows about.
Receiving a message: In order to receive a message, your class must do the following:
1. Notify the manager that it wants to hear messages. This is done with the command
```
M.addListener(this);
```
  This only needs to be done once, when the object is created.
2. Implement mcbReceive. If a McBilliards component wishes to here objects of type ObjectType it should contain a function of type
```
public void mcbReceive(ObjectType obj){...do something...}
```
  A component can implement as many mcbReceive functions as it wishes.
3. Notify the manager when it wishes to stop listening to messages. This should be done when the object is destroyed. This is done by a call to M.remove(this);. For popups, McBilliards will call a function of the form
```
public void mcbCleanup(){...}
```
  when the popup is closed. Suppose your popup is a container that listens to messages and also has a subcomponent that listens to messages. Then, it might have a mcbCleanup() function like this:
```
public void mcbCleanup(){
	M.remove(this);
	M.remove(subcomponent);
}
```

Caching Messages

If you tell it to, the Manager can store the last message sent of a given type. In this way, a component still has access to this message even if it is "popped up" after the message was sent. (For example, this is used for tiles, colors, and points in the parameter space).

To indicate that the manager should cache message objects of ObjectType, use the command
```
M.mcbCache(ObjectType.class);
```
You might consider adding this line to the defaultCaching() line in the Manager to have it called when the manager starts.
To get the last message sent of type ObjectType use the command
```
((ObjectType)(M.mcbGet(ObjectType.class)))
```
(replace ObjectType with a class of your choice)
Some objects are cached by default. Currently, these are:
Color, Tile, Parameter, RationalTriangle, RationalLine, ViewingRectangleChange.

Common Message Types

While you can send any object you wish through mcbSend, some message types will be of interest to many components.

Tile: McBilliards thinks of a word as a Tile that can't be drawn. The manager has some convenience methods for handling words:
M.getWord();
and
M.setWord(word);
To select T to be the current Tile for McBilliards to think about use:
M.selectTile(T);
or alternately
M.mcbSend(T);
To listen for new tiles (or words) implement a method like this:
```
public void mcbReceive(Tile T){... word=T.getStringWord(); ...}
```
To get the currently selected tile call
M.getSelectedTile();
or equivalently
((Tile)(M.mcbGet(Tile.class))
Parameter: Use the Parameter class to get and receive points in the parameter space (triangles). To set the point in the parameter space you have several options (z is a Complex number, x and y are doubles):
M.setParameter(z);
or
M.setParameter(x,y);
or
M.mcbSend(new Parameter(z);
or
M.mcbSend(new Parameter(x,y);
all are equivalent. To obtain the current point use
M.getZ();
, which is more convenient than
((Parameter)(M.mcbGet(Parameter.class))).getZ();
To be notified when the point changes use a function of the form:
```
public void mcbReceive(Parameter p){
	Complex z=p.getZ();
	double x=p.getX(); // which equals z.x
	double y=p.getY();
	... do something ...
}
```
RationalTriangle: Used to keep track of a rational point in the parameter space. Get the current rational triangle with
```
((RationalTriangle)(M.mcbGet(RationalTriangle.class)))
```
You can listen for new rational triangles with
```
public void mcbReceive(RationalTriangle rt){...}
```
HelpDocument: Suppose a component in McBilliards wishes to display the help document "Files/Help/helpdoc.html" in the McBilliards documentation window. It should do a call of the form
```
M.mcbSend(new HelpDocument("helpdoc.html");
```
SettingsRequest: A class supporting the settings popup might have an inner class of the form
```
public static class ColorSettings implements Serializable {...}
```
To bring up the settings for this object, you can call
```
M.mcbSend(new SettingsRequest(ColorSettings.class));
```
Alternately, if you have an object of type ColorSettings called cs you can call
```
M.mcbSend(new SettingsRequest(cs.getClass()));
```
Color: A class wishing to be notified when the current color changes can implement
```
M.mcbRecieve(Color color);
```
To get the current color:
M.getColor();
or
(Color)mcbGet(Color.class);
You can set the color either with
M.setColor(color);
or
M.mcbSend(color);
BasicSearchResults: Used for sending search results
RationalLine: For changing the current rational line

PAT'S HOME >>>>> McBILLIARDS >>>>> DEVELOPMENT