Livescribe Pen API

See:
Description

Livescribe Pen Profile

com.livescribe.afp	This package consists of classes that interact with Anoto Functionality Document files and related APIs.
com.livescribe.buttons
com.livescribe.configuration	This package consists of classes and interfaces that provide access to configuration values and specific access to System configuration settings.
com.livescribe.display	This package consists of classes and interfaces that allows applications to render on the pen display.
com.livescribe.event	This package consists of classes and interfaces that broadcast notifications and events to penlets.
com.livescribe.ext.io	Contains I/O-related tools and classes.
com.livescribe.ext.plugins	Contains single-function plugins designed to, among other things, help the developer achieve parity with Livescribe's UI guidelines, and provide easier ways to do more difficult things, such as acquiring and recognizing handwriting from the user.
com.livescribe.ext.ui	Contains classes for conveniently creating menus, managing menu bookmarks, and doing other helpful UI-related things.
com.livescribe.ext.util	Contains miscellaneous helper utilities, including a logging helper, collections classes, and a few threading primitives.
com.livescribe.geom
com.livescribe.i18n	This package consists of classes and interfaces to aid the internationalization of application resources.
com.livescribe.icr	Provides classes and interfaces for Intelligent Character Recognition (ICR).
com.livescribe.io
com.livescribe.penlet	This package consists of classes and interfaces that are core to pen application development.
com.livescribe.storage
com.livescribe.ui
com.livescribe.util

CLDC 1.1

java.io	Provides classes for input and output through data streams.
java.lang	Provides classes that are fundamental to the Java programming language.
java.lang.ref	Provides support for weak references.
java.util	Contains the collection classes, and the date and time facilities.

MMAPI 1.2

javax.microedition.media.control
javax.microedition.media.protocol

Other Packages

com.sun.cldc.i18n	Provides classes for work with character streams.
com.sun.cldc.i18n.j2me
com.sun.cldc.i18n.uclc	Provides class for converting characters from upper case to low case.
com.sun.cldc.io	Provides base class for all connections.
com.sun.cldc.io.j2me.socket
com.sun.cldc.isolate
com.sun.cldc.util
com.sun.cldc.util.j2me	Provides implementation classes for java.util.Calendar and java.util.TimeZone.
com.sun.cldchi.io	Provides class for System.out implmentation.
com.sun.cldchi.jvm	Provides classes for interaction with VM internals.
com.sun.cldchi.test
javax.microedition.io	Classes for the Generic Connection framework.
javax.microedition.media

Livescribe Pen API

Revision History

Date	Version	Description
	0.2	Changes to MenuEventListener
	0.3	ICRContext changes to support cursive writing style com.livescribe.afp changes to support for notebook retirement
	0.4	I18N API defined in com.livescribe.i18n package
	0.5	Added AttributedText and AttributedText.Attribute classes to display package Added ScrollLabel.draw(AttributedText, boolean) method. Renamed Synchronizable to com.livescribe.penlet.Remote, SyncContext to com.livescribe.penlet.DataSender Defined com.livescribe.penlet.DataReceiver interface to read data from endpoint Added additional argument DataSender to com.livescribe.penlet.Remote#executeCommand(com.livescribe.penlet.Command, DataSender) Removed Synchronizable.hasDataToSynchronize() since it is not being used. Added com.livescribe.penlet.Remote#getDataLastModifiedTime() Added Graphics.drawString(com.livescribe.display.AttributedText, int, int, int) Changed return value of BrowseList.Item.getText() from String to Object
	0.6	Added MediaPlayer.play(java.io.InputStream, java.lang.String, boolean, int, int) method Exposed BrowseList.scrollItem(Graphics, ScrollLabel, Item, int, int) and BrowseList.drawItem(Graphics, Item, com.livescribe.display.Image, java.lang.Object, int, int) as protected methods, allowing for subclasses to provide alternate rendering implementations. Added support for subclasses to change the default decorations using the following methods BrowseList.setInsets(BrowseList.Insets) BrowseList.drawDecorations(Graphics, Item) Created new BrowseList.Insets class to define the decoration regions. Added PenletContext.playDefaultLeftAPM(boolean) PenletContext.playDefaultRightAPM(boolean) to allow applications to disable the default APM for the Left and Right APMs.
	0.7	Minor parameter naming modifications for consistency Deprecation of AreaEnterExitListener Interface. Note that the Interface stub remains in place to avoid runtime exceptions. All users of this interface must use RegionEnterExitListener as of the API 0.7 Addition of RegionEnterExitListener Interface.

