com.livescribe.penlet
Class Penlet

java.lang.Object
  com.livescribe.penlet.Penlet

public abstract class Penlet
extends Object

Penlet provides the lifecycle methods for a pen application. The services of the platform is exposed using the PenletContext class that is provided to the application as part of the initialization.

Penlet States

The following are the states the penlet goes through as part of the lifecycle.

Menu System

Menu Handling provides details on how the menu events should be handled by the apps.

Field Summary

static int	ACTIVATED_BY_EVENT Indicates that the activation occurred due a event like tapping on an area.
static int	ACTIVATED_BY_MENU Indicates that the activation occurred due to launching of the app from a menu
static int	ACTIVATED_BY_QCAPP Indicates that the Quick Commands application has delegated a command to this app.
static int	ACTIVATED_BY_SELF Indicates that the activation occurred due to the penlet making a state change using PenletInstance.notifyStateChange()
static int	ACTIVATED_BY_SYNCEVENT Indicates that the system wants this penlet to sync its data.
static int	ACTIVATED_BY_SYSEVENT Indicates that the activation occurred due a system event.
protected PenletContext	context
protected long	dataModifiedTime Holds the last modified time when the application data.
static int	DEACTIVATED_BY_APPSWITCH Indicates that the deactivation occurred because the system switched to another app.
static int	DEACTIVATED_BY_MENU Indicates that the deactivation occurred because the system switched back to main menu
static int	DEACTIVATED_BY_NOTES_MODE Indicates that the deactivation occurred due to switching to notes mode.
static int	DEACTIVATED_BY_SELF Indicates that the deactivation occurred due to the Penlet making a state change using PenletInstance.notifyStateChange()
static int	DEACTIVATED_BY_SHUTDOWN Indicates that the deactivation occurred because the system is shutdown
static int	DEACTIVATED_BY_SYCNEVENT
static int	DEACTIVATED_BY_SYSEVENT Indicates that the deactivation occurred due to some system event
protected static String	LOG_MASK_PROPERTY Property that specified the logging mask.
Logger	logger

Constructor Summary

protected

Penlet()

Method Summary

abstract void	activateApp(int reason, Object[] params) Activates the application.
boolean	canProcessOpenPaperEvents() Indicates if the application can process strokes and taps created on open paper, any unclaimed paper space.
abstract void	deactivateApp(int reason) Deactivates the application.
abstract void	destroyApp() Destroys the application.
PenletContext	getContext() Gets the penlet context.
long	getDataLastModifiedTime() Gets the time when the application last modified its data.
abstract void	initApp() Initializes the application.
void	setContext(PenletContext context) Initializes context information.

Methods inherited from class java.lang.Object

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

Field Detail

LOG_MASK_PROPERTY

protected static final String LOG_MASK_PROPERTY

Property that specified the logging mask.

See Also:

Constant Field Values

context

protected PenletContext context

logger

public final Logger logger

dataModifiedTime

protected long dataModifiedTime

Holds the last modified time when the application data.

ACTIVATED_BY_EVENT

public static final int ACTIVATED_BY_EVENT

Indicates that the activation occurred due a event like tapping on an area.

See Also:

Constant Field Values

ACTIVATED_BY_MENU

public static final int ACTIVATED_BY_MENU

Indicates that the activation occurred due to launching of the app from a menu

See Also:

Constant Field Values

ACTIVATED_BY_SELF

public static final int ACTIVATED_BY_SELF

Indicates that the activation occurred due to the penlet making a state change using PenletInstance.notifyStateChange()

See Also:

Constant Field Values

ACTIVATED_BY_SYSEVENT

public static final int ACTIVATED_BY_SYSEVENT

Indicates that the activation occurred due a system event.

See Also:

Constant Field Values

ACTIVATED_BY_SYNCEVENT

public static final int ACTIVATED_BY_SYNCEVENT

Indicates that the system wants this penlet to sync its data.

See Also:

Constant Field Values

ACTIVATED_BY_QCAPP

public static final int ACTIVATED_BY_QCAPP

Indicates that the Quick Commands application has delegated a command to this app. The first argument of args in activateApp(int, Object[]) will contain the command. NOTE: This is currently not passed to Penlets; ACTIVATED_BY_MENU is passed instead.

