Kinoma Documentation

Developer Guide

"KPS" is the definitive document for developers creating software using Kinoma Play Script. The document consists of two parts. The first part is a comprehensive overview, which introduces major KPS concepts together with simple examples. The second part is a complete reference to KPS objects, arranged in alphabetical order.

The source code of Kinoma apps consists of one or more XML files. The XML mark-up defines the structure of the app. Developers add scripts to the mark-up to implement specific behaviors for their applications. This document describes both the XML mark-up format used by Kinoma Play Script and the scripts that developers write.

For scripts, Kinoma Play Script uses the programming language commonly known as JavaScript. This language is formally defined in the ECMAScript 5th edition language specification. Please note that while Kinoma Play Script uses the JavaScript programming language, the runtime environment is not a web browser so there are differences from developing web pages. There are many excellent tutorials available on-line for programmers getting started with JavaScript. We suggest Douglas Crockford's excellent survey and his Code Conventions for the JavaScript Programming Language.

Tutorials

Kinoma Create includes a growing number of Tutorials to get you started, including:

• Building your first app The classic "Hello World"
• Installing the Example Apps: Step by step instructions to get the code samples loaded in a project in Kinoma Create
• Testing Your App On an Android Device: This tutorial guides you through setting up an android device with a debug version of Kinoma Play and wirelessly testing your app on the device.

Code Samples

Short sample code snippets or small Kinoma Play apps,built into Kinoma Create, that illustrate best practices for the features you want to implement.

• Align: This example shows how the different alignment options of a cell's style attributes impact layout. It provides a test bed to explore KPS alignment.
• Effects: This sample demonstates how to apply different visual effects. Two sample images are drawn using a variety of effects defined using a combination of colorize, opacity, shadows, hilights, glows, masks, and shading. This example shows effects applied to images; they may also be applied to thumbnails.
• Files: This example shows how to perform several common file system operations. KPS restricts access to FileSystem APIs to handlers with a require attribute with a value that includes FileSytem. The example shows how to browse the full device file system and locate the application directory, as well as read, write, delete and get information about files.
• GPS: This example demonstrates how to retrieve the GPS location of the host device. Retrieving the location is an asyncronous operation. Note: when run on the Kinoma Simulator, an IP-to-location service is used to determine the location.
• HTTP header: This example shows how to add headers to an HTTP request, and how to retrieve headers from an HTTP response. Note: most applications don't need to manipulate HTTP headers directly, but there are some circumstances where it is necessary.
• Image draw: This example shows how to draw into an offscreen image buffer. This is useful if your application wants to render a complex image once, and then redraw it several times. The offscreen buffer is an image asset without an image file to initialize its contents. KPS canvas drawing functions are used to render the contents of the image buffer. The drawing canvas is obtained using getContext("kps-2d");
• Icon sizes: This example shows how the drawIcon function of the KPS canvas automatically selects the optimal icon size to use when rendering an icon at different dimensions.
• Jump back: This example demonstrates how to skip over views in the Back button stack. This capability is most commonly used to provide a button to return to an application's main view from anywhere in the view hierarchy.
• Mosaic: This example demonstrates how to use the mosaic control in a KPS view. The mosaic control embeds a grid inside of a KPS table (list) view. In addition, unlike a grid view which uses a system defined cell size, the mosaic control lets the application developer to determine the dimensions of the grid's cells. The result of a Twitter search is used to populate the grid cells.
• Multitouch: This example shows how to implement multitouch interactions. The sample demonstrates moving, scaling, and rotating an image using common one and two finger operations. The image maniupation is described using a matrix and rendered using projectImage. The sample uses a full screen custom layout.
• OAuth2: This example shows how to log into a web service using OAuth 2.0. The service used in the example is foursquare, but the technique can be applied to other services. To run the example, you will need to enter your own client_id and client_secret in the source code. The sample incorporates a minimal HTTP server in application.xml. Once the user successfully logs into the service using OAuth 2.0, the local web browser makes a request to the HTTP server built into this sample. That request invokes the "authorized" handler, passing the log-in token in query.code.
• Panes: This example demonstrates how to use panes to build more complex views. Each pane can be independently positioned, and contains its own layout cells. In this example, the first pane selects the kind of data to show in the second pane.
• Picker: This example shows how to use the horizontal picker control to display a list of numbers.
• Quotes: This example shows how to implement a simple dashboarder. The dashboarder displays a new quote every minute in the Play Dashboard. Tap a quote to launch a Google search for it in your browser.
• Seach Library: This example shows how to perform a search on the KPS media library. It demonstrates how to search on different media types, and how to filter and sort the search results.
• Switch: This example shows how to create a custom KPS touch control. It implements a simple on/off switch, with touch tracking and animation.
• Synonyms: This example shows how to implement a simple dashboarder. The dashboarder displays synonyms in the Search Dashboard. The widths of the cell depend on their content. Tap a synonym to get its synonyms, and so on.
• Tabs: This example shows how to implement a tabbed view. The tabs are located in the footer of the view. In this example, each of the three tabs uses a different KPS body type: table, grid, and custom. The time tab shows how to use expireViewer and KPS.formatTime to implement a simple clock.
• Transitions: This example shows how to define which transitions are used when traveling between viewers, and how to implement your own custom transitions with parameters. You'll learn how to use toChild and fromChild to specify parent/child transitions, and how to optionally override them with fromParent and toParent in a child viewer. Sibling transitions may also be specified using next and previous. The code also demonstrates how to use projectImageTwo() to draw rotated images.
• Translate: This example demonstrates how to implement a translation application. The Microsoft Translator service is used to perform the translation. The application maintains a history of translated words and phrases using KPS preferences. The application demonstrates how to implement different layouts for portrait and landscape modes.
• Splash Screen: This example demonstrates how to display a brief splash screen when entering a KPS application. It shows how to use goBack to skip over the splash screen viewer when the user goes back from the main viewer. Note: splash screens are generally unnecessary in KPS applications. This example is provided because it is a common developer request.
• Trigger versus Redirect: This example is a simple testbed to understand the difference between redirect and trigger when working with KPS handlers. The difference between redirect and trigger is a little subtle, but important to understand for creating KPS applications. Both trigger and redirect invoke a handler. The difference is that trigger changes the viewer binding, whereas redirect does not.
• YouTube: This example shows how to embed a YouTube video player into a KPS view. It also shows how to retrieve a compact-JSON (jsonc) feed from YouTube and render it as a KPS list. The YouTube video is identified through the same URI used to view it on the YouTube web site, such as http://www.youtube.com/watch?v=RKV2bHpiH1E. KPS can optionally provide playback controls for the video. Video playback is handled by the KPS YouTube service, so it inherits all its intelligence including automatically selecting the best video format based on available network bandwidth and media codecs available on the host device.