Related Literature

Introduction

Livescribe's Java Application Platform is a Java ME stack for a smartpen. The components are:

MMAPI 1.2 (JSR 135)

Audio Capture

Audio Playback

Livescribe Pen Profile

Display

Event

Storage

Geometry

Configuration

Lifecycle

ICR

I18N

CLDC 1.1 (JSR 139)

The Livescribe Pen Profile supports system properties. To retrieve a property, use java.lang.System.getProperty()

Property	Description
pen.profile.version	The API revision of the pen profile. Currently it should report 0.6

Terms and Concepts

AFD	AFD stands for Anoto Functionality Document. It is a document format that describes a Paper Product. An AFD can be viewed, printed and also have applications bound to it.
AFP	AFP stands for Anoto Functionality Platform, a set of APIs to manipulate AFDs. The smartpen platform exposes a subset of this API.
Paper Product	One or more dot-enabled pages, usually with printed graphics, that have been designed to work with a penlet (or with several penlets). The dots, static regions, shapes, graphics, and dot license for the pages are specified in an AFD.
Region	Region refers to a region of interest to a penlet. It is a region of Anoto dot-space defined by a Shape. When the smartpen user performs some action on the region (such as tapping), the system sends an event to the penlet that registered for that region. Every region has an unique identifier, called a Region ID. Regions can either be: static--The regions are bound to a particular penlet when the penlet is installed. A developer designs these regions, specifying shapes, placements, and IDs in a Paper Product. Then the developer supports this fixed set of static regions explicitly in the penlet code. dynamic-- The regions are dynamically created during runtime by the penlet, in response to user activity. Subsequently, the user should be able to tap on the regions and get a penlet-defined response. The number of regions created during each execution of the penlet can vary dramatically. Both kinds of regions (static and dynamic) exhibit the same behavior when the user performs an action on them. Regions can serve as input UI controls for the penlet. You can think of them as "paper buttons." RegionCollection refers to a collection of Region on a single page of dot-enabled paper.
Fixed Print (FP) Application	Consists of a Paper Product and a penlet that claimed a piece of dot-space when the penlet was installed on the smartpen. The penlet uses the dotspace for static regions and/or for interpreting strokes made by the smartpen user. A user launches the penlet by tapping on a static Region registered to that penlet. The penlet may have other means of activation, such as the Main Menu system. In an FP application, the developer must explicitly bind the penlet to one or more paper products.
Open Paper (OP) Application	Consists of a penlet that can make use of any Open Paper. The penlet does not claim any dot-space at installation time, and the developer does not bind the penlet to a Paper Product. The penlet may create dynamic regions in response to user activity. Once created, these regions are "tappable" by the user. The user can launch an OP application by using the Main Menu on the smartpen or by tapping an existing dynamic Region. The developer is responsible for providing the functionality for these tappable dynamic Regions. All applications that are not FP apps can be thought of as OP apps, whether they actually use dot-enabled paper or not. (For instance, some applications require no paper, but only the display and audio capabilities of the smartpen.)
Notes Mode	The state of the system when no penlets are being run: the system captures strokes written by the user on dot-enabled paper. If the Default Screen is visible on the smartpen display, then the smartpen is in Notes Mode.
Data On Display	State of a penlet in which it has some data that should temporarily stay on the display before the system switches to Notes Mode. Most often occurs when a Fixed Print (FP) application is active and the user taps on Open Paper. Because the penlet has Data on Display status, the system delays starting Notes Mode very briefly. Example: A Fixed Print calculator penlet has a computational result visible on the display, and then the user taps on Open Paper. The system allows the result to remain on the display for a short while and then activates Notes Mode.
Nav Plus	Navigational control to navigate the smartpen's menu system. NavPlus controls are pre-printed on various pieces of dot-enabled paper. They are also created dynamically on Open Paper when the user draws a cross and double taps on the center of the cross.
Default Screen	Default screen, visible when no penlet owns the display.
APM	Audio Punctuation Marks. These are short sounds that are played to grab the user's attention and provide feedback for a user action.

Smartpen Application Model

A penlet is a Java application developed to interact with specific active areas defined on a Paper Product. The penlet handles smartpen events and performs actions dictated by the active regions. All applications must extend the Penlet base class. The Penlet class defines the life cycle for the application and exposes the runtime services (using PenletContext).

Each Penlet is packaged as a JAR file (standard Java archive). The jar contains the Java classes and the application resources and metadata. The following table shows the organization of the metadata:

Location in jar	Description	Required
META-INF/MANIFEST.MF	Manifest file containing penlet metadata	YES
menu.txt	Contains metadata about registering the penlet with the menu system	YES, if the application is launched from the menu.
config.txt	Configuration properties for the penlet. This is a simple property file that the penlet can access using the Config class.	NO

Context

All system services are defined by a context abstraction. Some contexts are automatically created for the penlet by the system. For instance, the system creates a (PenletContext object and makes it available to the penlet via the Penlet.context variable. Other contexts are created from an existing one, when the penlet calls a method on the existing context. For instance, the penlet can call the getIRCContext() method on a PenletContext object in order to create and access an ICRContext object.

Life Cycle

The application is in one of these four life cycle states

State	Event	Description
Initialized	Penlet.initApp()	In this state, the system has initialized the penlet with a PenletContext object. Now it can acquire resources needed for the rest of the life cycle. If resources do not require a context, however, the penlet can create them even earlier--in the penlet's constructor.
Active	Penlet.activateApp()	The penlet goes into this state when it is activated. Only one penlet can be active at any time. The penlet can be activated for various reasons (defined by Penlet.ACTIVATED_BY_XXX constants). The reason for the activation and any optional arguments are passed during this time. Penlets can acquire resources for doing work at this time.
Inactive	Penlet.deactivateApp()	A penlet goes into this state when it is deactivated. The penlet can be activated for various reasons (defined by Penlet.DEACTIVATED_BY_XXX constants). The reason for deactivation is passed to the penlet.
Destroyed	Penlet.destroyApp()	A penlet goes into this state when the runtime determines that the penlet should be unloaded. If the penlet was Active, then it is made Inactive, before the penlet enters the Destroyed state. The developer must release all the resources acquired during the Initialized phase of the life cycle. The developer must also exit any threads that were created by the penlet.

The following diagram highlights state transition during the life cycle of the penlet.

Event System

Events (defined in com.livescribe.event package) are asynchronous notification of some activity in the system. There are two ways for the penlets to register for events.

1. During design time : First, implement a listener interface on your subclass of Penlet. Listeners that can be registered during design time are:
   
• MenuEventListener
• SystemEventListener
2. During runtime time : First, implement a listener interface on a class in your penlet. Then register your listener class(es), using PenletContext's add/remove*Listener() methods.
   

User Interface

The platform provides various UI controls for the penlet.

GUI

The GUI (graphical user interface) packages enable a penlet to render text and images on the smartpen display.

Packages com.livescribe.display and com.livescribe.ui provide the infrastructure for developing GUIs, which is very similar to MIDP UI model. There are some out-of-the-box GUI components (defined in com.livescribe.display and com.livescribe.ui) that will serve most application needs. The ScrollLabel and BrowseListclasses are two such components.
Developers can create custom GUI components using Canvas and Graphics classes.

AUI

The AUI (audio user Interface) enables the penlet to play sounds on the smartpen speakers.

The Pulse Smartpen Java Application Platform supports MMAPI 1.2, which can be used to play sound. To simplify penlet development, we created a convenience class that plays sounds without requiring the developer to be an expert in MMAPI 1.2. We strongly recommend using this class for AUI, since the platform can control system-wide features within this class.

Paper UI

The paper user interface allows a penlet to be controlled by static and dynamic regions, defined by the Region class.

Intelligent Character Recognition (ICR)

The platform supports ICR (defined by com.livescribe.icr and HWRListener classes) to allow the application to get user input.

Persistence support

The Platform support reading and writing of penlet data using the PenletStorage class, which is based on java.io Input and Output streams. In addition, it supports a file system API to create, delete, and list directories and files.

The data that the penlet persists can be synchronized with Livescribe Desktop. Penlet can enable this feature by implementing the com.livescribe.penlet.Synchronizable interface. When invoked to synchronize, the penlet uses the com.livescribe.penlet.SyncContext to attach data files to be synchronized.

Menu System

The platform's menu system can perform the following

• Launch a penlet (Typically, Open Paper applications are launched from a menu.)
• Launch a penlet menu. A penlet notifies the platform that it has a penlet menu by implementing the MenuEventListener interface in its Penlet subclass.

Penlets that wish to be part of the Main Menu must provide metadata (in menu.txt file) in the application jar file.

The menu is launched by tapping anywhere on a Nav+ symbol. The user navigates through the menu system by tapping the five controls (the four directional arrows and the center of the NavPlus).