Creating Apple Watch Applications in Volt MX Iris
With Volt MX Iris, you can create your entire iOS app from end to end. Specifically, you can write an iOS app that runs on a user's iOS device, you can add your Watch app's business logic in the WatchKit Extension, and you can design the entire user interfaces of both the iOS app and the Watch app. The user interfaces for both your iOS app and your Watch app are forms and widgets that you simply drag and drop onto the Iris palette. For information about which user interface objects are supported on the watch, please see Watch Applications, Forms, and Widgets.
Adding a Watch App to your Volt MX Iris Project
In Volt MX Iris, you can add an Apple Watch app to your current project in just the same way that you would add a mobile, desktop, or tablet app to your project. In Iris's Project Explorer pane, you will see that in addition to the Mobile, Tablet, and Desktop channels, there is also a Watch channel displayed, as shown in the following illustration.
As you can see, the watch appears as an additional channel in the Project pane at the left of the illustration.
When you develop a mobile or tablet app, you do so by adding forms, widgets, and so forth to the appropriate channels. Likewise, you can build a watch app by adding forms and user interface objects to the Watch channel. The ability to interactively build both a Watch app and its associated iOS app interactively provides a simple, integrated, and intuitive method of creating an integrated phone and watch application.
In addition, when you build your Watch app project, you also need to select Apple Watch apps in the build settings in Volt MX Iris, as shown below.
Watch Applications, Forms, and Widgets
You create your watch app's user interface with forms and widgets. You can use three types of forms in a watch application: App forms, Notification forms, and Glance forms. All of these are directly available on the Widgets tab of the Volt MX Library pane in Iris.
A watch application cannot dynamically create forms at run time as you can in a mobile or desktop app. You must add all of the forms your watch app needs in Iris at design time. If your app has more than one form, it can dynamically select which form it will display at any given time.
Notification forms can be either static or dynamic. That is, they can contain either static content that does not change, or they can hold dynamic information that changes.
Glance forms follow the Apple layout. Specifically, there are upper and lower areas to the glance form as defined in the Apple programming guidelines. Glance forms only support a few types of widgets. For example, you cannot add a button to a glance form because glances are not actionable.
Iris enables you to use the following widgets in your watch application.
- Button
- Date
- Group: horizontal and vertical
- Image
- Label
- Line
- Map
- Segment
- Slider
- Switch
- Timer
Watch Applications and Templates
To help you build the user interface for your app, Volt MX Wearables for Apple Watch supports templates, but only for SegmentedUI widgets. For example, the sample app shown in the figure below has a SegmentedUI widget on its frmSecond
form. To use a template with the SegmentedUI widget, you first click on the Templates tab, as shown below.
The Templates tab displays a list of all of the SegmentedUI widgets in your Watch app and enables you to add templates for each one. In this example, there is only one segment. It has a single template, and it's called segTemp, as the following figure illustrates.
In your templates, you can add Group widgets, buttons, images, and so forth. These are applied to segments and displayed in the UI when your app displays the segment.
After you have your template looking the way you want it to, you can apply it to a segment by using the following steps.
-
Click on the Project tab and then selecting the segment, as illustrated below.
-
Go to the Properties pane and click the Segment tab, which is displayed in the following figure.
-
Now select the template to apply to the segment from the Row Template list.
Watch Applications, Actions, and Modules
Adding actions enables you to build the business logic directly into your watch application. Watch app actions are typically event handlers that are triggered by user interactions with the UI. They can also be callbacks that are invoked by notifications. These are written in Swift. You add an action to a form or widget with the following steps.
-
Click the Action tab in the Properties pane, as shown below.
-
The Action tab displays the list of actions that the form or widget supports. Click the Edit button. Volt MX Iris displays a list of actions. Currently the only action that is supported is adding a Swift code snippet.
-
Add Swift Snippet and add your code in the editor pane that appears.
If your snippet takes more than a few lines of code, you should consider putting it into a function an a Swift code module. Your app can then call the function from an action's code snippet. As with any other type of project, you can group your watch app's functions into modules and include them in your project. You create a Swift code module by clicking on Modules in the Project tree and then selecting New Swift module from the Watch node, as shown in the illustration below.
Note that you can put any valid code in your custom Swift modules that you need for you app. This includes classes, methods, constants, module global variables, or whatever else you may need to write your app.
Communication Between the iPhone App and the WatchKit Extension
Watch apps are paired with iPhones via Bluetooth. Watch apps send information requests to their respective iOS apps by calling the sendMessage:replyHandler:errorHandler:
method, which is in the WCSession
class in the Apple Watch Connectivity API. In addition to using the sendMessage:replyHandler:errorHandler:
method for information requests, your watch app can invoke it to perform time-consuming tasks such as network calls. In these cases, the watch application relies on the iOS application to execute the business logic. Calling the the sendMessage:replyHandler:errorHandler:
method wakes the parent application up in the background (if it is not already running in the foreground), executes the operation, and returns the data that the Watch application needs. The watch callback method that handles the WatchKit request must return immediately or nearly immediately.
To fetch data from the iOS app, the Watch app calls sendMessage:replyHandler:errorHandler:
in accordance with the Apple guidelines for using the WCSession
class. The following example demonstrates how the Watch app fetchs data from the iOS app.
<Class Start>
import Foundation
import WatchConnectivity
import WatchKit
class PhoneCommunicator : NSObject, WCSessionDelegate {
static var sharedInstance:PhoneCommunicator? = nil;
var session:WCSession? = nil;
override init() {
super.init();
session = WCSession.defaultSession();
if(session!.delegate == nil){
session!.delegate = self;
session!.activateSession();
}
}
class func getSharedInstance() -> (PhoneCommunicator) {
if(sharedInstance == nil){
sharedInstance = PhoneCommunicator();
}
return sharedInstance!;
}
func pingPhone() {
if WCSession.isSupported() {
print("session is supported on watch");
if(session!.reachable){
print("session reachable on phone");
session!.sendMessage(
["requestId": "sayHello"],
replyHandler: {
(response) -> Void in print("in reply handler");
print("\(response["reply"]!)");
},
errorHandler: {
(error) -> Void in print("in error callback");
print("\(error)")
}
)
}
}
}
}
<Class End>
Handling Notifications
Your Apple Watch app responds to both local notifications and remote notifications. They are processed by your iOS app that is paired with your Watch app. iOS itself decides whether to actually send the notifications to the watch.
To process notifications, you must use Volt MX Iris to create the appropriate notification forms in the Watch app.
Creating Notifications on the Watch
To create notifications, use the following steps.
- Go to the Notifications node in the Volt MX Iris Project pane and select it.
- In the menu that appears, click New Notification. By default, this creates a static notification that cannot be interacted with. It can only display information and alerts.
- If you want to change the notification to a dynamic notification, which can have interactive elements such as buttons, select the notification that you created in step 2.
-
Use the down arrow next to the name of the notification to pull down the context menu and click Create Dynamic Notification, as shown in the following illustration.
Volt MX Iris adds a new node for the dynamic notification form to your project, as depicted in the illustration below.
When you create a dynamic notification form, the form can receive events. Therefore, you can add event handlers to the form by clicking the Action tab in the Properties pane, and then choosing the Edit button followed by Add Swift Snippet.
Processing Notifications
Notifications are processed by the iOS app that is paired with your Watch app. Your app processes local notifications using the functions in the voltmx.localnotifications namespace. Your iOS app does not have to register for local notifications.
To process remote notifications, it uses the functions in the voltmx.push namespace. When your iOS app starts, it must register for the remote notifications that it needs to receive by invoking the voltmx.push.register function. It can then get its notifications using the voltmx.push.getMessages and voltmx.push.getMessageCount functions. You can also use the voltmx.push.setCallbacks function to set the notification handlers for the notifications you want to process.
Adding Notification Handlers
You add notification handlers in your Swift code by selecting the Action tab in the Properties pane, and then choosing the Edit button followed by Add Swift Snippet. Your code must handle the notifications in accordance with Apple guidelines. For more information, please see the following Apple documentation.
Many notification event handlers have a parameter named completionHandler, as indicated by the red circle in the figure below.
The completionHandler parameter contains a callback function that your event handler must call upon successful completion in order for the event to be handled properly. This call must be placed at the end of your event handler. Failure to invoke the completionHandler function results in undefined behavior.
How to Create a Sample Watch App on iOS
This walkthrough provides a brief introduction on how to create Watch apps for iOS.
Beginning the Sample Watch App
When you build your own watch app, it must be built in conjunction with an iOS app. So the first step is to create an iOS app in Iris. To do so, you add forms and code to the Mobile or Tablet nodes (or both) in the Volt MX Iris Project tree, as the following illustration shows.
You must ensure that your iOS app has at least one form or your app will not build.
If you need information on creating iOS mobile or tablet apps in Volt MX Iris, please see the VoltMX Widget Programmer's Guide and the VoltMX Iris API Developer's Guide.
In the Volt MX Iris Project tree there is an additional platform (also called a channel) that is specifically for the watch. This channel, named Watch, contains three sub-items; one for forms, one for notifications, and one for glances, as shown below.
Adding Forms to the Sample Watch App
You can design a user interface for your watch app by dragging user interface objects and forms from the Widgets list in the lower left of the Iris screen and dropping them onto the Forms node, as illustrated below.