com.livescribe.ext.plugins
Class AcquireHWPlugin

java.lang.Object
  com.livescribe.penlet.PenletPlugin
      com.livescribe.penlet.AbstractPenletPlugin
          com.livescribe.ext.plugins.AcquireHWPlugin

public class AcquireHWPlugin
extends AbstractPenletPlugin

A penlet plugin that performs common functions.

• Manage the ICR state and results.
• Display filtered results on the screen.
• Double-tap detection.

This is designed to work well with applications that use a single line of handwriting and some terminating event (including double-tap) to perform a function.

Note that this plugin does not save and restore the screen.

Nested Class Summary

static interface

AcquireHWPlugin.DisplayFilter An interface that defines how to display the results on the screen when displaying the results is enabled.

Field Summary

protected Rectangle	currBB The current bounding box of any received strokes.
protected PageInstance	currPage The current page, set when a pen-down event occurs.
static int	DEFAULT_HWR_INACTIVITY_TIME The default HWR inactivity time.
static int	RESULT_HWR_ERROR Indicates that an HWR error occurred.
static int	RESULT_OK The result is "OK".
static int	RESULT_OVERLAPPED An overlap was detected and overlapping was set to not allowed.
static int	RESULT_PAGE_CHANGED The page was changed in the middle of the recognition and page changing was set to not allowed.
static int	RESULT_UNDEFINED The plugin has not been used to generate a result or it has been deactivated early.

Fields inherited from class com.livescribe.penlet.AbstractPenletPlugin

active, listeners

Constructor Summary

AcquireHWPlugin(Penlet penlet)
Creates a new HWR plugin.

Method Summary

void	activate() Activates the plugin.
void	addAKSystemResource(String res) Adds an Alphabet Knowledge system ICR resource.
void	addAppResource(String res) Adds an application-specific ICR resource.
void	addLKSystemResource(String res) Adds a Lexical Knowledge system ICR resource.
void	addSKSystemResource(String res) Adds a Subset Knowledge system ICR resource.
void	clearResources() Clears all the ICR resources.
void	deactivate() Deactivates the plugin.
String	getHWRErrorString() Returns the HWR error string if getResultStatus() returns RESULT_HWR_ERROR.
String	getResult() Returns the last HWR result.
Rectangle	getResultBounds() Gets the bounds of the last result.
int	getResultStatus() Gets the status of the result, for example if the result is null because of an error.
boolean	onPenTipEvent(PenTipEvent ev) Processes a pen tip event.
boolean	onStrokeEvent(StrokeEvent ev) A new stroke was created by the user.
protected void	restart(boolean resetState) Restarts the handwriting recognition process.
void	setAllowOverlap(boolean flag) Sets whether strokes are allowed on regions that are not open paper.
void	setAllowPageChange(boolean flag) Sets whether to allow handwriting recognition over multiple pages.
void	setDisplayOnResult(boolean flag, AcquireHWPlugin.DisplayFilter displayFilter) Sets whether to display the results as the are received.
void	setDoubleTapTerminates(boolean flag) Sets whether the plugin should terminate when a user timeout occurs or if it should terminate after a double tap.
void	setHWRInactivityTime(int time) Sets the HWR timeout, in milliseconds.
void	setUserPauseTerminates(boolean flag) Sets whether a user pause can terminate the plugin.
String	toString() Returns a string representation of this object.

Methods inherited from class com.livescribe.penlet.AbstractPenletPlugin

addPluginListener, fireActivated, fireDeactivated, isActive, onCoordinateEvent, onDocumentEvent, onMenuEvent, onRegionEvent, removePluginListener, scheduleDeactivation, setConsumeAllEvents

Methods inherited from class com.livescribe.penlet.PenletPlugin

getDisplay, getPenlet, restoreDisplay, saveDisplay

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_HWR_INACTIVITY_TIME

public static final int DEFAULT_HWR_INACTIVITY_TIME

The default HWR inactivity time.

See Also:

Constant Field Values

RESULT_UNDEFINED

public static final int RESULT_UNDEFINED

The plugin has not been used to generate a result or it has been deactivated early.

See Also:

Constant Field Values

RESULT_OK

public static final int RESULT_OK

