Version: 1.0.0
Watch API Reference for
Alpha WatchBenchTM


AWBlib Functions
|
AWB Object & Callbacks

WatchBench provides a set of API calls that are used by the project JavaScript in the WatchBench WatchKit extension to communicate back and forth with the iOS WatchKit APIs as well as between various parts of the WatchBench environment.

The API calls may be broken down into two major sections: The AWBlib functions, where the project's JavaScript calls the WatchBench watch extension code, and the AWB Object functions and the callbacks, where WatchBench calls the project's JavaScript.

The AWBlib functions are used to set the attributes of various visible interface objects, such as labels and tables. They may also be used to access persistent storage, make HTTP requests to URLs, and more. The AWB Object functions and the callbacks are used to indicate the progress through lifecycle state and for responding to various events, such as the tapping of a button.

There is documentation on the API used by the Project Web App in the Project Web App help file.

AWBlib: Your JavaScript Calls Watch Extension


Logging
|
Persistent State
|
Visible Object Cmds
|
Input
|
Tables
|
Location
|
Switching Pages
|
Local Files
|
URLs and Web App

The JavaScript in a project that interacts with the WatchKit API in the watch extension of WatchBench runs in its own JavaScript context. WatchBench creates a special object in that context that contains functions the project JavaScript can call to use the WatchKit API to communicate with the paired watch, to read and write files, and a variety of other useful functions. That object is the AWBlib object.

An example of an AWBlib function call would be this one to set the text of a label:

AWBlib.objCmd("label1","text","Count: "+n);
There are many AWBlib functions. Each has its own specific arguments. If arguments missing or of wrong type, the call will probably be ignored.

Some of the functions return a value, but many do not.

Top of Page
Logging
There are two log files that are used by WatchBench when running your project in the WatchKit extension to notify you of various events, errors, etc. They are "currentWatchLog.txt" and "currentGlanceLog.txt". They are automatically created if not present when an entry is added. (There is also a "currentAppLog.txt" file used by the iPhone app for indicating errors when running it, as well as for use by your index.html webApp.)

In addition to the messages logged automatically, you can add to, and clear, the log in your JS program using these functions, AWBlib.log and AWBlib.clearLog.

These functions are mainly for debugging and helping you examine the lifecycle of the WatchKit extension.

If your project does not behave as you expect, or if the watch stops being able to invoke WatchBench, make sure to check the log files. There are many errors in JSON format, JavaScript syntax, function argument values, etc., that can affect WatchBench. Most are, hopefully, caught by WatchBench which then adds information to one of the log files. 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. Remember that there are separate log files for Glance, Watch, and App.
log
Add text to currentWatchLog.txt
AWBlib.log(msg)
Use this function to add text to the current log. The msg argment is a string. A timestamp is included with each log entry.
For example:
AWB.activate = function(pg) {
AWBlib.log("Activated "+pg);
}
might result in the following entry in currentWatchLog.txt:
2015-05-07 10:09:40: Activated rootPage
clearLog
Erase log entries
AWBlib.clearLog()
This function clears the current log, starting it afresh. Having a log file grow continually can end up slowing down display of the log, among other effects. When you enable Auto Refresh, a warning is displayed if the file is greater than a certain size and you will be given an opportunity to clear it.
Top of Page
Persistent State
Your watch extension creates, activates, deactivates, and terminates your pages when needed. The JavaScript context in which your statements are executed is also created and reset as appropriate. You must take care to save and load data that is needed between the states.

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. This is where the AWB object and your associated functions may be created. The config for the page will be loaded before initialization, so all of the visible objects may be accessed.

Because your root page may be terminated without warning when not activated, erasing all data resident in the JavaScript context, you need to save any data that you cannot recreate easily each time the context is reset. There are a variety of ways to save and restore such data.

One way is to save the data to a local file using the various read/write API methods provided. Another way is to retrieve current information from the iPhone app (if running) using AWBlib.appCmd or a remote server using AWBlib.getURL. Finally, there is state information that is maintained by WatchBench that you can write as well as read.

This section is about the state information 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.

