com.livescribe.penlet
Class PenletContext

java.lang.Object
  com.livescribe.penlet.PenletContext

public abstract class PenletContext
extends Object

PenletContext exposes services to the pen application. The context is made available as part of the penlet initialization ( Penlet.initApp()).

The context allows applications to dynamically add/remove listeners to monitor events. If the application tries to add the same listener twice (or more), the latter call will not add the listener. On the same note if the application removes a registered listener twice (or more), the latter call to remove will be simply ignored.

Field Summary

protected int

instanceId

Constructor Summary

protected

PenletContext(int instanceID) Creates a new penlet context having the specified instance ID.

Method Summary

abstract void	addAreaEnterExitListener(AreaEnterExitListener listener) Deprecated. use addRegionEnterExitListener(RegionEnterExitListener)
abstract void	addAreaEnterExitListener(AreaEnterExitListener listener, Region region) Deprecated. use addRegionEnterExitListener(RegionEnterExitListener,Region)
abstract void	addCoordinateListener(CoordinateListener listener) Adds a listener for coordinate events.
void	addMetricData(String metricName) Add a metric with empty data.
void	addMetricData(String metricName, Object data) Add a metric with data.
abstract void	addMetricData(String metricName, Object[] data) Add metric data associated with the penlet.
abstract void	addPaperListener(PaperListener listener) Adds a listener for paper events
abstract void	addPenTipListener(PenTipListener listener) Adds a listener for pen tip events for all pages the penlet owns.
abstract void	addPenTipListener(PenTipListener listener, Region region) Adds a listener for pen tip events for the specific region on all pages the penlet owns.
abstract void	addRegionEnterExitListener(RegionEnterExitListener listener) Adds a listener for region enter/exit events for all regions on all pages the penlet owns.
abstract void	addRegionEnterExitListener(RegionEnterExitListener listener, Region region) Adds a listener for region enter/exit events for the specified region on all pages the penlet owns.
abstract void	addStrokeListener(StrokeListener listener) Adds a listener for stroke events for all pages the penlet owns.
abstract void	addStrokeListener(StrokeListener listener, Region region) Adds a listener for stroke events for the specific region on all pages the penlet owns.
abstract Config	getAppConfiguration() Gets the application configuration.
abstract RegionCollection	getCurrentRegionCollection() Gets the RegionCollection for the current page.
abstract Display	getDisplay() Gets the display instance.
PenHardware	getHardware() Get info about the pen
ICRContext	getICRContext(int delay, HWRListener listener) Creats an ICR recognition context for recognition of text for the current locale and default writing style (WritingStyle.DEFAULT).
abstract ICRContext	getICRContext(int delay, HWRListener listener, Language language, WritingStyle style) Deprecated.
abstract ICRContext	getICRContext(int delay, HWRListener listener, Locale locale, WritingStyle style) Creates an ICR recognition context for recognition of text for a specified language and writing style.
int	getId() Gets the identifier for the application.
abstract PenletStorage	getInternalPenletStorage() Gets the persistant storage to be used by the application.
abstract String	getName() Gets the name of the penlet.
abstract Object	getProperty(String prop) Gets the value of the specified property.
QuickLaunch	getQuickLaunch() Get a QuickLaunch object which allows editing of the dynamic Quick Launch menu items associated with this penlet
RegionCollection	getRegionCollection(PageInstance page) Gets a region collection for the page instance passed.
abstract ResourceBundle	getResourceBundle() Gets the resource bundle for the current locale.
abstract ResourceBundle	getResourceBundle(Locale locale) Gets the resource bundle for a specific locale.
abstract SystemConfig	getSystemConfiguration() Gets the system configuration instance.
abstract void	hideMuteWarning() Hides a warning to user that volume is MUTED.
abstract void	installPlugin(PenletPlugin plugin) Installs the specified plugin but does not activate it.
abstract boolean	isRecordingInProgress() Indicates if the system is currently recording or not.
abstract void	notifyCanProcessMenuEvents(boolean process) The application notifies the system that it can now process or not process menu events.
abstract void	notifyDataOnDisplay(boolean valid) Allows the application to notify the system that display has data.
abstract boolean	notifyStateChange(boolean requestActive) Allows the application to request the system that it wants to change its state.
abstract void	playDefaultLeftAPM(boolean enable) The system plays a default sound when a left menu event is passed to the application.
abstract void	playDefaultRightAPM(boolean enable) The system plays a default sound when a right menu event is passed to the application.
abstract void	removeAreaEnterExitListener(AreaEnterExitListener listener) Deprecated. use removeRegionEnterExitListener(RegionEnterExitListener)
abstract void	removeCoordinateListener(CoordinateListener listener) Removes the coordinate listener that was added earlier.
abstract void	removePaperListener(PaperListener listener) Removes the paper listener that was added earlier.
abstract void	removePentipListener(PenTipListener listener) Deprecated. use removePenTipListener(PenTipListener)
abstract void	removePenTipListener(PenTipListener listener) Removes the pen tip listener that was added earlier.
abstract void	removeRegionEnterExitListener(RegionEnterExitListener listener) Removes the region enter/exit listener that was added earlier.
abstract void	removeStrokeListener(StrokeListener listener) Removes the stroke listener that was added earlier.
abstract boolean	requestActivation(long delay) Requests the penlet to be activated after the specified time.
byte[]	sendServiceRequest(String className, byte[] data) This will start a penlet and pass the data array to it and return a result.
abstract void	setProperty(String prop, Object value) Sets a property specific to this instance of a penlet context.
abstract void	showMuteWarning() Shows a warning to the user that the volume is MUTED.
abstract void	uninstallPlugin(PenletPlugin plugin) Uninstalls the specified plugin.

