com.hdcookbook.grin
Class Director

java.lang.Object
  com.hdcookbook.grin.Director

Direct Known Subclasses:

GenericDirector, RyanDirector

public class Director
extends java.lang.Object

This class is a supertype that xlets can subclass to interact with a show. The java_command commands can access the directory and do a downcast as a way of getting into the xlet. Director also defines various protected methods to notify the xlet of Show state changes, and to allow the xlet to insert itself into the animation loop. Shows that are created without a director will be given a default director that is a direct instance of this class.

Author:

Bill Foote (http://jovial.com)

Constructor Summary

Director()
Create a new Director.

Method Summary

Feature	getFeature(java.lang.String name) Get the named public feature from the show we're managing.
Command	getNamedCommand(java.lang.String name) Get the named public command (or command list) from the show we're managing.
Feature	getPart(Assembly assembly, java.lang.String partName) Look up the named part in the given assembly.
Segment	getSegment(java.lang.String name) Look up the given named public segment in the show we're managing.
Show	getShow() Get the show we're managing.
void	notifyAssemblyPartSelected(Assembly assembly, Feature newPart, Feature oldPart, boolean assemblyIsActive) Notify the director that a new part has been selected within an assembly.
void	notifyDestroyed() Notifies the director that the underlying show has been destroyed.
void	notifyNextFrame() Notify the director that the model is moving to the next frame.
void	notifySegmentActivated(Segment newSegment, Segment oldSegment) Notify the director that a new segment has been activated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Director

public Director()

Create a new Director.

Method Detail

getShow

public Show getShow()

Get the show we're managing.

getFeature

public Feature getFeature(java.lang.String name)

Get the named public feature from the show we're managing. If not found and if we're in debug mode, trigger an assertion failure. This method does a search through the show's features using a hashtable lookup, so it shouldn't be called frequently; it's best used during initialization.

getNamedCommand

public Command getNamedCommand(java.lang.String name)

Get the named public command (or command list) from the show we're managing. If not found and if we're in debug mode, trigger an assertion failure. This method does a search through the show's named commands using a hashtable lookup, so it shouldn't be called too frequently; it's best used during initialization.

The returned Command object can be used in a call to runCommand(Command) on the show from whene it came. If you send a named command to a different show, the results are undefined.

getPart

public Feature getPart(Assembly assembly,
                       java.lang.String partName)

Look up the named part in the given assembly. If not found and if we're in debug mode, trigger an assertion failure. This method does a search through the assembly's parts, so it shouldn't be called frequently; it's best used during initialization.

getSegment

public Segment getSegment(java.lang.String name)

Look up the given named public segment in the show we're managing. If not found and if we're in debug mode, trigger an assertion failure. This method does a search through the show's features using a hashtable lookup, so it shouldn't be called frequently; it's best used during initialization.

notifyNextFrame

public void notifyNextFrame()

Notify the director that the model is moving to the next frame. Subclasses that override this method must call super.notifyNextFrame() at least once. The implementation of this method in Director causes the show to execute all pending commands, which can result in model state changes, such as selecting new segments, changing the selected part in an assembly, etc. Usually, you'll probably want to call super.notifyNextFrame() first thing, but it may be useful in some circumstances to do some computation before, e.g. something that might result in posting a command to the show.

This method is called after the scene graph's model has moved to the upcoming frame's state. Xlets that override this method may wish to update user-programmable node values in the body of this method. This method and the execute() body of a command are the only safe times for user code to update show nodes.

This method is called with the show lock held, that is, within a synchronized block in this director's show. It's essential to hold the show lock when updating the scene graph, e.g. so that changes from remote control keypresses do not happen at the same time. Xlets that override notifyNextFrame() should be careful that any xlet state they access is done in a thread-safe way.

If you want to run some Java code to update the scene graph for every frame when the show is in certain states, it might be easier to make a timer that goes off every frame, invoking a java_command.

notifySegmentActivated

public void notifySegmentActivated(Segment newSegment,
                                   Segment oldSegment)

Notify the director that a new segment has been activated.

This method is called with the show lock held, that is, within a synchronized block in this director's show. It's essential to hold the show lock when updating the scene graph, e.g. so that changes from remote control keypresses do not happen at the same time. Xlets that override this method should be careful that any xlet state they access is done in a thread-safe way.

The default implementation of this method does nothing, so there is no need to call super.notifySegmentActivated().

Parameters:

newSegment - The new segment that was activated

oldSegment - The old segment that was previously active

notifyAssemblyPartSelected

public void notifyAssemblyPartSelected(Assembly assembly,
                                       Feature newPart,
                                       Feature oldPart,
                                       boolean assemblyIsActive)

Notify the director that a new part has been selected within an assembly.

This method is called with the show lock held, that is, within a synchronized block on this director's show. It's essential to hold the show lock when updating the scene graph, e.g. so that changes from remote control keypresses do not happen at the same time. Xlets that override this method should be careful that any xlet state they access is done in a thread-safe way.

The default implementation of this method does nothing, so there is no need to call super.notifyAssemblyPartSelected().

Note that during the callback, the current part of the assembly is undefined, and might not reflect the new value.

Parameters:

assembly - The assembly within which a new part was selected

newPart - The new part that's now selected

oldPart - The old part that used to be selected.

assemblyIsActive - True if assembly is currently active, that is, being displayed.

notifyDestroyed

public void notifyDestroyed()

Notifies the director that the underlying show has been destroyed. This is called from the animation thread with the show lock held. If the director has acquired any resources, it should release them here.