HTCdev

Scribe Pen API Overview

The Pen API consists of a rich framework for creating drawing applications using HTC tablets that provide HTC Scribe technology, such as the HTC Flyer, HTC EVO View and the HTC Jetstream. As illustrated by the preloaded native pen applications such as the notepad application, this framework provides the ability to interact with the pen's buttons and provides the pen controls, settings and properties that are available to the native applications, for example, the pen menu and features such as the ability to provide history and undo.

NOTE: the Pen API targets Android 3.1 (HoneyComb - API Level 12) and above only - except where noted below for the low level api only where a compatibility example is provided. ICS (Android 4.0) support is forthcoming and will only effect the low level api but existing api will continue to be supported in parallel (more information below).

API Packages

The following packages comprise the Pen API portion of the Open Sense SDK

• com.htc.painting.engine
• com.htc.painting.engine.render
• com.htc.painting.engine.stroke
• com.htc.painting.penmenu
• com.htc.painting.tool.pen
• com.htc.pen

The com.htc.painting.engine package and its subpackages handle all aspects of the drawing stroke events and properties such as handling the painting view and associated view port.

The com.htc.painting.penmenu package provides the UI widget for selecting pen settings for drawing on a painting view and to execute functions such as undo, redo, clear.

The com.htc.painting.tool.pen package handles all the core pen properties and associated utilities.

The com.htc.pen package provides the low level support for handling pen events.

The following chart illustrated the various options available when using the OpenSense SDK vs rolling your own code and the combinations available.

Beginning with Android 4.0 (ICS = Ice Cream Sandwich), there is low level pen api provided by the Android platform, specifically using the MotionEvent class. The HTC low level pen API, provided in the PenEvent class similarly uses the MotionEvent class and will be replaced by the standard Android Pen API. Since the rest of the framework is built on top of the low level api as shown in the overview above, the majority of the Pen framework will not be affected. Support for HTC's low level API provided in PenEvent will continue giving developers the option of both APIs.

The SDK includes the following example code projects to help you familiarize yourself with the Pen API portion of the SDK:

HelloPen sample

The basic "hello world" application illustrating a basic drawing application.

PenMenu example

This example project illustrates a drawing application that can bring up and hide the PenMenu UI control and how to interact with the PenMenu to select pen properties.

PaintScrollingView example

This example is a drawing application that illustrates the ability to create a scrollable view surface for drawing beyond the visible area as well as how to interact with custom controls instead of the PenMenu for selecting pen properties.

PenEvent example

This example illustrates how to use the low level access to the pen functionality, namely the PenEvent class. PenEvents are handled similarly to standard MotionEvents, both of which are handled in the onTouch method for the specific surface view that will handle pen events.

This example is provided for those who do not require the full framework as illustrated by the previous two examples which is the preferred way to use the pen APIs for all drawing applications. This example is a simple drawing application that shows how to access the pen's buttons and basic PenEvent actions and also illustrates how to handle both touch and pen events in the same drawing view.

Examples where only the low level access to the PenEvent API are applications that do not need to draw or already have drawing functionality. For example porting existing applications such as photo editing applications or applications that only need basic access to pen input for custom applications.

PenEventCompatibility example

This example provides the same functionality as the previous PenEvent example with the exception that with the provided compatibility jar library it is a modification of the previous example which works only on Android 3.x (Honeycomb) and above to accommodate also running on Android 2.3 (Gingerbread) devices (note: most tablet devices on 3.x have already updated to 3.x) to bring applications to market targeting devices that have yet to be updated to Android 3.x (Honeycomb). Note: currently this compatibility example also adds fallback support for non pen scribe devices such as the emulator (i.e. to simulate a pen in the emulator, use the standard touch input and a specific modifier key to differentiate from standard touch events - see Sample Code section for specific key support provided).

SingleAPKDemo example

This example demonstrates how to provide pen api functionality for pen enabled devices as well as support for non-pen enabled devices using the same codebase and providing only one (a single) apk application file.

Note: For more detailed information of the sample code projects see the Sample Code section.