Note: To transfer data from the glance page to the root page, you can use the AWBlib.updateUserActivity function. To access data in the glance from the root and other pages, you can either read the currentWatchState.txt file and parse it with JSON.parse(), or save and load data in a local file specific to your project.
getStateObject
Get currentWatchState as object
AWBlib.getStateObject()
This function returns the entire state information as an object. It is a copy of the state object, so you should not make changes to it. You may only change the stateString, and that is done with the AWBlib.saveStateString function.

The structure of the state information 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.
getStateString
Get persistent string
AWBlib.getStateString()
Retrieves the current value of the state object's stateString property.
For example:
var sstr = AWBlib.getStateString();
var myData = JSON.parse(sstr);
if (myData.needsRefesh) {
...
}
setStateString
Set persistent string
AWBlib.setStateString(statestring)
This function sets the project state's stateString property value. You can use JSON.stringify(object) to help store more complex values.
saveStateNow
Instead of on deactivate
AWBlib.saveStateNow()
The project state files are usually written to the iPhone's file system when a page is deactivated. You can use this function to force a write at other times to make sure that the file is up to date.

One reason to write it out is that when you push from one page to another (e.g., rootPage to Page2, or glancePage to rootPage) the new page may receive an activate before the old page gets a deactivate.
Top of Page
Visible Objects: AWBlib.objCmd
WatchBench gives you access to most of the visual interface objects provided by WatchKit. These include labels, buttons, images, groups, tables, sliders, switches, and separators. The AWBlib.objCmd function lets you set some of the values for which WatchKit provides an API.

The format of a call to AWBlib.objCmd is:
AWBlib.objCmd(itemname, command, value)
The itemname is a string identifying the visible object for which you wish to set a value. It is also known as the "short name" in WatchBench.

The command is a string identifying the particular command. Some commands are available to all objects, while some may only be applied to a subset of objects. This is dictated by the type of object and the WatchKit API.

The value is a string, interpreted as described for each command.

Boolean, true/false values are either the string "", "NO" or "FALSE" for false (ignoring case), or any other value for true ("YES" or "true" is preferred).

Numeric values are just the string representation, e.g., "15".

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%
Callback functions are provided as a string with the name of the function. For example:
function done(txt) {input=txt; ...}
AWBlib.textInput(["First","Second","Third"],"done");
Base64-encoded values are text string representations of binary data in Base64 notation. Base64 is a common method for representing binary data using normal ASCII characters. It is used in WatchBench to make it easier to handle raw image data as character strings. Base64-encoded values may be used in HTML5 for representing images in data URIs and may be created, for example, from an HTML canvas element with the toDataURL() method. Note that the Web App in the iPhone app has access to HTML canvas elements. The JavaScript context in the extension does not.
objCmd text
Change text of object
AWBlib.objCmd(item,"text",value)
This command sets the text of a label, button, or switch. For example:
AWBlib.objCmd("mainlabel","text","Count "+n);
objCmd color
Change color of aspect of object
AWBlib.objCmd(item,"color",value)
This command sets the text color of labels, the background color of buttons and groups, and the color of sliders, switches, and separators. For example:
AWBlib.objCmd("statuslabel","color",OK?"0F0":"F00");
objCmd image
Change image in object
AWBlib.objCmd(item,"image",value64)
The command takes a Base64 value and sets the image of an image object, or the background image of a button or group. For example:
var img = AWBlib.readFileBase64("icon.png");
AWBlib.objCmd("img1","image",img);
See also: AWBlib.readImage() and AWBlib.imageFromFile.
objCmd hidden
Hide or show object
AWBlib.objCmd(item,"hidden",value)
This command sets the hidden property of any interface object. When hidden, an object's space is collapsed. A value of "YES" will hide the object, a value of "NO" will display the object.
objCmd alpha
Change opacity of object
AWBlib.objCmd(item,"alpha",value)
This command sets the alpha (opacity) property of any interface object. The value is a number (represented as a string) from "0.0" to "1.0". A value of "0.0" will hide the object without collapsing its space.
objCmd height
Change object height
AWBlib.objCmd(item,"height",value)
This command sets the height property of any interface object except tables and separators. The value is a number (represented as a string). A value of "0.0" will use the default for that object, which is often "sized to fit content". If you set an explicit size for an image it will change the scaling to fill the area.
objCmd width
Change object width
AWBlib.objCmd(item,"width",value)
This command sets the width property of any interface object except tables and separators. The value is a number (represented as a string). A value of "0.0" will use the default for that object, which is often "sized to fit content". If you set an explicit size for an image it will change the scaling to fill the area.
objCmd value
Change object value
AWBlib.objCmd(item,"value",value)
This command sets the value property of a switch or slider object. The value is a number (represented as a string). The value for a switch should be either "0" or "1" (non-zero), not "YES" or "NO". The value for a slider should be "0.0" to "10.0".
objCmd steps
Change steps in slider
AWBlib.objCmd(item,"steps",value)
This command sets the number of steps property of a slider object. The value is a number (represented as a string). Each tap on a slider adds or subtracts 10.0 divided by the number of steps. The minimum value of the slider is 0.0 and the maximum is 10.0 when adding or subtracting.
objCmd enabled
Change whether object enabled
AWBlib.objCmd(item,"enabled",value)
This command sets the enabled property of button, slider, and switch objects. When disabled the object will not be affected by taps. A value of "YES" will enable the object, while "NO" will disable the object.
objCmd radius
Change object corner radius
AWBlib.objCmd(item,"radius",value)
This command sets the cornerRadius property of a group object. The value is a number (represented as a string) in points. The default value is "6". A value of "0" will make the corner a sharp angle rather than a curve.
Top of Page
Input: Menus, Text, Switches, and Sliders
WatchBench gives you access to many of the input methods provided by WatchKit. If you are familiar with the Apple Watch you probably have encountered all of them.

