Release Notes - webOS SDK 3.0.0 (Build 643)

webOS SDK 3.0.0 is a major update, the primary purpose of which is to enable development for the HP TouchPad.

The most significant change for developers in webOS 3.0 is the replacement of the Mojo application framework with the new Enyo framework. The initial Enyo release focuses primarily on delivering production-ready tablet support, but Enyo will serve as the foundation for all webOS app development going forward and has been designed to let developers target tablets, phones, and future webOS form factors with a minimum of effort.

Legacy Mojo apps are supported in webOS 3.0 via a special compatibility mode, which provides a window sized for the app's original resolution, an on-screen gesture area, and access to the virtual keyboard.

All webOS developers should install the webOS 3.0 SDK. Because webOS 3.0 is currently available only for the HP TouchPad, the 3.0 SDK includes only a TouchPad emulator image. If you're working on apps for phones running earlier versions of webOS, you can use the emulator images provided with previous SDK releases. These images should remain on your system when you update to the webOS 3.0 SDK, but if necessary you can download emulator images for webOS 2.1 here.

Enyo Framework

The 3.0.0 SDK marks the first public release of the all-new Enyo development framework, the successor to the Mojo framework used in webOS 1.x and 2.x.

These are the default locations where Enyo version 1.0 will be installed on your local computer, by platform:

Windows (32-bit) 

c:\Program Files\HP webOS\SDK\share\refcode\webos-framework\enyo\1.0

Windows (64-bit) 

c:\Program Files (x86)\HP webOS\SDK\share\refcode\webos-framework\enyo\1.0

Mac/Linux 

/opt/PalmSDK/Current/share/refcode/framework/enyo/1.0

(Note: We will refer to the default installation location as <enyo-root> throughout this document.)

Highlights of the new framework include:

  • A highly flexible component system that makes it easy to build complex, reusable UI elements out of simple parts

  • A comprehensive suite of widgets to speed the development process

  • Convenient and concise handling of high-level events, which eliminates the need for tedious boilerplate code

  • The ability to run your apps in a (WebKit-based) desktop browser, not just on a webOS device or the software Emulator

For more information, see the Enyo Developer Guide and the Enyo API Reference.

Compatibility Mode

By default, applications on the TouchPad (or in the Emulator) run in a 320x480 pixel compatibility mode. To have your app run at full size, disable compatibility mode by including the following in your appinfo.json file: 

uiRevision: 2

Note for Mojo developers: Disabling compatibility mode for an app also removes the simulated gesture area, so if your Mojo app depends on gestures, you will need to provide alternative UI elements for navigation in your app when running on TouchPad.

Tools and Installers

palm-package

In the 3.0.0 SDK, the palm-package tool has been updated to properly package Enyo apps so they can be installed onto the Palm Emulator (using palm-install) and launched (using palm-launch or the webOS application launcher).

It is not necessary to include a copy of the Enyo framework inside the application, nor is it necessary to modify the script tag that includes "enyo.js", since palm-package will re-write this (to work in the emulator or device) when it builds the application package, as long as the script tag ends with "1.0/framework/enyo.js".

This means that you can develop on the desktop using a relative (or absolute) path to the Enyo framework, and palm-package will update the tag when it creates the package.

Emulator

  • The webOS Emulator now supports VirtualBox 4.0.x.

  • The 3.0 Emulator image only supports TouchPad screen resolutions. To test smaller screen resolutions, please use a 2.1 Emulator image.

Plugin Development Kit

New Hardware

The following hardware identifiers have been added: 

#define HARDWARE_VEER       301
#define HARDWARE_PRE_2      401
#define HARDWARE_PRE_3      501
#define HARDWARE_TOUCHPAD   601

Virtual Keyboard 

PDL_Err PDL_SetKeyboardState(PDL_bool bVisible);

If your application takes keyboard input, you need to be aware that with the HP TouchPad, we're starting to produce devices that do not have a physical keyboard. On these systems, you use PDL_SetKeyboardState to turn the onscreen keyboard on and off. When onscreen, the keyboard will send keyup/down SDL events. The keyboard may be dismissed by the user, so you should either provide a way for the user to toggle the keyboard on/off or always enable it when your app wants keyboard input.

Compass 

typedef struct
{
  int confidence;
  double magneticBearing;
  double trueBearing;
} PDL_Compass; 

PDL_Err PDL_EnableCompass(PDL_bool activate);
PDL_Err PDL_GetCompass(PDL_Compass *compass);

The Compass APIs are for devices that include a compass sensor, such as the HP Pre 3. Since the compass uses power, you should only enable it when it is needed. When it's turned on, you can either poll for its current setting using PDL_GetCompass or wait for PDL_Compass events to be sent through the SDL event loop.

PDK Apps in the Emulator

