com.hdcookbook.grin.commands
Class Command

java.lang.Object
  extended by com.hdcookbook.grin.commands.Command
Direct Known Subclasses:
ActivatePartCommand, ActivateSegmentCommand, GrinXHelper, RCKeyEvent, ResetFeatureCommand, SetVisualRCStateCommand

public abstract class Command
extends java.lang.Object

Common base class of all GRIN commands. GRIN defers anything that can change the state of a show to a command. In this way, the synchronization model is kept very simple. Commands are always executed with the show lock held, at a time when it's OK to update the show's model. They can be executed from the animation thread within Show.nextFrame(), and the can also be executed from within a remote control key handler.

If you make an extension command, and if you want equivalent command objects to be canonicalized (that is, collapsed into one object), the Java SE version of that command class should override Object.equals(Object) and Object.hashCode().

Author:
Bill Foote (http://jovial.com)
See Also:
Show.nextFrame()

Field Summary
protected  Show show
           
 
Constructor Summary
protected Command(Show show)
           
 
Method Summary
 Command cloneIfNeeded(java.util.HashMap featureClones)
          Return this command, or if needed, a copy of this command.
 boolean deferNextCommands()
          Deprecated.  
abstract  void execute()
          Execute the command.
 void execute(Show caller)
          Execute the command.
 java.lang.String toString()
          Return a user-friendly string for this command for debugging purposes.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

show

protected Show show
Constructor Detail

Command

protected Command(Show show)
Method Detail

execute

public void execute(Show caller)
Execute the command. This causes the command to take whatever action it was created to do. By default, this calls execute().

Parameters:
caller - The show that is executing this command. This might not be the same as the show this command was created under.

execute

public abstract void execute()
Execute the command. This causes the command to take whatever action it was created to do.


cloneIfNeeded

public Command cloneIfNeeded(java.util.HashMap featureClones)
Return this command, or if needed, a copy of this command.

Most commands don't have any data members that contain mutable state, that is, data memebers whose values are modified (e.g. when the command is executed). Also, most commands don't refer to part of a scene graph. For this reason, when a subtree of a scene graph is cloned, most of the cloned features can just re-use the same Command objects in their endCommands arrays.

However, some commands to contain references to features. If a command in a subtree being cloned refers to a feature in that subtree, then the cloned command should refer to the cloned feature. Commands that do this should override this method to provide a copy of the command, with the feature references mapeped over.

Further, it's possible that a command subclass might contain a data member that gets modified, e.g. during command execution. This is probably bad form, and none of the GRIN commands do this, but if you make a command subclass that does, you should override this method so that cloned commands get a new instance of your command subclass.

The default implementation of this method returns the current instances.

Parameters:
featureClones - HashMap mapping an original feature to its clone.

deferNextCommands

public final boolean deferNextCommands()
Deprecated. 

This method is obsolete, and should not be overridden by any subclass. It has been kept and marked final so that a compilation error will be provoked if any subclass overrides it.

This method used to be defined so that returning true would have the effect of a sync_display command. Now that there's a sync_display command, there's no need (see GrinXHelper.SYNC_DISPLAY). Additionally, any command that wants to defer command execution until the display is caught up can call Show.deferNextCommands() in the body of the command's execute method.

See Also:
Show.deferNextCommands()

toString

public java.lang.String toString()
Return a user-friendly string for this command for debugging purposes.

Overrides:
toString in class java.lang.Object