When a page is active, you may set up to four menu items that are available when the user does a Force Touch on the screen.

You may request text input from the user, giving optional fixed phrases in addition to using voice recognition.

There are also switch and slider interface objects.
menuClear
Removes menus for page
AWBlib.menuClear()
Removes any added menu items.
menuAdd
Adds menu item for page
AWBlib.menuAdd(text,icon,donefunction)
Adds a menu item to the page. Up to four menu items may be active at once. Any more will be ignored.

The text will appear under the icon. The icon is a text name corresponding to one of the standard icons provided by WatchKit. You may not set your own image.

The donefunction is the name of a menuTapped JavaScript function to invoke when the user completes the input.

The icon names are:
accept, add, block, decline, info, maybe, more, mute, pause, play, repeat, resume, share, shuffle, speaker, trash
For example:
AWBlib.menuClear();
AWBlib.menuAdd("OK","accept","menu");
AWBlib.menuAdd("Cancel","decline","menu");
function menu(num,pg) {
if (num==1) dodone();
if (num==2) docancel();
}
textInput
Prompts for text
AWBlib.textInput(phrasesarry,donefunction)
This function requests text input from the user. The phrasearray is an array of strings that are presented to the user. If the array has contents, those phrases are presented to the user as choices, along with a button to do dictation. If the array has no items, text dictation will be requested. When the user finishes the function specified by the donefunction string will be executed as a textInput completion function. The page will be deactivated and activated while this all occurs after this function returns.

Here is an example:
function done(txt) {input=txt; ...}
AWBlib.textInput(["First","Second","Third"],"done");
Top of Page
Tables
WatchBench gives you access to much of the functionality of WatchKit's table interface objects. A table allows you to display one or more rows, each with its own group of other interface objects, such as labels and images.

Tables start out empty. You add rows with the populateTable function. This function takes an array of arrays. Each of the sub-arrays has the values used to define a row.

WatchBench defines five types of rows, named RowType1 through RowType5. The first element in each sub-array is a string that specifies the row type for that row (all rows need not have the same type). Each row type has a different predefined arrangement of visual interface objects. For each row type, the subsequent elements in the array set values for those objects. If the sub-array is shorter than the total number of elements needed, default values are assigned to the trailing missing elements.

The documentation for the different row types is in the Table Row Types help file.

If the user taps on a row, there is a table selection callback function.
populateTable
Creates rows for table
AWBlib.populateTable(table,itemsarrays,selectfunction)
This function takes an array of arrays to fill the specified table on the current page. The table argument is the name of the table, the itemsarrays is the array of arrays, and the selection function is the string name of the function to call with the 0-origin row number that was tapped.

