Version: 1.0.0
Files in an
Alpha WatchBenchTM
Project


Config Files
|
JS Files
|
Log Files
|
State Files
|
Web App Files
The Files

A WatchBench project consists of a folder containing at least some of a set of specially named files. Most of these files are in text format, though they can be augmented with image files and other files that are used by the project.

Understanding the role of each of the different types of files, and their formats, is crucial to understanding how to create projects in WatchBench.

There are four main sets of files:

The initial value files are: The current value files are one or more of the following: The Web App files are one or more of the following: Data files have names given by the project developer. Ones that were modified by the AWBlib.getURL function may have the following additional extensions: See the detailed documentation about each file format below.

Each project has its own versions of these files. When you duplicate a project, all of the files are copied. A "new" project has default content for some of the files, while others are created as needed as the project runs or when the developer adds them explicitly.

New files may be created using the "+" button when viewing the list of files for a project. An image may also be imported from Photos using the Share "New File From Photos" command.

Project files may be sent by email using the Share button in the bottom right of the WatchBench app screen. They may be sent individually as attachments, as multiple attachments to a single email, or combined into a single ".awbs" save file that may be tapped on in mail to load it into WatchBench as a new project.

Top of Page
Initial Config Files
Overview
When the root page of a project is initialized by the system, a config data structure with information about all the potentially visible interface objects for all pages is created internally by WatchBench. The initialWatchConfig.txt file is then read and used to update that config data structure.

When each page is created by the system, and the actual interface objects managed by the iOS WatchKit framework are instantiated, WatchBench uses the config information to set attributes of those objects.

As the app continues, AWBlib functions may be used to change the current attributes, for example to update a button name from "Set" to "Reset" when tapped.

In the config file, all of the potentially visible objects on a page have long names as specified in the Page Layouts help file. To aid in programming, and to make it easier to change which objects you are using, each object you want to refer to in AWBlib commands is given a "shortname" in the config file.

By default, all objects are hidden. If an object is defined in the config file, then by default its hidden value is set NO (0), meaning that it will be displayed. Other object attributes also have defaults that may be overridden by the config file.

Objects that you are not using for a project may be left undefined in the config file. They will be left hidden on their respective pages and will take up no space on the screen when the page is displayed.

In addition to the initialWatchConfig.txt file, there is an initialGlanceConfig.txt file that is used to initialize a separate config data structure used by the Glance page.

The initial config data is also used when the watch is "reset" by the user tapping the Reset Watch button in the iPhone app. The next time a page is activated on the watch, WatchBench will pop all pages back to the main root or glance page, and then reuse the (perhaps updated) contents of the config file to reset all of the objects.

The config file is JSON data in a text file, not JavaScript. That is, attribute names must be quoted, and expressions and comments are not allowed. The one exception is that for config files WatchBench ignores lines that start with the "#" character, so that they may be used for comments.

If the first line of a file being displayed in Window 1 of the iPhone app is "{" or "[", then WatchBench assumes that it should be in JSON format. When you save any changes, WatchBench attempts to parse the JSON. If there is an error, then an indication is shown next to the filename in the window header. For this reason, it is best to not use a comment (line starting with "#") as the first line of a config file so that you will get this checking. Config file typos are a common source of error when editing a WatchBench project.
Specifics
The format of a config file is as follows:
{
"longObjectName": {
"name":"shortname",
"attrib1":"value",
...
},
"nextObject": {
"name":"shortname",
"attrib1":"value",
...
},
...
}
The name and attribs are optional. If missing, then the object will be made visible but will only have the default values for text, color, etc. For some objects, such as groups, this may be all that is needed.

Here is an example of a simple config file:
{
"label1root": {
"name":"label1",
"text":"My Stats",
"color":"0F0"
},
"button1root": {
"name":"button1",
"text":"Get Stats"
},
"label4root": {
"name":"label2",
"text":"Awaiting stats..."
}
}
You can find definitions for all of the potential objects in the Page Layouts help file. If you are editing a config file in Window 1, when you tap on the name of an object in the Help (e.g., label1root), a prototype will be inserted at the insertion point in Window 1. Don't forget that these are just items in an object -- you still need the surrounding "{" and "}".

What follows are the attributes you can set in the config.
name
Short name
"name":"shortname"
This is the name that is used in AWBlib and AWB functions. The full name (e.g., label1root1) is not used unless you assign it as a shortname.

There is no default.
hidden
Visibility
"hidden":0-or-1
If this is the number zero (not a string), the object will not be hidden. If it is the number 1, the object will be hidden and the space it takes up will be collapsed.

The default, if missing, is 0 if there is a config entry, 1 otherwise.
alpha
Opacity
"alpha":floating-point-value
This is a number from 0.0 to 1.0. If it is 0.0, the object will be hidden, but the space it takes up will not be collapsed.

The default, if missing, is 1.0.
width
Width of object
"width":number
If this is the number zero (not a string), the default will be used. Otherwise, it will be the size, if applicable to the object.

The default, if missing, is 0.
height
Height of object
"height":number
If this is the number zero (not a string), the default will be used. Otherwise, it will be the size, if applicable to the object.

The default, if missing, is 0.
text
Text to display
"text":"string"
The text for labels, buttons, and switches.

The default, if missing, varies by the type of object.
color
Color of object
"color":"color value"
This is the text color for labels. It is the background color for buttons, groups, and separators. It is switch ON color for switches, and the slider line color for sliders.

The default, if missing, varies by type of object.

