Version: 1.0.0
Introduction to
Alpha WatchBenchTM

What is WatchBench?
How to Use This Documentation
Structure of the WatchBench System
Lifecycle of a WatchBench Project When Running
What is WatchBench?
The WatchBenchTM app from Alpha Software® lets you build prototype apps for Apple Watch using just an Apple iPhone and knowledge of the JavaScript language.

You can build these prototype apps as "projects" that consist of files you edit on the iPhone. You can have any number of projects. Each may be run using the WatchBench app, though only one may be active at any given time.

When a WatchBench project is running on the watch paired with the iPhone, it appears like a normal Apple Watch app. It can have labels, buttons, sliders, images, tables of data, and more. It can be a Glance or a hierarchical app with multiple pages. The project can respond to taps on buttons or dictated input from the user. It can communicate with remote servers, sending data and fetching responses.

The projects created with WatchBench are called "prototypes" because they are not full-fledged apps. Unlike "real" apps built in native code, they are not installed separately on an iPhone or Apple Watch, and have a limited range of object layouts and position customizations on the screen. However, they can be very useful when it comes to inexpensively testing various ideas for potential apps, and can even be used for simple usability or pilot testing.

WatchBench projects are much more than simple screen mockups or wireframes. They can be working code that interacts with real data services and can, given appropriate attention to visual design, look quite polished.

WatchBench projects may be constructed quickly. The API provided to your JavaScript is powerful and concise. What may take many lines of native code can often be accomplished with a few lines of JavaScript calling WatchBench functions. There is extensive documentation built into the WatchBench iPhone app, including sample projects as well as boilerplate function calls and data structures.
Top of Page
How To Use This Documentation
You should read the introduction below about the structure of the WatchBench system and how it fits into the frameworks that iOS provides. You should then look at the other Help files, especially the one explaining the WatchBench Project Files and the App User Interface. You can either read the detailed API Reference, or try the Sample Files, reading the material they display when first loaded.

Please check the "News and Support" help file periodically. It loads and displays up-to-date information from the support web site, including about bugs, Frequently Asked Questions, where to get additional support, and other useful material.
Top of Page
Structure of the WatchBench System
In order to create projects in WatchBench, you should understand the general architecture of an iOS application that uses the WatchKit framework with Apple Watch. You also need to understand the different pieces that make up a running WatchBench project. This section covers both of those topics.

In the initial release of Apple Watch, Apple provided software developers with the WatchKit framework (a code library provided by Apple) for making custom apps. WatchBench works by using that framework.

The iOS WatchKit framework is used to give custom apps the ability to manipulate the interface of an Apple Watch app. The code for the custom app runs on the iPhone that is paired with Apple Watch, and WatchKit manages the communication between the two devices.

WatchBench app
WatchBench files
WatchKit Extension
iOS WatchKit Framework
Apple Watch
iOS WatchKit Framework
Watch Objects
WatchBench is a normal iOS app that runs on the iPhone. It has a visible user interface. It manages a variety of files on the iPhone.

In addition to the WatchBench app, there is "WatchKit extension" code that is part of WatchBench. This extension code is not visible. It runs when needed in the background, even when the visible app is not running. It is driven by the iOS WatchKit framework.

The extension has access to the same data files as the WatchBench iPhone app.

The iOS WatchKit framework communicates wirelessly with the watch, loading data, and updating the extension with information about the state of the watch, activation of the display, taps on buttons, etc.

An iOS app that supports Apple Watch always has WatchKit extension code. If the app is set with "Show App on Apple Watch" in the My Watch settings for Apple Watch on the iPhone, then certain fixed, predefined specifications about the visible interface objects (labels, buttons, switches, groups containing these, separate pages, etc.) are loaded into the watch. These specifications are fixed as part of the iPhone app itself when it is created by the iOS developer. The WatchKit API is used by the extension code to set the properties of those objects and react to various events.