Here is an example:
function selected(n,pg) {
AWBlib.log("Row "+n+" was tapped");
}
var items = [
["RowType1","First"],
["RowType1","Second","F66"],
["RowType3","Third"]
];
AWBlib.populateTable("t1",items,"selected");
updateTableRow
Updates contents of existing row
AWBlib.updateTableRow(table,index,valuearray)
This function lets you change the values for a particular row already present in a table. The arguments are the table name, the 0-origin index of the row to change (as a number, not a string), and an array with just the values -- that is, without the row type as the first element.

For example:
var items = ["Second","000","FDD"];
AWBlib.updateTableRow("t1",1,items);
scrollToTableRow
Ensures row visible
AWBlib.scrollToTableRow(table,index)
This function causes the table to scroll on the screen if necessary so that the specified numeric row number (0-origin) is visible.
Top of Page
Location Tracking
WatchBench has functions that may be used to determine the location of the iPhone. This is done using the normal iOS location tracking mechanisms. The user must give WatchBench permission and have tracking enabled.

Tracking is preformed asynchronously as the iPhone moves and various radio signals are received. Your project needs to turn on the tracking, and then it can read the most recent information from the system. Continual updates to tracking involve extra burden on the iPhone, so it is often desirable to just get a single reading and then stop tracking. This might be, for example, when you just need to save the location where a button was tapped, rather than continually updating the screen.

In WatchBench, you use the AWBlib.useLocationTracking function to make sure that the app is authorized by the iPhone user for tracking, including requesting authorization if needed. The AWBlib.startLocationTracking function starts the background capture of location information. The AWBlib.currentLocation function returns the most recent information given to the app by iOS. The AWBlib.stopLocationTracking function stops the background data capture. The AWBlib.trackLocationOnce function turns on tracking, but automatically stops it once a reading has been provided by iOS.

To monitor how frequently your project is getting tracking information, and to help avoid doing it too much, you can examine the "locationUpdates" property of the state object. See the description of AWBlib.getStateObject.
useLocationTracking
Authorize GPS tracking
AWBlib.useLocationTracking()
This function checks to see if the iPhone user has indicated whether or not WatchBench may use location tracking. If the authorization status is undetermined, then it will request authorization, which may or may not be granted by the user.

NOTE: You may need to explicitly set the authorization in the iPhone Settings for Privacy. Go to Location Services and set WatchBench to Always.
isLocationTrackingAllowed
Is tracking authorized
AWBlib.isLocationTrackingAllowed()
This function returns a string indicating authorization status. The values are:
Always
WhenInUse
NotDetermined
Denied
isLocationTrackingEnabled
Is device setup to track
AWBlib.isLocationTrackingEnabled()
This function returns the string "YES" if Location Services is currently enabled in the iPhone General Settings so that tracking may be done. Otherwise, it returns "NO".
trackLocationOnce
Get location now only
AWBlib.trackLocationOnce(donefunction)
If location tracking is enabled, this function starts location tracking by WatchBench, then returns. As soon as there is at least one reading, location tracking is halted and the donefunction is called. You can then get the location using the AWBlib.currentLocation function.

For example:
var AWB = {};
var loc = AWBlib.currentLocation();
function tracked() {
loc = AWBlib.currentLocation();
}
AWB.activate = function(pg) {
AWBlib.trackLocationOnce("tracked");
}
AWB.deactivate = function(pg) {
AWBlib.stopLocationTracking();
}
AWB.buttonAction = function(btn) {
var loc = AWBlib.currentLocation();
info = {
time:Date.now(),
lat:loc.latitude,
lon:loc.longitude
};
AWBlib.log(JSON.stringify(info));
}
startLocationTracking
Start continual tracking
AWBlib.startLocationTracking()
This function starts the updating of location information, if location tracking is enabled. It returns immediately. There may be a delay before an up to date location is available using the AWBlib.currentLocation function. WatchBench is set to request best location accuracy.
stopLocationTracking
Stop continual tracking
AWBlib.stopLocationTracking()
This function stops the updating of location information.
currentLocation
Get latest Lat/Log/Alt
AWBlib.currentLocation()
This function returns the most recent updated location information as an object in the following format:
{
latitude: number,
longitude: number,
altitude: number
}
The latitude and longitude values are floating point numbers representing degrees. The altitude is a floating point value in meters.
Top of Page
Switching Pages
WatchBench implements a "hierarchical" navigation style WatchKit app. That means that the user cannont swipe from one screen to another like in a "Page-Based" navigation style, but they can tap a button or select a row in a table and "push" to another page under control of you JavaScript.

