com.livescribe.penlet
Class PenletPlugin

java.lang.Object
  com.livescribe.penlet.PenletPlugin

Direct Known Subclasses:

AbstractPenletPlugin

public abstract class PenletPlugin
extends Object

A base class for all penlet plugins. A plugin has the ability to temporarily replace the display contents and to intercept penlet events.

An example of where this is useful is a subsystem that tells the user to draw a Prompt and Believe button. Having all the logic in a plugin removes the need for doing more work to support a specific feature from inside a penlet. Otherwise, the penlet would need to manage more states and data.

Another example is a logger that intercepts pen events.

Plugins can consume events by returning false from any of its event handling methods. Consumed events will not be passed on to the application.

Don't forget that plugins may choose not to handle events. This means that if an application uses plugins then they should check whether any relevant plugins are active. For example, a plugin may choose to assign meaning to only the NavPlus right arrow. It may handle this but will pass all other menu events to the application. Thus, the application needs to check the active state of that plugin before deciding what to do with all the other non-right arrow menu events.

A note on receiving events after the plugin is activated: Let's say a plugin is activated on a pen-down or region-enter event in a penlet. The plugin will now intercept everything after it has been activated, which means it will receive the region-exit, pen-up, and any taps that come later. Be careful when handling the pen tip, region, and stroke events in both the penlet and plugin processing logic.

Some ways to handle this include:

1. One way to handle this is to have the plugin ignore everything up to and including the pen-up-related event. This includes the following tap and stroke events.
2. Another way to handle this is to have the penlet not activate the plugin until after all events relating to lifting the pen have been handled. Again, this includes a final pen-up event, a possible single- or double-tap, and a stroke.
3. Yet a third, and probably the simplest, way is to have the plugin ignore everything until the next pen-down or menu event.

Plugins can share information via context properties.

A note on receiving menu events: A penlet must implement MenuEventListener in order for any installed and active plugins to receive any menu events. This is a current limitation in the system.

Since:

2.4

See Also:

isActive(), com.livescribe.event, PenletContext.installPlugin(PenletPlugin), PenletContext.uninstallPlugin(PenletPlugin), PenletContext.setProperty(String, Object)

Constructor Summary

protected

PenletPlugin(Penlet penlet) Creates a new penlet plugin and uses the context of the specified Penlet.

Method Summary

abstract void	activate() Activates the plugin.
abstract void	addPluginListener(PluginListener l) Adds a listener that's notified when the plugin changes state.
abstract void	deactivate() Deactivates the plugin.
protected Display	getDisplay() Gets the current Display.
Penlet	getPenlet() Gets the penlet to which this plugin is attached.
abstract boolean	isActive() Returns whether the plugin is currently active.
boolean	onCoordinateEvent(CoordinateEvent ev) Handles a coordinate event.
boolean	onDocumentEvent(DocumentEvent ev) Handles a document event.
boolean	onMenuEvent(MenuEvent ev) Handles a menu event.
boolean	onPenTipEvent(PenTipEvent ev) Handles a pen tip event.
boolean	onRegionEvent(RegionEvent ev) Handles a region event.
boolean	onStrokeEvent(StrokeEvent ev) Handles a stroke event.
abstract void	removePluginListener(PluginListener l) Removes a listener that's notified when the plugin changes state.
protected void	restoreDisplay() Restores the screen stored with saveDisplay().
protected void	saveDisplay() Stores the current screen contents so that it may be replaced and then restored at a later time.

Methods inherited from class java.lang.Object

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

Constructor Detail

PenletPlugin

protected PenletPlugin(Penlet penlet)

Creates a new penlet plugin and uses the context of the specified Penlet.

Parameters:

penlet - the penlet

Method Detail

getPenlet

public Penlet getPenlet()

Gets the penlet to which this plugin is attached.

Returns:

the attached penlet.

saveDisplay

protected void saveDisplay()

Stores the current screen contents so that it may be replaced and then restored at a later time.

See Also:

restoreDisplay()

restoreDisplay

protected void restoreDisplay()

Restores the screen stored with saveDisplay().

See Also:

saveDisplay()

