com.hdcookbook.grin.input
Class VisualRCHandler

java.lang.Object
  com.hdcookbook.grin.input.RCHandler
      com.hdcookbook.grin.input.VisualRCHandler

All Implemented Interfaces:

Node

public class VisualRCHandler
extends RCHandler
implements Node

A VisualRCHandler models interaction with the remote control and the mouse as a grid of cells. Each cell can contain a state, but it can instead contain an address of another cell. When the user navigates from one cell to another, he lands on the indicated state, or if he lands on a cell that contains the address of another cell, he goes to that cell. A given state can only occupy one cell.

No wrapping behavior is specified: If a user tries to navigate off the edge of the grid, the state remains unchanged. If that isn't the desired UI behavior, then simply create a grid where the border consists of cell addresses.

A visual handler may optionally be tied to an assembly. When this handler is activated, the handler is put into the state determined by the assembly, by finding the state that corresponding to the assembly's currently active part. Once a handler is active, it assumes that it's the only one in control fo the assembly; it doesn't check for the assembly changing state out from under it.

A handler can also optionally have commands associated with its states. These are invoked only when the handler changes state - a command is not sent for the current state when the handler is activated. When commands are used to maintain the scene graph's state, it's up to the application to ensure that the UI is in a state that matches the handler's state before the handler is activated.

The state of a handler is determined by the activated flag, and by the named state. It may be safely changed with a set_visual_rc command. Once the handler is activated, it stays in that state until reset by a set_visual_rc command, a call to setState(...), or the user navigating with the arrow keys. If the handler is activated and the user presses the enter key again, the handler is "re-activated;" the activation commands are executed again, and the assembly's state is set to selected then immediately to activated, in order to re-run any activation animation.

Author:

Bill Foote (http://jovial.com)

Field Summary

protected Command[][]	activateCommands
protected Feature[]	activateFeatures
protected Assembly	assembly
static int	GRID_ACTIVATE A special value in a grid that means to activate the current state
protected java.lang.String[]	gridAlternateNames
protected static int	MASK
protected java.awt.Rectangle[]	mouseRects
protected int[]	mouseRectStates
protected int[]	rightLeft
protected int[][]	rightLeftAlternates
protected Command[][]	selectCommands
protected Feature[]	selectFeatures
protected boolean	startSelected Flag that, if true, makes the handler start out in the selected state.
protected java.lang.String[]	stateNames
protected int	timeout
protected Command[]	timeoutCommands
protected int[]	upDown
protected int[][]	upDownAlternates

Fields inherited from class com.hdcookbook.grin.input.RCHandler

name, show

Constructor Summary

VisualRCHandler()

Method Summary

void	activate(Segment s) Called for handlers in s when s is activated
boolean	getActivated() This is intended for applications that wish to query the UI state.
int	getState() This is intended for applications that wish to query the UI state.
java.lang.String	getStateName(int stateNum) Get the name of a numbered state.
boolean	handleKeyPressed(RCKeyEvent ke, Show caller) Handle a remote control key press.
boolean	handleKeyReleased(RCKeyEvent ke, Show caller) Handle a remote control key release.
boolean	handleKeyTyped(RCKeyEvent ke, Show caller) Handle a key typed event.
boolean	handleMouse(int x, int y, boolean activate)
int	lookupGrid(java.lang.String gridAlternateName) Look up an alternate grid by name.
int	lookupState(java.lang.String name) Lookup a state number by name.
void	nextFrame() Called by the show to let us know as the model progresses through time.
void	readInstanceData(GrinDataInputStream in, int length) Reads in this node information from the binary file format.
void	setState(int newState, boolean newActivated, boolean runCommands) Called from InvokeVisualCellCommand, and from internal methods.
void	setState(int newState, boolean newActivated, boolean runCommands, int gridAlternate) Called from InvokeVisualCellCommand, and from internal methods.
java.lang.String	toString() Give a developer-friendly string describing this handler.

Methods inherited from class com.hdcookbook.grin.input.RCHandler

getName, setName, setShow

Methods inherited from class java.lang.Object

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

Field Detail

GRID_ACTIVATE

public static final int GRID_ACTIVATE

A special value in a grid that means to activate the current state

See Also:

Constant Field Values

MASK

protected static int MASK

upDown

protected int[] upDown

rightLeft

protected int[] rightLeft

upDownAlternates

protected int[][] upDownAlternates

rightLeftAlternates

protected int[][] rightLeftAlternates

gridAlternateNames

protected java.lang.String[] gridAlternateNames

stateNames

protected java.lang.String[] stateNames

assembly

protected Assembly assembly

selectFeatures

protected Feature[] selectFeatures

selectCommands

protected Command[][] selectCommands

activateFeatures

protected Feature[] activateFeatures

activateCommands

protected Command[][] activateCommands

mouseRects

protected java.awt.Rectangle[] mouseRects

mouseRectStates

protected int[] mouseRectStates

timeout

protected int timeout

timeoutCommands

protected Command[] timeoutCommands

startSelected

protected boolean startSelected

Flag that, if true, makes the handler start out in the selected state. When the handler is activated, if the underlying assembly is found to be in an activated state, it is coerced into the corresponding selected state.

Constructor Detail

VisualRCHandler

public VisualRCHandler()

Method Detail

toString

public java.lang.String toString()

Give a developer-friendly string describing this handler. Useful for development.

Overrides:

toString in class RCHandler

getActivated

public boolean getActivated()

This is intended for applications that wish to query the UI state. The value of this will not be changed as long as a lock is held on our show.

getState

public int getState()

This is intended for applications that wish to query the UI state. The value of this will not be changed as long as a lock is held on our show.

getStateName

public java.lang.String getStateName(int stateNum)

Get the name of a numbered state.

lookupState

public int lookupState(java.lang.String name)

Lookup a state number by name. Used for parsing, or by xlets.

Returns:

-1 if not found

lookupGrid

public int lookupGrid(java.lang.String gridAlternateName)

Look up an alternate grid by name. Used for parsing, or by xlets.

Returns:

-1 if not found

handleKeyPressed

public boolean handleKeyPressed(RCKeyEvent ke,
                                Show caller)

Handle a remote control key press. This is called on the animation thread, at a time when it's safe to modify the scene graph. The show lock will be held, and the show won't be between a call to addDisplayAreas() and paintFrame().

Specified by:

handleKeyPressed in class RCHandler

Returns:

true if the keypress is used

handleKeyReleased

public boolean handleKeyReleased(RCKeyEvent ke,
                                 Show caller)

Handle a remote control key release. This is not supported on all devices. This is called on the animation thread, at a time when it's safe to modify the scene graph. The show lock will be held, and the show won't be between a call to addDisplayAreas() and paintFrame().

Specified by:

handleKeyReleased in class RCHandler

Returns:

true if the keypress is used

handleKeyTyped

public boolean handleKeyTyped(RCKeyEvent ke,
                              Show caller)

Handle a key typed event. Key typed events can be part of a GRIN extension; see the protected constructor of RCKeyEvent for details. This is called on the animatino thread when it's safe to modify the scene graph. The show lock will be held, and the show won't be between a call to addDisplayAreas() and paintFrame().

Specified by:

handleKeyTyped in class RCHandler

Returns:

true if the keypress is used

handleMouse

public boolean handleMouse(int x,
                           int y,
                           boolean activate)

Specified by:

handleMouse in class RCHandler

Returns:

true if something is done with the mouse

setState

public void setState(int newState,
                     boolean newActivated,
                     boolean runCommands)

Called from InvokeVisualCellCommand, and from internal methods. This is synchronized on our show, to only occur during model updates. This method may also be called from a java_command or from the director, within the animation thread.

Parameters:

newState - New state, -1 means "current"

newActivated - New value for activated

runCommands - If true, run the commands normally associated with entering this state due to a keypress.

setState

public void setState(int newState,
                     boolean newActivated,
                     boolean runCommands,
                     int gridAlternate)

Called from InvokeVisualCellCommand, and from internal methods. This is synchronized on our show, to only occur during model updates. This method may also be called from a java_command or from the director, within the animation thread.

Parameters:

newState - New state, -1 means "current"

newActivated - New value for activated

runCommands - If true, run the commands normally associated with entering this state due to a keypress.

gridAlternate - Alternate grid # to select, 0..max, or -1 to leave grid unchanged.

activate

public void activate(Segment s)

Called for handlers in s when s is activated

Specified by:

activate in class RCHandler

nextFrame

public void nextFrame()

Called by the show to let us know as the model progresses through time. This can be useful for things like timeouts.

Specified by:

nextFrame in class RCHandler

readInstanceData

public void readInstanceData(GrinDataInputStream in,
                             int length)
                      throws java.io.IOException

Description copied from interface: Node

Reads in this node information from the binary file format.

An implementation of this method is recommended to call in.readSuperClassData(this) as the first line of the method to read in information that is defined in the base class of this Node type.

This should only be called while initializing this object.

Specified by:

readInstanceData in interface Node

Parameters:

in - InputStream to read data from.

length - the number of bytes that this node's information occupies in the InputStream. The implementation of this method is expected to read exactly this number of bytes from the stream. This can be used for a debugging purpose.

Throws:

java.io.IOException - if error occurs.

See Also:

GrinDataInputStream.readSuperClassData(Feature), GrinDataInputStream.readSuperClassData(RCHandler), GrinDataInputStream.readSuperClassData(Segment), GrinDataInputStream.readSuperClassData(Command)