edu.berkeley.guir.ptk.output
Class Output

java.lang.Object
  edu.berkeley.guir.ptk.PTK
      edu.berkeley.guir.ptk.output.Output

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

BusLEDOutputTest, BusMobileOutput, GraphicalTextOutput, IconOutput, OrbOutput, PhidgetInterfaceKitOutput, PhidgetLEDOutput, PhidgetServoOutput

public abstract class Output

extends PTK

implements java.lang.Runnable

Abstract class for output objects and library elements. Developers can use one of the PTK Output library elements or extend this class to create new applications. This class runs as its own thread so that an output can display events in variable lengths of time without stalling the entire system.

See the edu.berkeley.guir.edu.berkeley.guir.ptk.output package comments for much more information on how to write an Output, library elements, and how to customize library elements.

Author:

tmatthew

Field Summary

protected boolean	animatable
protected EventPriorityQueue	d_queue This member data stores the events that need to be displayed by this output in reverse chronilogical order.
protected java.lang.String[]	data_ids_I_want The data ID Strings of event Data the output can display.
protected History	history Stores all the events this Output has received (in handleEvent().
protected static int	ITEMS_LENGTH Size of arrays to create for data IDs array and MetadataItems array.
protected java.util.Vector	metadata_I_want The Metadata objects of events the output can display.
protected int	num_ids
protected int	num_metadata
long	output_cycle_time The number of milliseconds that the output will wait in between calling displayEvent() on new events (the sleep occurs in between loops of the run() method).
protected Transition	transition The Transition object that handles transitions for this Output.

Fields inherited from class edu.berkeley.guir.ptk.PTK

debug, MAX_DEBUG, MED_DEBUG, MIN_DEBUG, NO_DEBUG

Constructor Summary

Output()
Default constructor.

Output(boolean animatable)
Constructor for Animatable Outputs.

Output(java.lang.String data_id)

Output(java.lang.String[] data_ids_I_want)
Parameterized constructor.

Output(java.lang.String[] data_ids_I_want, boolean animatable)

Output(java.lang.String[] data_ids_I_want, Transition t)

Output(java.lang.String data_id, boolean animatable)

Output(java.lang.String data_id, Transition t)

Output(Transition t)
Constructor for Animatable Outputs that want to use a custom Transition class.

Method Summary

void	addDataID(java.lang.String id) This function copies the data id provided and adds it to the data_ids_I_want array
void	addMetadataIWant(Metadata mds) Performs a deep copy of the MetadataItems in the array passed in to the metadata_I_want data field.
protected boolean	checkAction(Event e) Used only for events that have the demand action notification level.
protected abstract void	displayEvent(Event e) This code needs to actually display the event (e.g.
boolean	doIWant(Event e) Checks the metadata_I_want and data_ids_I_want fields for the MetadataItems and Data ids in the given event.
Metadata[]	getAllMetadata() Returns all Metadata objects that indicate all input events the output can handle (used for connections to multiple inputs).
java.lang.String[]	getDataIDs() Returns the data IDs of event data this Output can handle.
Metadata	getFirstMetadata() Returns only the first Metadata object; for outputs that connect to only a single input, the first will be the ONLY Metadata object.
History	getHistory() Returns the History object kept by this Output.
protected void	handleEvent(Event new_event) This method is called by the output policy to send an event to this specific output.
protected void	interDisplayEvent(long ptime) This function is called between the displaying of events.
boolean	isAnimatable() Returns true if this class is animatable and false if it is not.
void	printMetadataIWant()
void	run() Thread function that periodically checks the event queue for new events, and calls displayEvent.
void	setChangeblindTransitionSteps(int steps) Sets the number of steps (events) involved in a change blind transition.
void	setDataIDsIWant(java.lang.String[] ids) Performs a deep copy of the Strings in the array passed in to the data_ids_I_want data field.
void	setInterruptTransitionSteps(int steps) Sets the number of steps (events) involved in a interrupt transition.
void	setMakeawareTransitionSteps(int steps) Sets the number of steps (events) involved in a make aware transition.
void	setTimeBetweenDisplayEvents(long ms)
void	setTransition(Transition t) Sets the Transition object for this Output.
void	setUnsetNotification(Event e) Sets the notification level for events that have not had their's set.

Methods inherited from class edu.berkeley.guir.ptk.PTK

getMAX, getMED, getMIN, getNO, printDebug, printDebug, printError

Methods inherited from class java.lang.Object

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

Field Detail

ITEMS_LENGTH

protected static final int ITEMS_LENGTH

Size of arrays to create for data IDs array and MetadataItems array.

See Also:

Constant Field Values

output_cycle_time

public long output_cycle_time

The number of milliseconds that the output will wait in between calling displayEvent() on new events (the sleep occurs in between loops of the run() method).

num_ids

protected int num_ids

num_metadata

protected int num_metadata

metadata_I_want

protected java.util.Vector metadata_I_want

The Metadata objects of events the output can display. These could hold one or more metadata items. The doIWant(Event) method checks this array. This data field must be set to a valid input metadata for this Output to get any events.

data_ids_I_want

protected java.lang.String[] data_ids_I_want

The data ID Strings of event Data the output can display. These could hold one or more data IDs. The doIWant(Event) method checks this array. This data field can be null.

d_queue

protected EventPriorityQueue d_queue

This member data stores the events that need to be displayed by this output in reverse chronilogical order.

animatable

protected boolean animatable

transition

protected Transition transition

The Transition object that handles transitions for this Output. If null, this Output does not do transitions.

history

protected History history

Stores all the events this Output has received (in handleEvent().

Constructor Detail

Output

public Output()

Default constructor.

Output

public Output(boolean animatable)

Constructor for Animatable Outputs. The default Transition class is instantiated for use by the Output.

Parameters:

animatable - true indicates the Output will be Animatable.

Output

public Output(Transition t)

Constructor for Animatable Outputs that want to use a custom Transition class.

Parameters:

t - a custom Transition object.

Output

public Output(java.lang.String[] data_ids_I_want)

Parameterized constructor.

Parameters:

data_ids_I_want - the data IDs from an input event's data that this Output wants to display. The data IDs specified do not have to exactly match the input event's data IDs: they must simply be included in the event's data IDs.

Output

public Output(java.lang.String[] data_ids_I_want,
              boolean animatable)

Output

public Output(java.lang.String[] data_ids_I_want,
              Transition t)

Output

public Output(java.lang.String data_id)

Output

public Output(java.lang.String data_id,
              boolean animatable)

Output

public Output(java.lang.String data_id,
              Transition t)

Method Detail

displayEvent

protected abstract void displayEvent(Event e)

This code needs to actually display the event (e.g. print the text, show the image, etc). This function should return as fast as possible.

Parameters:

e - This event to be displayed

handleEvent

protected void handleEvent(Event new_event)

This method is called by the output policy to send an event to this specific output. First, if the Output is Animatable, then transition is called on the new event. Next, an array including the events created by the transition object (or simply an array with the single new event) is sent to EventPriorityQueue.insert, which puts each event into the display queue (d_queue) so that the actual display function (Output.displayTheEvent()) can display the events in the correct order.

run

public void run()

Thread function that periodically checks the event queue for new events, and calls displayEvent.

Specified by:

run in interface java.lang.Runnable

isAnimatable

public boolean isAnimatable()

Returns true if this class is animatable and false if it is not.

getHistory

public History getHistory()

Returns the History object kept by this Output.

doIWant

public boolean doIWant(Event e)

Checks the metadata_I_want and data_ids_I_want fields for the MetadataItems and Data ids in the given event. These fields identify the event so the output can determine if it wants the data it contains. Returns true if no ids are specified in both metadata_I_want and data_ids_I_want. Returns true if the MetadataItems indicated in metadata_I_want is included in the metadata and the ids indicated in data_ids_I_want are included in the data.

setUnsetNotification

public void setUnsetNotification(Event e)

Sets the notification level for events that have not had their's set. The default implemented here is to set the notification level to change blind.

setTransition

public void setTransition(Transition t)

Sets the Transition object for this Output. Use this to customize how Transitions are done.

Parameters:

t - custom Transition object.

setChangeblindTransitionSteps

public void setChangeblindTransitionSteps(int steps)

Sets the number of steps (events) involved in a change blind transition.

Parameters:

steps -

setMakeawareTransitionSteps

public void setMakeawareTransitionSteps(int steps)

Sets the number of steps (events) involved in a make aware transition.

Parameters:

steps -

setInterruptTransitionSteps

public void setInterruptTransitionSteps(int steps)

Sets the number of steps (events) involved in a interrupt transition.

Parameters:

steps -

setDataIDsIWant

public void setDataIDsIWant(java.lang.String[] ids)

Performs a deep copy of the Strings in the array passed in to the data_ids_I_want data field. Use this method instead of "=" so that multiple output objects are not sharing the same array of ids.

Parameters:

ids - An array of string indicating what data items in the input data this output object is interested in getting.

addDataID

public void addDataID(java.lang.String id)

This function copies the data id provided and adds it to the data_ids_I_want array

Parameters:

id - String containing the id of the data item in the input data this output object is interested in getting.

addMetadataIWant

public void addMetadataIWant(Metadata mds)

Performs a deep copy of the MetadataItems in the array passed in to the metadata_I_want data field. Use this method instead of "=" so that multiple output objects are not sharing the same array of MetadatItems.

getFirstMetadata

public Metadata getFirstMetadata()

Returns only the first Metadata object; for outputs that connect to only a single input, the first will be the ONLY Metadata object.

Returns:

getAllMetadata

public Metadata[] getAllMetadata()

Returns all Metadata objects that indicate all input events the output can handle (used for connections to multiple inputs).

Returns:

getDataIDs

public java.lang.String[] getDataIDs()

Returns the data IDs of event data this Output can handle.

Returns:

setTimeBetweenDisplayEvents

public void setTimeBetweenDisplayEvents(long ms)

interDisplayEvent

protected void interDisplayEvent(long ptime)

This function is called between the displaying of events. The default behavior is to sleep for the given amount of time. The user can overwrite this method to do other actions between events.

Parameters:

ptime - the time in milliseconds that this function controls the display

checkAction

protected boolean checkAction(Event e)

Used only for events that have the demand action notification level. Should check whether the action that has been demanded has been performed - this default simply returns false.

Parameters:

e - the event to be displayed.

Returns:

boolean specifies whether the demanded action has been performed.

printMetadataIWant

public void printMetadataIWant()