The way WatchBench works is that it was built with a large set of predefined interface objects. That heavily-populated app is loaded onto the watch. When the WatchBench app is launched on Apple Watch, the WatchBench WatchKit extension then hides all of those objects except for ones that are specified in a configuration file. This allows the WatchBench developer to specify a wide range of different applications that run using the same set of predefined interface objects.

WatchBench creates a JavaScript context and loads in JavaScript code from a file. That JavaScript (JS) is then used to respond to events on the watch that come through the WatchKit framework and to make changes to objects on the watch through WatchKit calls. This JavaScript is written by the user of WatchBench and may be edited using the WatchBench iPhone app's user interface:

WatchBench app with file viewers and editor
Config files
JS files
Data files
Log files
Status files
WatchBench WatchKit Extension with JS context
WatchBench predefined labels, buttons, etc.

To create a working WatchBench project, you must create a configuration file that describes the interface objects that will be displayed. You must also create a file with the JavaScript to run in the WatchBench WatchKit extension. These files are named "initialWatchConfig.txt" and "intitialWatchJS.txt", respectively. You can also provide an optional "index.html" file that is displayed in a simple web view on the iPhone app display. This HTML page (known as the Project Web App) may be used to provide documentation to the user, read and write various shared data files, and other purposes.

When you create a new project (by tapping the "+" button when viewing the list of projects), WatchBench will automatically populate the project folder with minimal template versions of these files to get you started.

All of the files, and the APIs they support, are documented in the Help files accessible by tapping the Help button at the bottom of the iPhone app screen.
Top of Page
Lifecycle of a WatchBench Project When Running
This is what happens when the Apple Watch user launches the WatchBench app from the Home screen of their watch.

The WatchBench WatchKit extension creates, activates, deactivates, and terminates the pages of the app when needed. The JavaScript context in which your statements are executed is also created and reset as appropriate.

The first page shown is the Root Page. That page and the objects on it are created. The page is then made "active" and displayed on the watch screen. When the screen shuts off (such as when the watch-wearer's arm is moved down or enough time has passed) the page is "deactivated". The page may or may not be removed completely. There may be any number of activate/deactivate sequences before a page's data is removed and it will need to be reinitialized.

The root page may "push" to another page. In that case, the new page will be created and activated, and the root page deactivated. When the new page "pops" back to the root page, the root page is reactivated, and the new page is deactivated and usually removed.

The Glance Page is shown when the user views the Glance for WatchBench. It is created and activated just like the Root Page, but is completely separate, with separate configuration and JS files. Glance pages do not have buttons or other enabled controls. When you tap on a glance page, the root page is launched as if it was launched from the home page.

The JavaScript context is created anew when the root page is initialized (by the watch through WatchKit) or reset (by responding to the tapping of the Reset Watch button in the iPhone app). All pages pushed to starting with the root page share that same JavaScript context along with its variable values, function definitions, etc. There is a separate context for the Glance page.

When created, the contents of the initialWatchJS.txt or initialGlanceJS.txt file, as appropriate, are evaluated in the fresh context. Top-level statements, such as var and assignment statements, are executed. The config for the page will be loaded as part of initialization, so all of the visible objects may be accessed.

WatchBench notifies the JS code of the changes of state (such as init, activate, deactivate) by calling certain functions in the JS code. You need to create these functions if you want your code to respond to those calls. They are defined in the Watch API Reference help file in the AWB Object section.

Note that the JavaScript context used by the extension does not run in a web view with the DOM. That is, it does not have the "window" or "document" objects. It just runs Core JavaScript. For example, it does not have canvas HTML elements or timers, but it does have Date, String, and Array objects, as well as the JSON parse and stringify global functions. (The Project Web App, though, does run in a full web view environment.)

A description of the contents of the config files and the JS files is provided in the Files in a Project help file. Understanding the role of each of the different files, and their formats, is crucial to understanding how to create projects in WatchBench so please read that help file.
Top of Page