WatchBench provides three different pages. The first page is always the root page, and has that layout. If you push to another page, it may be either the one with the Page2 layout or the Page3 layout. See the help file on Page Layouts for more information about which visible interface objects are available on each page layout.
setPageTitle
Sets displayed title of page
AWBlib.setPageTitle(string)
This function lets you set the string that appears in the left side of the status bar at the top of the screen for the current page. On the root page, you may want this to be, for example, related to what your project does. On other pages, tapping on that part of the status bar returns to the previous page (and has a "<" character to indicate that). You may want this to indicate what tapping there symbolizes (such as the contents of the previous page) or what it does (such as "Done").
pushToPage
Change screens
AWBlib.pushToPage(newpagename)
This function switches to the page specified by the string value of newpagename. That new page will be initialized, awoken, and activated as needed. The current page will be deactived at some point after this call. When the pushed-to page executes the AWBlib.popPage function, the pushing page will be reactivated. The JavaScript context is shared among pages, so top-level values set on the root page are availabe on the other pages, and vice versa.

The glance page is not part of this heirarchy and has its own JavaScript context. It also cannot push to others pages under program control. Tapping on it always switches to the root page.

See the Persistent State section of this help file for more information.

For example:
AWBlib.pushToPage("Page2");
popPage
Back one level
AWBlib.popPage()
This function causes the current page to be ended and the page that pushed to it to be restored to the screen. The root page may not pop to the glance page.

Note that if the user taps the left side of the status bar at the top of the screen, or swipes to the right from the far left of the screen, the page will be popped without notice.

After popping the page, the returned-to page will be activated and the popping page will be deactivated.
popToRoot
Back to top level
AWBlib.popToRoot()
This function causes the current page to be ended and returns all the way back to the root page.
updateUserActivity
Set message from Glance
AWBlib.updateUserActivity(contextstring)
This function is a way to send information from the glance page to the root page when the user taps on the screen to switch. It must be executed before that tap. (Your JS is not notified of the tap on the glance page with a callback.)

The information is in the form of a string. It will be made available to the root page by a call to the AWB.userActivity function. This could be used, for example, to have the root page change what is displayed or push to another page.

See the Persistent State section of this help file for more information.
Top of Page
Local Files
Each WatchBench project is contained in its own folder on the iPhone, separate from the other projects. These functions give the JS running in the extension the ability to create, read, write, and delete files in that folder. The folder is only one level -- there are no sub-folders. The files are only accessible to the WatchBench app. They are accessible to the extension as well as the web app running in the iPhone app. They are not directly shareable with other apps on the iPhone.

This functionality can be used to retrieve image data for display, persist data over longer periods of time, share data with the iPhone web app, etc.

Note that the main files that drive a project, like the config and JS files, are accessible with this functionality. Use such access carefully.

Filenames should not include any of the following characters: '/', '\', '?', '<', '>', '"', ':', '+', '[', ']', or '|'.

Some file operations deal with Base64-encoded data. Base64-encoded values are text string representations of binary data in Base64 notation. Base64 is a common method for representing binary data using normal ASCII characters. It uses 64 of the normal, printable ASCII characters to represent successive 6 bits of data. This encoding is a bit larger than the original data, but it is easily handled by systems that are designed for text data rather than binary, such as email. It is used in WatchBench to make it easier to handle raw image data as character strings in simple JavaScript.
readFile
Returns contents of local file
AWBlib.readFile(filename)
This function returns the contents of the file specified by the filename as a string. The data in the file should be encoded in UTF-8 or 7-bit ASCII, the normal forms for text files. The filename should be a string with just the filename with extension, without any path components (such as those separated by "/").