The result is "OK".

See Also:

Constant Field Values

RESULT_OVERLAPPED

public static final int RESULT_OVERLAPPED

An overlap was detected and overlapping was set to not allowed.

See Also:

setAllowOverlap(boolean), Constant Field Values

RESULT_PAGE_CHANGED

public static final int RESULT_PAGE_CHANGED

The page was changed in the middle of the recognition and page changing was set to not allowed.

See Also:

setAllowPageChange(boolean), Constant Field Values

RESULT_HWR_ERROR

public static final int RESULT_HWR_ERROR

Indicates that an HWR error occurred.

See Also:

Constant Field Values

currBB

protected Rectangle currBB

The current bounding box of any received strokes.

currPage

protected PageInstance currPage

The current page, set when a pen-down event occurs.

Constructor Detail

AcquireHWPlugin

public AcquireHWPlugin(Penlet penlet)

Creates a new HWR plugin. The plugin is set to not consume all events. In other words, the superclass constructor is called with consumeAllEvents set to false.

Parameters:

penlet - the associated penlet

See Also:

AbstractPenletPlugin.AbstractPenletPlugin(Penlet, boolean)

Method Detail

activate

public void activate()
              throws PenletStateChangeException

Activates the plugin. This creates a new ICR context. Note that this does not save the display.

If the HWR engine could not be initialized or if the ICR resources have not been set then this will throw a PenletStateChangeException.

The plugin will start processing events when it sees the next pen-down event. It will ignore all other pen tip and stroke events—and pass them along to the application—until then.

Overrides:

activate in class AbstractPenletPlugin

Throws:

PenletStateChangeException - if there was an error initializing HWR engine or if the ICR resources were not set.

See Also:

setHWRInactivityTime(int), addAKSystemResource(String), addSKSystemResource(String), addLKSystemResource(String), addAppResource(String)

restart

protected void restart(boolean resetState)

Restarts the handwriting recognition process. This can be used from inside a subclass's deactivate() implementation if actual deactivation is not yet required.

There are two ways to restart the process. The first way is to completely reset the state so that new handwriting will not continue from where the recognition left off. If this is the desired behavior, pass true for the resetState parameter.

The other way is to continue the recognition from where it left off. If this is desired then pass false for the parameter.

Parameters:

resetState - indicates whether to reset the state

deactivate

public void deactivate()

Deactivates the plugin. This disposes of the ICR context. Note that this does not restore the display.

This can be overridden and used as a way to detect when this plugin is finished recognition. The HWR process can be restarted via restart(boolean). In this case, don't call super.deactivate() because that would actually deactivate the plugin.

Overrides:

deactivate in class AbstractPenletPlugin

See Also:

AbstractPenletPlugin.active, AbstractPenletPlugin.fireDeactivated()

setHWRInactivityTime

public void setHWRInactivityTime(int time)

Sets the HWR timeout, in milliseconds. The timeout is measured from when the user lifts the pen.

The default is 2000 ms.

Parameters:

time - the new HWR timeout, in ms

See Also:

DEFAULT_HWR_INACTIVITY_TIME

addAKSystemResource

public void addAKSystemResource(String res)

Adds an Alphabet Knowledge system ICR resource.

Parameters:

res - add this AK system resource

See Also:

ICRContext.createAKSystemResource(String), clearResources()

addSKSystemResource

public void addSKSystemResource(String res)

Adds a Subset Knowledge system ICR resource.

Parameters:

res - add this SK system resource

See Also:

ICRContext.createSKSystemResource(String), clearResources()

addLKSystemResource

public void addLKSystemResource(String res)

Adds a Lexical Knowledge system ICR resource.

Parameters:

res - add this LK system resource

See Also:

ICRContext.createLKSystemResource(String), clearResources()

addAppResource

public void addAppResource(String res)

Adds an application-specific ICR resource.

Parameters:

res - add this application resource

See Also:

ICRContext.createAppResource(String), clearResources()

clearResources

public void clearResources()

Clears all the ICR resources.

See Also:

addAKSystemResource(String), addSKSystemResource(String), addLKSystemResource(String), addAppResource(String)

setAllowOverlap

public void setAllowOverlap(boolean flag)