getDisplay

protected Display getDisplay()

Gets the current Display.

Returns:

Display object

See Also:

Display

addPluginListener

public abstract void addPluginListener(PluginListener l)

Adds a listener that's notified when the plugin changes state. This should do nothing if the specified listener is null.

Note that this does not specify what happens if a listener is added more than once.

Parameters:

l - the listener to add

removePluginListener

public abstract void removePluginListener(PluginListener l)

Removes a listener that's notified when the plugin changes state. This should do nothing if the specified listener is null or is not in the listener list.

Parameters:

l - the listener to remove

isActive

public abstract boolean isActive()

Returns whether the plugin is currently active.

Returns:

whether the plugin is currently active.

See Also:

activate(), deactivate()

activate

public abstract void activate()
                       throws PenletStateChangeException

Activates the plugin. It is up to the plugin to determine what happens if it is activated more than once. A common behavior is to simply ignore any new activation requests.

Any necessary plugin setup is done here. Additionally, any registered plugin listeners are notified when the plugin has finished activating.

This may throw a PenletStateChangeException if the plugin was not activated. A plugin may decide that certain conditions are not met and decide not to activate. One example is if an attempt is made to activate the plugin more than once and the plugin disallows this. A useful method is PenletStateChangeException.getCause() for determining the underlying cause for an unsuccessful activation request.

Throws:

PenletStateChangeException - if the plugin could not be activated.

See Also:

deactivate(), isActive(), PluginListener, PenletStateChangeException.getCause()

deactivate

public abstract void deactivate()

Deactivates the plugin. This does nothing if the plugin is not active.

Any necessary plugin cleanup is done here. Additionally, any registered plugin listeners are notified when the plugin has finished deactivating.

See Also:

activate(), isActive(), PluginListener

onCoordinateEvent

public boolean onCoordinateEvent(CoordinateEvent ev)

Handles a coordinate event. This returns false by default, indicating that the event is consumed.

Note that the event can also be marked as consumed to prevent the penlet from receiving the event, even if this returns false.

Parameters:

ev - the coordinate event

Returns:

whether the menu event was handled; the default implementation returns false.

See Also:

Event.consume(), CoordinateListener

onMenuEvent

public boolean onMenuEvent(MenuEvent ev)

Handles a menu event. This returns false by default, indicating that the event is consumed.

Note that the event can also be marked as consumed to prevent the penlet from receiving the event, even if this returns false.

Parameters:

ev - the menu event

Returns:

whether the menu event was handled; the default implementation returns false.

See Also:

Event.consume(), MenuEventListener

onPenTipEvent

public boolean onPenTipEvent(PenTipEvent ev)

Handles a pen tip event. This returns false by default, indicating that the event is consumed.

Note that the event can also be marked as consumed to prevent the penlet from receiving the event, even if this returns false.

Parameters:

ev - the pen tip event

Returns:

whether the event was handled; the default implementation returns false.

See Also:

Event.consume(), PenTipListener

onStrokeEvent

public boolean onStrokeEvent(StrokeEvent ev)

Handles a stroke event. This returns false by default, indicating that the event is consumed.

Note that the event can also be marked as consumed to prevent the penlet from receiving the event, even if this returns false.

Parameters:

ev - the stroke event

Returns:

whether the event was handled; the default implementation returns false.

See Also:

Event.consume(), StrokeListener

onRegionEvent

public boolean onRegionEvent(RegionEvent ev)

Handles a region event. This returns false by default, indicating that the event is consumed.

Note that the event can also be marked as consumed to prevent the penlet from receiving the event, even if this returns false.

Parameters:

ev - the region event

Returns:

whether the event was handled; the default implementation returns false.

See Also:

Event.consume(), RegionEnterExitListener

onDocumentEvent

public boolean onDocumentEvent(DocumentEvent ev)

Handles a document event. This returns false by default, indicating that the event is consumed.

Note that the event can also be marked as consumed to prevent the penlet from receiving the event, even if this returns false.

Parameters:

ev - the document event

Returns:

whether the event was handled; the default implementation returns false.

See Also:

Event.consume(), PaperListener