See Also:

Constant Field Values

DEACTIVATED_BY_APPSWITCH

public static final int DEACTIVATED_BY_APPSWITCH

Indicates that the deactivation occurred because the system switched to another app.

See Also:

Constant Field Values

DEACTIVATED_BY_SHUTDOWN

public static final int DEACTIVATED_BY_SHUTDOWN

Indicates that the deactivation occurred because the system is shutdown

See Also:

Constant Field Values

DEACTIVATED_BY_SELF

public static final int DEACTIVATED_BY_SELF

Indicates that the deactivation occurred due to the Penlet making a state change using PenletInstance.notifyStateChange()

See Also:

Constant Field Values

DEACTIVATED_BY_SYSEVENT

public static final int DEACTIVATED_BY_SYSEVENT

Indicates that the deactivation occurred due to some system event

See Also:

Constant Field Values

DEACTIVATED_BY_NOTES_MODE

public static final int DEACTIVATED_BY_NOTES_MODE

Indicates that the deactivation occurred due to switching to notes mode.

See Also:

Constant Field Values

DEACTIVATED_BY_MENU

public static final int DEACTIVATED_BY_MENU

Indicates that the deactivation occurred because the system switched back to main menu

See Also:

Constant Field Values

DEACTIVATED_BY_SYCNEVENT

public static final int DEACTIVATED_BY_SYCNEVENT

See Also:

Constant Field Values

Constructor Detail

Penlet

protected Penlet()

Method Detail

setContext

public final void setContext(PenletContext context)

Initializes context information. This is called by the platform to initialize the application with a context.

Parameters:

context - the new penlet context

getContext

public PenletContext getContext()

Gets the penlet context.

Returns:

Penlet context instance. null if called before the initApp() method is invoked and after destroyApp() is invoked.

initApp

public abstract void initApp()
                      throws PenletStateChangeException

Initializes the application. All context specific resources are initialized in this method. The application goes into Initialized state once it has fully initialized itself.

Throws:

PenletStateChangeException - if it cannot initialize itself.

activateApp

public abstract void activateApp(int reason,
                                 Object[] params)

Activates the application. The penlet goes into Active state when the call returns. All application specific events are delivered only when the app is in the Active state.

Parameters:

reason - indicates the reason for activation. This is one of the following constants ACTIVATED_BY_MENU, ACTIVATED_BY_EVENT, ACTIVATED_BY_SELF ACTIVATED_BY_SYSEVENT

params - arguments to use as part of the activation. This can be null

deactivateApp

public abstract void deactivateApp(int reason)

Deactivates the application. The penlet goes into Inactive state when the call returns. Application specific events are not delivered in the Inactive state.

Parameters:

reason - indicates the reason for de-activation. This is one of the following constants DEACTIVATED_BY_APPSWITCH, DEACTIVATED_BY_SELF, DEACTIVATED_BY_SHUTDOWN DEACTIVATED_BY_SYSEVENT

destroyApp

public abstract void destroyApp()
                         throws PenletStateChangeException

Destroys the application. The application goes into Destroyed state and is not used by the anymore. All resources allocated during initApp() must be deallocated at this point.

Throws:

PenletStateChangeException - if there was an error while destroying the penlet and moving into the destroyed state.

canProcessOpenPaperEvents

public boolean canProcessOpenPaperEvents()

Indicates if the application can process strokes and taps created on open paper, any unclaimed paper space. If this returns false then the pen will exit into notes mode just before taps and a stroke event would be delivered. If this returns true then the application will receive all events.

The name for this method is misleading because all events up to, but not including, taps and stroke events are given to the application even if this returns false. For example, pen-down, pen-up, and region events are still delivered to the application.

This default implementation returns false.

Please see the com.livescribe.event package for more details on events and event ordering.

Returns:

if the penlet can process taps and strokes made on open paper.

See Also:

com.livescribe.event

getDataLastModifiedTime

public long getDataLastModifiedTime()

Gets the time when the application last modified its data.

Returns:

pen RTC time that specified the last modification.

Since:

0.5