This is good for reading in data saved in JSON form.
readFileBase64
Returns contents of
file as Base64 encoded
AWBlib.readFileBase64(filename)
This function reads the contents of the file specified by the filename as raw data. It then encodes the data (made up of 8-bit bytes) into a text string in Base64 form and returns the encoded data as a string value. That encoded data may be used to set the image data of image objects, or the background of buttons and groups.
readImage
Returns file (38mm or 42mm)
AWBlib.readImage(filename38mm,filename42mm)
This function reads in the contents of an image data file, such as a ".png" or ".jpg" file, and returns a string with that data encoded using Base64. There are two filename arguments. The first will be used if the paired watch has the 38mm size screen and the second will be used if the paired watch has the 42mm size screen.
imageFromFile
Load image from file (38mm or 42mm)
AWBlib.imageFromFile(item,filename38mm,filename42mm)
This function reads in the contents of an image data file, such as a ".png" or ".jpg" file, and uses that data to set the image data of the interface object specified by the string value of item.

There are two filename arguments. The first will be used if the paired watch has the 38mm size screen and the second will be used if the paired watch has the 42mm size screen.
readFromFile
Returns contents of local file
AWBlib.readFromFile(filename,options)
This function returns the contents of the file specified by the filename as a string. If options is "base64", the data will be converted to Base64, otherwise the data in the file will be assumed to text data encoded in UTF-8 or 7-bit ASCII. The filename should be a string with just the filename with extension, without any path components (such as those separated by "/").
writeFile
Writes text to local file
AWBlib.writeFile(filename,string)
This function writes the string argument to the file specified by filename using UTF-8 encoding. This is used for normal text strings, including those created using JSON.stringify.
writeToFile
Writes text to local file
AWBlib.writeToFile(filename,string,options)
This function writes the string argument to the file specified by filename. If options is "base64", the string is assumed to be Base64-encoded data and will first be converted to raw 8-bit data before output. Otherwise, the string is assumed to be normal text and will be written out in UTF-8 encoding.
deleteFile
Deletes local file
AWBlib.deleteFile(filename)
This function deletes the file specified by the filename argument.
Top of Page
URLs and the iPhone Web App
These functions are used to communicate outside of the extension execution environment. They let your JS access remote web servers, and also execute JavaScript within the environment of the project's web app running on the iPhone.

These functions return immediately, but the functionality that it starts usually continues asynchronously. When that functionality completes, a JavaScript function whose name you specify in the donefunction argument is invoked with appropriate arguments.
getURL
HTTP GET request and response
AWBlib.getURL(url,file,donefunction)
This function causes a GET HTTP request to be made to the URL specified by the url argument. When the server responds, the response body is saved to a file with the name specified by the file argument and then the function specified by the donefunction argument is invoked.

The form of the donefunction function should be:
function donefunction(filename,errormsg,statuscode) {
}
For example, if the file argument was "d1.txt" and the donefunction argument was "urldone", the donefunction call for a successful response would be as follows:
urldone("d1.txt", "", "200");
In addition to the file named by the file argument, three other companion files are created. They all start with the same name (and optional extension) as the main file, but the other three have an added extension. The first is "name.request", the second is "name.error", and the third is "name.statuscode". When WatchBench is about to make the HTTP request, it deletes the ".error" and ".statuscode" companion files. It writes out the URL being requested and the time the request started to the ".request" file.

When the response completes (or has an error or times out), the ".request" file is deleted and the status code returned by the server is stored as text in the ".statuscode" companion file. If there is an error, information about the error is written to the ".error" file, otherwise the ".error" file is not recreated. Requests will time out if there is no activity from the server within 15 seconds.

These extra files make it easy for the developer to see what is going on and should help with debugging.
getURLWithTimeout
HTTP GET request and response
AWBlib.getURLWithTimeout(url,file,donefunction,timeout)
This function is almost identical to the AWBlib.getURL function. The only difference is that there is a fourth argument that is a number specifying the timeout setting for the request to the server (in seconds). The default value for AWBlib.getURL is 15 seconds. If that is not appropriate for your situation, you can use this function to use a different value.
appCmd
Request to iPhone Web App
AWBlib.appCmd(operation,donefunction)
This function gives your extension JS code access to the JavaScript environment of the Project Web App web view in the iPhone app. See the help file about the Project Web App for more information.