Methods inherited from class java.lang.Object

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

Field Detail

instanceId

protected int instanceId

Constructor Detail

PenletContext

protected PenletContext(int instanceID)

Creates a new penlet context having the specified instance ID.

Parameters:

instanceID - the instance ID

Method Detail

addMetricData

public void addMetricData(String metricName)

Add a metric with empty data.

Parameters:

metricName - name of the metric that the app wants to track

See Also:

addMetricData(String, Object), addMetricData(String, Object[])

addMetricData

public void addMetricData(String metricName,
                          Object data)

Add a metric with data.

Parameters:

metricName - name of the metric that the app wants to track

data - any object that contains the metric data. This cannot be null

See Also:

addMetricData(String), addMetricData(String, Object[])

addMetricData

public abstract void addMetricData(String metricName,
                                   Object[] data)

Add metric data associated with the penlet.

Parameters:

metricName - name of the metric that the app wants to track

data - an array of objects that contains the metric data. This cannot be null

See Also:

addMetricData(String), addMetricData(String, Object)

isRecordingInProgress

public abstract boolean isRecordingInProgress()

Indicates if the system is currently recording or not.

Returns:

true if the system is currently recording and false if the system is not recording.

addAreaEnterExitListener

public abstract void addAreaEnterExitListener(AreaEnterExitListener listener)

Deprecated. use addRegionEnterExitListener(RegionEnterExitListener)

Adds a listener for region enter/exit events for all regions on all pages the penlet owns. This function no longer provides functionality and remains as a stub to provide an upgrade path to usage of RegionEnterExitListener.

Parameters:

listener - add this listener

addAreaEnterExitListener

public abstract void addAreaEnterExitListener(AreaEnterExitListener listener,
                                              Region region)

Deprecated. use addRegionEnterExitListener(RegionEnterExitListener,Region)

Adds a listener for region enter/exit events for the specified region on all pages the penlet owns. This function no longer provides functionality and remains as a stub to provide an upgrade path to usage of RegionEnterExitListener.

Parameters:

listener - add this listener

region - region for which the application wants to monitor enter/exit events.

addRegionEnterExitListener

public abstract void addRegionEnterExitListener(RegionEnterExitListener listener)

Adds a listener for region enter/exit events for all regions on all pages the penlet owns.

Parameters:

listener - add this listener

addRegionEnterExitListener

public abstract void addRegionEnterExitListener(RegionEnterExitListener listener,
                                                Region region)

Adds a listener for region enter/exit events for the specified region on all pages the penlet owns.

Parameters:

listener - add this listener

region - region for which the application wants to monitor enter/exit events.

addPenTipListener

public abstract void addPenTipListener(PenTipListener listener)

Adds a listener for pen tip events for all pages the penlet owns.

Parameters:

listener - add this listener

addPenTipListener

public abstract void addPenTipListener(PenTipListener listener,
                                       Region region)

Adds a listener for pen tip events for the specific region on all pages the penlet owns.

Parameters:

listener - add this listener

region - region for which the application wants to monitor pen tip events

addStrokeListener

public abstract void addStrokeListener(StrokeListener listener)

Adds a listener for stroke events for all pages the penlet owns.

Parameters:

listener - add this listener

addStrokeListener

public abstract void addStrokeListener(StrokeListener listener,
                                       Region region)

Adds a listener for stroke events for the specific region on all pages the penlet owns.

Parameters:

listener - add this listener

region - region for which the application wants to monitor stroke events

addPaperListener

public abstract void addPaperListener(PaperListener listener)

Adds a listener for paper events

Parameters:

listener - add this listener

removePaperListener

public abstract void removePaperListener(PaperListener listener)

Removes the paper listener that was added earlier.

Parameters:

listener - listener that should be removed. This MUST be a non-null instance

removeAreaEnterExitListener

public abstract void removeAreaEnterExitListener(AreaEnterExitListener listener)

Deprecated. use removeRegionEnterExitListener(RegionEnterExitListener)

Removes the region enter/exit listener that was added earlier. This function no longer provides functionality and remains as a stub to provide an upgrade path to usage of RegionEnterExitListener.

Parameters:

listener - listener that should be removed. This MUST be a non-null instance

removeRegionEnterExitListener

public abstract void removeRegionEnterExitListener(RegionEnterExitListener listener)

Removes the region enter/exit listener that was added earlier.

Parameters:

listener - listener that should be removed. This MUST be a non-null instance

removePentipListener

public abstract void removePentipListener(PenTipListener listener)

Deprecated. use removePenTipListener(PenTipListener)

Removes the pen tip listener that was added earlier.

Parameters:

listener - listener that should be removed. This MUST be a non-null instance

removePenTipListener

public abstract void removePenTipListener(PenTipListener listener)

Removes the pen tip listener that was added earlier.

Parameters:

listener - listener that should be removed. This MUST be a non-null instance

removeStrokeListener

public abstract void removeStrokeListener(StrokeListener listener)

Removes the stroke listener that was added earlier.

Parameters:

listener - listener that should be removed. This MUST be a non-null instance

addCoordinateListener

public abstract void addCoordinateListener(CoordinateListener listener)

Adds a listener for coordinate events.

Parameters:

listener - listener that should be added. This MUST be a non-null instance

removeCoordinateListener

public abstract void removeCoordinateListener(CoordinateListener listener)

Removes the coordinate listener that was added earlier.

Parameters:

listener - listener that should be removed. This MUST be a non-null instance

getAppConfiguration

public abstract Config getAppConfiguration()

Gets the application configuration. This always a non-null instance even if the application does not have a config file specified.

Returns:

configuration data for the application.

getCurrentRegionCollection

public abstract RegionCollection getCurrentRegionCollection()

Gets the RegionCollection for the current page.

Returns:

a region collection instance.

getRegionCollection

public final RegionCollection getRegionCollection(PageInstance page)

Gets a region collection for the page instance passed.

Parameters:

page - page instance.

Returns:

the region collection for the page instance passed.

Since:

0.5

getDisplay

public abstract Display getDisplay()

Gets the display instance.

Returns:

display instance.

getICRContext

public abstract ICRContext getICRContext(int delay,
                                         HWRListener listener,
                                         Language language,
                                         WritingStyle style)

Deprecated.

getICRContext

public abstract ICRContext getICRContext(int delay,
                                         HWRListener listener,
                                         Locale locale,
                                         WritingStyle style)

Creates an ICR recognition context for recognition of text for a specified language and writing style. The best place to call this method is in activateApp. Additionally, the best place to call the matching dispose method is in deactivateApp.

The delay is measured from when strokes are added to the context. The timing will actually be greater than or equal to this value because the recognition engine varies in the time it takes to recognize strokes.

NOTE: The ICRContext.dispose() method should be called before trying to create a new ICRContext with this method. One way to do this is to call dispose at the start of deactivateApp. This will guarantee that no previous code in the method will throw an uncaught exception. Any inadvertent uncaught exception would prevent dispose from executing.

Parameters:

delay - timeout in milliseconds that should be used for user pauses

listener - a listener that would process ICR events

locale - the language to be used for the handwriting.

style - the writing style to be used for the context.

Returns:

a context for managing the ICR engine.

See Also:

ICRContext.dispose(), HWRListener.hwrUserPause(long, String)

getICRContext

public ICRContext getICRContext(int delay,
                                HWRListener listener)

Creats an ICR recognition context for recognition of text for the current locale and default writing style (WritingStyle.DEFAULT).

Please see the note in the other getICRContext method for how to properly dispose of the returned instance.

Parameters:

delay - timeout in milliseconds that should be used for user pauses

listener - a listener that would process ICR events

Returns:

a context for managing the ICR engine.

See Also:

getICRContext(int, HWRListener, Language, WritingStyle), ICRContext.dispose(), HWRListener.hwrUserPause(long, String)

getId

public int getId()

Gets the identifier for the application. This is a system generated identifier.

Returns:

the instance id

getInternalPenletStorage

public abstract PenletStorage getInternalPenletStorage()

Gets the persistant storage to be used by the application.

Returns:

the storage for persistand data.

getName

public abstract String getName()

Gets the name of the penlet.

Returns:

a String of the penlet name

getSystemConfiguration

public abstract SystemConfig getSystemConfiguration()

Gets the system configuration instance. The system configuration cannot be modified by application.

Returns:

system configuration instance.

notifyDataOnDisplay