Sets whether strokes are allowed on regions that are not open paper. A region is considered as "not open paper" if it has no assigned meaning, to the current app as a dynamic or fixed print control, for example.

The default is to disallow overlap, or false.

Parameters:

flag - the new state

setAllowPageChange

public void setAllowPageChange(boolean flag)

Sets whether to allow handwriting recognition over multiple pages. The default is to disallow this, or false.

Parameters:

flag - the new state

setDisplayOnResult

public void setDisplayOnResult(boolean flag,
                               AcquireHWPlugin.DisplayFilter displayFilter)

Sets whether to display the results as the are received. The default is to not display intermediate results, or false.

This also sets the display filter to use when displaying received results. If this is set to null then the result will be used as-is. The default is no display filter, or null.

Parameters:

flag - the new state

displayFilter - the new display filter, may be null

See Also:

AcquireHWPlugin.DisplayFilter

setDoubleTapTerminates

public void setDoubleTapTerminates(boolean flag)

Sets whether the plugin should terminate when a user timeout occurs or if it should terminate after a double tap. If set to true, the plugin will terminate after a double tap. If set to false, the plugin will terminate after it receives its first timeout.

The default is false.

If this is set to true then double taps are not consumed by this plugin and are passed along to the application. This is to allow the application to, for example, alert the user. Note that there is no guarantee as to the ordering of this event with respect to plugin deactivation.

Parameters:

flag - the new state

See Also:

setUserPauseTerminates(boolean)

setUserPauseTerminates

public void setUserPauseTerminates(boolean flag)

Sets whether a user pause can terminate the plugin. If a double tap is set to not terminate the plugin (setDoubleTapTerminates(boolean) set to false), then this setting is ignored and it will be as if it is set to true. In other words, the only time a user pause does not terminate the plugin is when this setting is set to false and setDoubleTapTerminates(boolean) is set to true.

The default is false.

Parameters:

flag - the new state

See Also:

setDoubleTapTerminates(boolean)

getResult

public String getResult()

Returns the last HWR result. This will return null if the plugin has never been activated before, or if the current result was not recognized.

Returns:

the last HWR result.

See Also:

getResultBounds(), getResultStatus()

getResultBounds

public Rectangle getResultBounds()

Gets the bounds of the last result.

Returns:

the bounds of the last result.

See Also:

getResult()

getResultStatus

public int getResultStatus()

Gets the status of the result, for example if the result is null because of an error.

Please see the RESULT_XXX constants.

If this returns RESULT_HWR_ERROR then getHWRErrorString() can be used to retrieve any associated error string.

Returns:

the result status.

See Also:

RESULT_UNDEFINED, RESULT_OK, RESULT_OVERLAPPED, RESULT_PAGE_CHANGED, RESULT_HWR_ERROR

getHWRErrorString

public String getHWRErrorString()

Returns the HWR error string if getResultStatus() returns RESULT_HWR_ERROR.

Returns:

the HWR error string.

Since:

2.5

See Also:

HWRListener.hwrError(long, String)

onStrokeEvent

public boolean onStrokeEvent(StrokeEvent ev)

A new stroke was created by the user.

This performs the following tasks:

1. Sets recordNextStroke to true and returns immediately if it was set to false.
2. Notifies the ICR context of the latest pen down time and adds the stroke.
3. Adds the stroke's bounding box to currBB.

Overrides:

onStrokeEvent in class AbstractPenletPlugin

Parameters:

ev - the stroke event

Returns:

whether the event is handled.

See Also:

AbstractPenletPlugin.setConsumeAllEvents(boolean)

onPenTipEvent

public boolean onPenTipEvent(PenTipEvent ev)

Processes a pen tip event.

This does not consume double taps if double tap termination is enabled via setDoubleTapTerminates(boolean). The purpose of passing along double taps is to allow the application to perform some action in case it wishes to alert the user.

Overrides:

onPenTipEvent in class AbstractPenletPlugin

Parameters:

ev - the pen tip event

Returns:

whether the event was processed.

See Also:

AbstractPenletPlugin.setConsumeAllEvents(boolean)

toString

public String toString()

Returns a string representation of this object.

Overrides:

toString in class Object

Returns:

a string representation of this object.