PENLETS.com

Tutorial

Penlets 101

Tutorial by Robert Hanson

---

Page 1 » Page 2

---

Ok, so you just downloaded the LiveScribe SDK but you don't know where to start. This tutorial will present you with a basic penlet that is used as the starting point for many of the tutorials on this site. Along the way we will point our things you need to know.

Setting Up You Development Environment

The first step is to setup you development environment. If you have a favorite IDE, hopefully it is either NetBeans or Eclipse, because the SDK comes with tools to make setting up a new project with these fairly easy. Both of these IDEs are free and widely used.

In the unzipped SDK there are two files; README-Eclipse.txt and README-NetBeans.txt. Open up the appropriate file and follow the steps. In both cases you want to create the basic penlet project. The Eclipse instructions refer to it as "sdk.build.basic.project" and the NetBeans instructions call it "Create Simple Penlet Project".

If you use a different IDE or don't use an IDE, well you will need to do some experimentation. To start with, you may want to start with either Eclipse or NetBeans, get a basic understanding of the directory structure, then try to move development to your favored IDE.

Whichever IDE you choose, it may be worth reading the tutorial on Developing Penlets in Eclipse. That tutorial walks you through setting up the project manually in Eclipse, and explains the location and contents of the files within the project.

A Boilerplate Penlet

So you now have your development environment all set, and created a basic project. If you created your project structure manually you won't have a main class yet, so you should copy the following source code and create a class in your /src/java/ directory. Rename the class and package names to suit your taste.

So however you got to this point, you should have a main class that looks like this. Read through the code, and then we will explain what it all does.

package com.penlets;

import com.livescribe.penlet.Penlet;
import com.livescribe.penlet.PenletStateChangeException;
import com.livescribe.display.Display;
import com.livescribe.ui.ScrollLabel;


public class MyFirstPenlet extends Penlet
{
    private Display display;
    private ScrollLabel label;


    public MyFirstPenlet ()
    {
    }

    public void initApp () throws PenletStateChangeException
    {
        this.display = this.context.getDisplay();
        this.label = new ScrollLabel();
    }

    public void activateApp (int reason, Object[] args)
    {
        if (reason == Penlet.ACTIVATED_BY_MENU) {
            this.label.draw("Hello World", true);
            this.display.setCurrent(this.label);
        }
    }

    public void deactivateApp (int reason)
    {
    }

    public void destroyApp () throws PenletStateChangeException
    {
    }
}

Starting from the top, our penlet class extends Penlet . This is the parent class of all penlets, providing access to context information and lifecycle events.

These lifecycle events are handled by four abstract methods of Penlet that we need to implement. In order these event handlers are initApp , which will be called once to initialize the penlet. In this basic template we call context.getDisplay() to get a handle to the pen's OLED display. We also create a new ScrollLabel instance. A ScrollLabel is a subclass of Canvas , which is a class that allows you to render text and graphics on the OLED display. The ScrollLabel in particular is used to render text on the OLED, and if the text is too long to fit on the display it will scroll the text so that the entire message can be read.

The next handler is activateApp , which is called when the penlet is activated. Typically this is when the penlet is selected on the pen's menu, just like the demo apps that come with the pen. In this method you will typically want to change what is displayed on the OLED or perhaps play an audio clip. In this basic penlet we take that ScrollLabel we created and set that as the current display. And we set the message in the ScrollLabel to say "Hello World".

Now eventually your penlet will be deactivated. This could be due to the user quitting the application, or maybe they just turned off the pen. This is handled by the deactivateApp handler, which also receives a code that specified the reason for the deactivation. All of the reason codes are available as static constants of the Penlet superclass. These include DEACTIVATED_BY_MENU , DEACTIVATED_BY_SHUTDOWN , and others. You will typically use this handler to free up resources that you created in activateApp . For example, you may have registered one or more event listeners like the StrokeListener or the PenTipListener that you want to unregister.

Last but not least, eventually the pen will completely shutdown the penlet, typically when the pen is powered down. This event is captured by destroyApp , allowing you to do any final cleanup that may be required.

So, whats next...

---

Page 1 » Page 2

---

Comments (View) blog comments powered by Disqus