public abstract void notifyDataOnDisplay(boolean valid)

Allows the application to notify the system that display has data. This should be used when the app gets deactivated and wants to let the system know that the data it has written on the display is data

Parameters:

valid - true if the display has data and false otherwise.

notifyStateChange

public abstract boolean notifyStateChange(boolean requestActive)

Allows the application to request the system that it wants to change its state. The only state changes allowed are active or inactive

Parameters:

requestActive - true indicates that the app wants to change to an active state and false if the app wants to change to the inactive state

Returns:

true if the state change was granted and false the state change was denied or the app was already in the state that it wants to change to.

requestActivation

public abstract boolean requestActivation(long delay)

Requests the penlet to be activated after the specified time. If the penlet is already active, then this does not have any effect.

Parameters:

delay - time after which the penlet has to be activated.

Returns:

true if the request was granted and false if the request was denied.

showMuteWarning

public abstract void showMuteWarning()

Shows a warning to the user that the volume is MUTED. The typical use-case for this method is for applications whose functionality is bound to audio part and would want to warn the user to unmute.

hideMuteWarning

public abstract void hideMuteWarning()

Hides a warning to user that volume is MUTED.

See Also:

showMuteWarning()

getResourceBundle

public abstract ResourceBundle getResourceBundle()

Gets the resource bundle for the current locale. This will always load a file named "message.properties".

Returns:

resource bundle. This will always return a non-null instance.

Since:

0.4

getResourceBundle

public abstract ResourceBundle getResourceBundle(Locale locale)

Gets the resource bundle for a specific locale. This will always load a file named "message.properties".

Parameters:

locale - get the bundle specific to this locale

Returns:

a resource bundle. This will always return a non-null instance.

notifyCanProcessMenuEvents

public abstract void notifyCanProcessMenuEvents(boolean process)

The application notifies the system that it can now process or not process menu events. The default value is that any application that implements MenuEventListener will automatically process menu events. Only apps that needs to selectively enable or disable the app menu will need this method. Calling this method has no effect if the application does not implement MenuEventListener.

Parameters:

process - true (the default) if it can process menu events and false if it cannot.

Since:

0.4

playDefaultRightAPM

public abstract void playDefaultRightAPM(boolean enable)

The system plays a default sound when a right menu event is passed to the application. This method can be used by the application to disable the default behavior if it wants to provide alternate sound when the event happens.

Parameters:

enable - true to play the default sound for right menu event.

Since:

0.6

playDefaultLeftAPM

public abstract void playDefaultLeftAPM(boolean enable)

The system plays a default sound when a left menu event is passed to the application. This method can be used by the application to disable the default behavior if it wants to provide alternate sound when the event happens.

Parameters:

enable - true to play the default sound for left menu event.

Since:

0.6

installPlugin

public abstract void installPlugin(PenletPlugin plugin)

Installs the specified plugin but does not activate it. If the plugin is null or is already installed then this does nothing. Note that the plugin is not activated by installing it.

Parameters:

plugin - install this plugin

Since:

2.3

See Also:

uninstallPlugin(PenletPlugin), PenletPlugin.activate()

uninstallPlugin

public abstract void uninstallPlugin(PenletPlugin plugin)

Uninstalls the specified plugin. This does nothing if the plugin is not already installed. Note that the plugin is not deactivated by uninstalling it.

Parameters:

plugin - uninstall this plugin

Since:

2.3

See Also:

installPlugin(PenletPlugin), PenletPlugin.deactivate()

setProperty

public abstract void setProperty(String prop,
                                 Object value)

Sets a property specific to this instance of a penlet context. Plugins, for example, could use properties to inter-communicate.

Parameters:

prop - the property to set

value - the new property value

Throws:

NullPointerException - if the property is null.

Since:

2.3

See Also:

getProperty(String)

getProperty

public abstract Object getProperty(String prop)

Gets the value of the specified property. This will return null if the property is not set.

Parameters:

prop - query this property

Returns:

the property's value, or null if it is not set.

Throws:

NullPointerException - if the property is null.

Since:

2.3

See Also:

setProperty(String, Object)

sendServiceRequest

public byte[] sendServiceRequest(String className,
                                 byte[] data)

This will start a penlet and pass the data array to it and return a result.

Parameters:

className - className to send request to, this must match the penlet's manifest Penlet-Class property

data - byte array of data to send to the penlet

Returns:

byte array of data returned by the penlet's RequestListener.onRequest

Since:

2.5

getHardware

public PenHardware getHardware()

Get info about the pen

Since:

2.5

getQuickLaunch

public QuickLaunch getQuickLaunch()

Get a QuickLaunch object which allows editing of the dynamic Quick Launch menu items associated with this penlet

Since:

2.5