Here is an example. There is an <input> element in index.html with an id of "input1" and a value set.
function done(msg,err) {
AWBlib.objCmd("label1","text",msg);
AWBlib.log("Got msg: "+msg+", error: "+err);
}
AWB.buttonAction = function(buttonname){
AWBlib.appCmd("document.getElementById('input1').value","done");
}
This will return the current value of the input element when the web app is visible on the iPhone screen.
Top of Page
AWB and Callbacks: Watch Extension Calls Your JavaScript


AWB
|
Callbacks

The WatchBench environment interacts with the JavaScript in a project by calling functions in the JavaScript. Those functions are either properties of a special object (the AWB object) that the developer defines in the JavaScript context, or they are normal functions whose name is provided in a call from the project JavaScript to WatchBench for use in a callback later upon completion of an operation or the signaling of an event.

Top of Page
AWB
WatchBench can communicate with your code by calling predefined functions that you may add to the top-level AWB object. You must create this object in your initialWatchJS.txt and initialGlanceJS.txt files with a top-level var statement. You then define functions as properties of the AWB object.

For example:
var AWB = {};
AWB.activate = function(pagename) {
statements to execute
}
These functions are mainly for allowing your code to participate throughout the lifecycle of the WatchKit extension. Most are triggered by normal iOS WatchKit method calls, which dictate much of how WatchBench operates. You can learn about them by including them in your project's initialJS file and using AWBlib.log calls to log what happens. You then view the log page (currentWatchLog.txt or currentGlanceLog.txt) in the second window of the iPhone app. (Make sure that Auto Refresh is on so that you can follow along in near real-time. When on, a small green rectangle flashes next to the Auto Refresh button. Tap the button to toggle on and off.)

For example, the function definition:
AWB.activate = function(pg) {
AWBlib.log("Activated "+pg);
}
might result in the following entry in currentWatchLog.txt:
2015-05-07 10:09:40: Activated rootPage
If an AWB function is not defined, the call to it is not performed.
activate
Page about to be shown
AWB.activate = function(pagename)
This function is called when pagename is about to be displayed. You use it to do last minute updates of the visible objects. You also use it to set menu items for the page.

Here is an example:
AWB.activate = function(pagename) {
AWBlib.objCmd("lbl2","text",data.status);
}
Pages are activated and deactivated quite frequently - every time the screen goes dark, when you switch pages, etc. You may need to save data between deactive/activate invocations in persistent storage.

For object properties that stay constant, such as text and colors, you may find that setting those properties in the config file is easier. This will also be more efficient, especially for the root page.
awake
Page started by another
AWB.awake = function(pagename)
This function is called when the extension's awakeWithContext method is called. It is called after the AWB.init.
buttonAction
A button was tapped
AWB.buttonAction = function(buttonname)
This function is called when a button on the screen is tapped. The argument, buttonname, is a string that identifies your shortname for the button object on that page.

Here is an example:
AWB.buttonAction = function(buttonname) {
switch (buttonname) {
case "b1":
data.b1 = true;
break;
case "b2":
data.b2 += 1;
break;
}
}
Note that there is only one AWB.buttonAction function that is shared by all buttons in the project. There is not one per page. Glances do not have buttons.
sliderChanged
A slider's value changed
AWB.sliderChanged = function(slidername,newvalue)
This function is called when a slider on the screen has its value changed by the user. The argument slidername is a string that identifies your shortname for the slider object on that page. The numeric argument newvalue has the new value, which should be between 0 and 10.

Here is an example:
AWB.sliderChanged = function(name,value) {
data[name] = value;
}
Note that there is only one AWB.sliderChanged function that is shared by all sliders in the project. There is not one per page. Glances do not have sliders.
switchChanged
A switch was tapped
AWB.switchChanged = function(switchname,newvalue)
This function is called when a switch on the screen is tapped. The argument, switchname, is a string that identifies your shortname for the switch object on that page. The value, newvalue, is numeric and is either 1 or 0.

Here is an example:
AWB.switchChanged = function(name,val) {
switch (name) {
case "switch1":
data.switch1 = val;
updateSettings();
break;
case "switch2":
data.autoUpdate = val;
if (!val) stopRemoteService();
break;
}
}
Note that there is only one AWB.switchChanged function that is shared by all switches in the project. There is not one per page. Glances do not have switches.
deactivate
Page has stopped being shown
AWB.deactivate = function(pagename)
This function is called when the extension's didDeactivate method is called. This is after the page is removed from the screen.