Starting with the webOS 3.0 Emulator, you are able to run x86-compiled PDK code in either full-screen or hybrid mode. Code using the SDL APIs is supported, but OpenGL ES is not yet functional in emulation. You need a separate x86 toolchain to build PDK code. On Windows, you can download the current CodeSourcery G++ Lite cross-compiler from http://www.codesourcery.com/sgpp/lite/ia32/portal/release1567. Note that we have seen problems with these tools when hosted on 64-bit Windows.

Hybrid Applications

Since a hybrid app runs in two separate processes, there is a delay between when the HTML's <object> tag becomes available and when the Plug-in's exposed methods can be called. The only safe way to work around this is to set up a "ready" method on the <object> from the JS side and wait until it is called via PDL_CallJS before the JS invokes Plug-in methods. On webOS 2.1 and earlier, this technique mostly worked, but since then, WebKit and adapter changes have meant that checking for a method on an <object> before it's completely constructed can cause the <object> tag to be removed from the DOM.

If you use the enyo.Hybrid control, exposed Plug-in method calls are delayed until the JavaScript receives an "I'm ready" message. For examples of enyo.Hybrid in action, see the "ShapeSpin", "FileTree", and "HybridKeyboard" PDK samples.

SDL Header Additions

The SDL structures for the mouse down/up (see below) and mouse move events have been modified to return ratioX/ratioY values that map all coordinates to a 0-1 (x), 0-1 (y) scale. So, for example, the exact center of the screen is always (0.5,0.5).

Mouse down/up event structure: 

/* Mouse button event structure */
typedef struct SDL_MouseButtonEvent {
  Uint8 type;     /* SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
  Uint8 which;    /* The mouse device index */
  Uint8 button;   /* The mouse button index */
  Uint8 state;    /* SDL_PRESSED or SDL_RELEASED */
  Uint16 x, y;    /* The X/Y coordinates of the mouse at press time */
  float32 ratioX, ratioY; /* the ratio across the window of x and y */
} SDL_MouseButtonEvent;

Code Samples

The standard SDK installation includes a collection of sample applications utilizing the Enyo framework. You'll find them on your local machine under <enyo-root>/support/examples and <enyo-root>/support/more-examples. To view an example app, enter the app directory and open the index.html file in a WebKit-based browser (e.g., Safari or Chrome).

Documentation

The documentation for SDK 3.0.0 features a new Enyo Developer Guide section, which includes a tutorial and a set of conceptual articles on a variety of topics.

Also included is the new Enyo Design Guide, which should be a useful reference as you design your application's user interface.

To begin viewing the documentation, open the file at <enyo-root>/support/docs/sdk/docs.html in a WebKit-based browser. If using Chrome, please launch the browser with the --allow-file-access-from-files command-line switch before opening docs.html.

Known Issues and Limitations

Compatibility Mode

  • Video playback is not currently working properly.

  • Mojo WebView widgets are not currently working properly.

  • The PeoplePicker API for choosing contacts in Mojo apps is not currently working.

  • The Media Capture API is currently working only for audio, not for video or still images.

  • Some apps freeze momentarily after a back gesture is performed.

  • Some apps do not launch successfully from the App Catalog, though they do launch from the webOS Launcher.

  • There is currently no Camera app on TouchPad, so apps using the cross-application Camera API will not function properly.

APIs

  • The cross-application Messaging API for starting a new message is not currently working.

  • The cross-application Calendar API for launching the calendar app and showing a specific date is not currently working.

  • The performance of some SQL transactions is currently slower than on previous devices. The difference does not noticeably affect most apps, but apps that perform individual SQL transactions for large numbers of records may be significantly impacted. Apps should limit the number of transactions by batching operations whenever possible (e.g., inserting multiple rows in a single SQL statement rather than executing a statement for each row).

  • The SQL RANDOM() function is not currently working.

  • As noted in the documentation, HTML5 video currently only supports full-screen playback.

  • Support for the Media Capture APIs has not yet been implemented in Enyo.

Tools and Installers

Emulator

Apps running in compatibility mode are currently rotated 90 degrees relative to the orientation of the Emulator's system UI (i.e., system status bar and virtual keyboard). You can still use the F6-F9 keys to rotate the Emulator, but be aware that an application running in compatibility mode will observe an orientation that does not match the Emulator's system UI orientation. This issue is further complicated by the fact that the Emulator window itself does not rotate when rotating the HP webOS Emulator image running inside it. This should not impact the actual function of most apps, even though they may seem visually unusual.

Plugin Development Kit

In the 3.0.0 release, the PDL_SetKeyboardState API has a bug in which the keyboard causes part of the application window to not be displayed.

Documentation

When viewing the documentation in the Chrome browser, links may not work correctly unless you have launched Chrome using the --allow-file-access-from-files command-line switch.