Color values are strings in forms similar to the RGB values that are used in CSS. Here are examples of the forms accepted:
66F (equivalent to #6666FF in CSS)
3345F8 (RRGGBB)
3345f8ff (includes alpha)
255,0,255 (RGB 0-255 each)
255,0,255,255 (with alpha)
0%,85%,100%
0%,85%,100%,50%
enabled
Interaction enabled
"enabled":number
If this is the number zero (not a string), the button, slide or switch will be disabled. If 1, then it will be enabled.

The default, if missing, is 1.
cornerRadius
Group corner
"cornerRadius":number
This number (not a string) is the radius for group corners.

The default, if missing, is 6.
numericValue
Value of object
"numericValue":number
For sliders, this is a number (not a string) from 0.0 to 10.0. For switches, it is a number (not a string) that is either 1 (ON) or 0 (OFF).

The default, if missing, is 0.0.
steps
Slider steps
"steps":number
This is the number of steps taken by each tap of the left or right button of the slider. The amount is 10.0 divided by the number of steps.

The default, if missing, is 10.0.
imageData
Filename of image
"imageData":"filespecifier"
This applies to images, groups, and buttons. It specifies an image file (such as a ".png" file) to read from the project folder and use as the background. The filespecifier is either a string with the file name, such as "logo.png" or a string with two filenames separated by the "/" character for 38mm/42mm devices, such as "logo38mm.png/log42mm.png".

The default, if missing, is no image.
Top of Page
Initial JS Files
When the root page or glance page of a project is initialized by the system, a JavaScript context is initialized with the contents of the initialWatchJS.txt or initialGlanceJS.txt file, respectively. This becomes the JavaScript that responds to function calls from the WatchBench system.

There is an object, the AWB object, that must be created at top level in this JavaScript to be used by WatchBench to access function it calls, such as AWB.activate.
var AWB = {};
AWB.activate = function(...
There is also an object, the AWBlib object, that is automatically created by WatchBench after the context is created to provide the AWBlib functions that your JavaScript can call.

See the Watch API Reference help file for more information.

Error detected when executing the JavaScript, and explicit log file entries, are added to the currentWatchLog.txt and currentGlanceLog.txt files as appropriate. You can monitor changes to a log file by displaying it in Window 2 and turning on Auto Refresh.
Top of Page
Log Files
There are separate files used to accumlate logging information from the Watch execution, the Glance execution, and the App execution. These are named currentWatchLog.txt, currentGlanceLog.txt, and currentAppLog.txt, respectively. They are created automatically if not present when an entry is made.

Log entries are time-stamped automatically.

You can monitor changes to a log file by displaying it in Window 2 and turning on Auto Refresh. The Auto Refresh capability of the iPhone app checks the displayed file every second, automatically moving to the bottom-most entry. You will probably find that when developing a project in WatchBench, the log files (and Auto Refresh) are your friends and provide much useful information and are vital for tracking down bugs. Remember that there are separate log files for Glance, Watch, and App.

If you turn on Auto Refresh, and the file being monitored is large enough that it refreshing or resizing may be a performance issue on the iPhone, you will be notified and given the option of continuing or first truncating the file.

Here is an example of a log file:
# Log file for Watch Extension (Watch)

2015-05-06 14:47:08: Button bigbutton tapped

2015-05-06 14:47:09: init Page2

2015-05-06 14:47:09: awake Page2

2015-05-06 14:47:09: activate Page2

2015-05-06 14:47:09: deactivate rootPage

2015-05-06 14:47:11: activate rootPage

2015-05-06 14:47:11: deactivate Page2

2015-05-06 14:47:58: Button updatebutton tapped

2015-05-06 14:47:58: sent URL

2015-05-06 14:47:58: nw.txt loaded
Top of Page
State Files
State information about a project's execution is maintained by WatchBench. The information is stored in JSON form in the currentWatchState.txt and currentGlanceState.txt files. It is automatically saved and loaded as necessary. One of the state object's properties is "stateString" whose value may be set and read by your JS. This is a string, so if you may want to use JSON in text form to store any complex data structures.

The structure of the state information (and the way it will appear in the state file) is as follows (not all properties may be present):
{
screenwidth: number,
screenheight: number,
lastsaved: seconds since 1/1/1970,
currentPageName: string,
locationUpdates: number,
stateString: string
}
The screenwidth and screenheight may be used to determine which size Apple Watch is being used. For the 38mm Apple Watch, it is 136x170, and for the 42mm it is 156x195, as reported by the WatchKit WKInterfaceDevice screenBounds value.

The lastsaved, a floating point number, may be used to see how old the data is. Note that the value is in seconds. JavaScript time, such as returned by Date.now(), is often measured in milliseconds.

The currentPageName is "rootPage", "Page2", etc.

The locationUpdates value is a count of how many times your app has been provided tracking location updates by iOS. In normal, proper use, this should only increment when you are using location tracking, and not more than a few times for each activation. It can be used to track down excessive location tracking, which can be a drain on the iPhone and cause the extension to be active more than it needs to be. It is not reset to zero except when the state file is recreated. A high value is not a problem if it is not incrementing. You can usually ignore this property.

The stateString is updated by your JS using AWBlib.setStateString and normally retrieved with AWBlib.getStateString.

See the Persistent State section of the AWBlib documentation in the Watch API Reference help file.

The state files may be used by the Project Web App to get information from the watch part. There is a ["status","varname"] command that may be used to retrieve it.
Top of Page
Web App Files
The iPhone WatchBench app UI can display HTML5 code running in a web view in place of the normal contents of Window 2. This comes from the index.html file in the project. This may include other files, such as ".css" and image files.

See the Project Web App help file for more information.
Top of Page