You may want to save state when this occurs, such as using the AWBlib.saveStateString function.
init
Page created
AWB.init = function(pagename)
This is called when the page is first created. There may be multiple activate/deactivate cycles after an init. The root page does not need to be re-inited when it pushes and returns from another page. Pages it pushes to, though, are usually inited each time they are pushed. There is no function that indicates that a page is no longer around and will need to be re-inited before being activated.

When the project in the watch is reset by the user and AWB.reset() is called, the AWB.init() function is not called, since the page is still active. The config for the page is still loaded first, and the initial JS is also reloaded. You can force an init of the root page by starting from a glance and then tapping the screen.
repeatingTimer
Called every second while visible
AWB.repeatingTimer = function()
This function is not part of the normal extension lifecycle. It is provided to let your page keep track of time, do periodic data checks, etc. It only fires while the page is visible and is not guaranteed to be exactly every second.
reset
Restarted by iPhone app
AWB.reset = function()
When the user of WatchBench taps the "Reset Watch" button on the iPhone app, and a page on the watch screen is reinitialized or activated, the configs and JS files are reloaded by the WatchKit extension. Then, this function is called to let your JS code know that it should reset appropriate data values.

When the project in the watch is reset by the user and AWB.reset() is called, the AWB.init() function is not called, since the page is still active. The config for the page is still loaded first, and the initial JS is also reloaded, so that should not be an issue. You can force an init of the root page by starting from a glance and then tapping the screen.
userActivity
Page was started from Glance
AWB.userActivity = function(pagename,contextstring)
When the user taps on the watch screen when viewing the Glance page, this function is invoked after the AWB.activate call is made. The pagename is the name of the page being switched to (usually rootPage) and the context string is a value set by the Glance page's JS using the AWBlib.updateUserActivity function. The default is "Came from Glance".
Top of Page
Callbacks
Many of the AWBlib functions take the name of one of your functions as an argument. When the operation you request completes at a later time, usually after the AWBlib function returns, your function will be invoked with appropriate arguments.

NOTE: The function name you provide is a string with the name of the function, not a function value.
appCmd completion
Result string
name(returnvalue)
This function is called when the AWBlib.appCmd function returns a result from the iPhone app. The returnvalue is an object in the following form:
{error:msg, value:valuestring}
If there are no errors, msg should be an empty string. The valuestring is the value returned by evaluating the operation your specified.
textInput completion
User input
name(resultstring)
This function is called when the input operation started by the AWBlib.textInput function completes. The resultstring will have the text value, or be empty if the user cancels the operation.
getURL completion
Server response
name(filename, errormsg, statuscode)
This function is called when the URL GET operation requested by the AWBlib.getURL function is called. The filename will be the file in which you requested the received data to be stored. You can then read the contents of that file to get the data with the appropriate reading function. (For example, image data may need to be read into Base64 format for use with an image object while JSON data may be read as a UTF-8 encoded string for parsing.)

If there was an error, a text message will be in errormsg, otherwise it will be an empty string. If the errormsg is non-empty, then the value is also in the file with the same name as filename with the added extension of ".error". The statuscode is a numeric value returned by the server, such as 200, 404, etc. The most recent statuscode for filename is stored as a string in the file with the same name as filename with the added extension ".statuscode".
trackLocationOnce done
Location available
name()
This function is called when the system first provides a location update after you invoke the AWBlib.trackLocationOnce function. You can then get the location information using the AWBlib.currentLocation function.
menu tapped
Menu tapped
name(menunumber,pagename)
When you call the AWBlib.menuAdd function you provide a function to call for that menu button. When it is tapped, the function name you provided is invoked. The menunumber indicates which current menu item on the current page was tapped. The pagename indicates the page.
table selection
Table item tapped
name(index,pagename)
When you use the AWBlib.populateTable function to create table rows you provide a selection function name as a string. When a row in the table is tapped, that function is invoked with the index (0-origin) of the row, and the page name.

This could be used, for example, along with the AWBlib.updateTableRow function, to change the contents of the row, or its color, or drill down with addition information on another page.
Top of Page