Creating Complications with ClockKit

In WatchOS2 , third-party apps gain accesss to the components of the watch faces. By designing the timeline carefully, the users of the watch can time travel to see the past events and future events if the information applies.

Getting started

There will be new extension point for watch app in Xcode 7

There are 5 families for the complication

• Modular Small
• Modular Large
• Utilitarian Small
• Utilitarian Large
• Circular Small

for different watch face styles.

The layout of UI is defined. Third-party developers are required to fill the content.

Important Classes

CLKImageProvider //provides images for the complications
CLKTextProvider //provides texts for the complications

CLKImageProvider

• complication only consider the alpha channel of the images

//Initialize imageProvider
let imageProvider = CLKImageProvider(backgroundImage: bgImage,
    backgroundColor: aColor,
    foregroundImage: fgImage,
    foregroundColor: CLKImageProviderForegroundColor.White)

CLKTextProvider

CLKDateTextProvider is a date formatter for complications

//Initialize date formatter with some date units
let sep23: NSDate = ...
let units = [NSCalendarUnit.Weekday,
             NSCalendarUnit.Month,
             NSCalendarUnit.Day]
textProvider = CLKDateTextProvider(sep23, units)

Other provider

• simple text provider
• time text provider for showing time text ( e.g. 2:20pm )
• Time interval text provider ( 11:00 am - 12:30 pm)
• Relative Date Text Provider ( 2HR 56 mins from the event happenes)

let moonset : NSDate = ... // 2:19pm
let units : NSCalendarUnit = [.Hour, .Minute]
let style : CLKRelativeDateStyle = .Natural
let textProvider = CLKRelativeDateTextProvider(date: moonset,
                                               style: style,
                                               units: units)

CKComplicationTemplate

A concrete class for building up the complication contains:

• CLKImageProvider
• CLKTextProvider ( can be multiple as families available)

TimeLine

As suggested before, in WatchOS 2, the users of watch can use "Time Travel" to view the past events like stocks or future events like the calendar events and predicted weather data. There is critical to design a reasonable timeline so that the users would not get confused.

CLKComplicationTimelineEntry

CLKComplicationTimelineEntry contains the timestamp and CKComplicationTemplate for represent a event in a timeline for complication display

CLKComplicationDataSource is required data source for third party developer to implement all required protocol methods.

Documentation for CLKComplicationDataSource

// return allowed direction(s) for time-travel
func getSupportedTimeTravelDirectionsForComplication(_ complication: CLKComplication,
                                         withHandler handler: (CLKComplicationTimeTravelDirections) -> Void)

//Timeline start 
func getTimelineStartDateForComplication(_ complication: CLKComplication,
                             withHandler handler: (NSDate?) -> Void)

//Timeline end
func getTimelineEndDateForComplication(_ complication: CLKComplication,
                           withHandler handler: (NSDate?) -> Void)

//The datetime of waking up and get next log of timeline
func getNextRequestedUpdateDateWithHandler(_ handler: (NSDate?) -> Void)

// timelineEntry for current
func getCurrentTimelineEntryForComplication(_ complication: CLKComplication,
                                withHandler handler: (CLKComplicationTimelineEntry?) -> Void)

// timelineEntries for past date
func getTimelineEntriesForComplication(_ complication: CLKComplication,
                            beforeDate date: NSDate,
                                 limit limit: Int,
                           withHandler handler: ([CLKComplicationTimelineEntry]?) -> Void)

// timelineEntries for future date
func getTimelineEntriesForComplication(_ complication: CLKComplication,
                             afterDate date: NSDate,
                                 limit limit: Int,
                           withHandler handler: ([CLKComplicationTimelineEntry]?) -> Void)

// placeholder for first lanuch the complication
func getPlaceholderTemplateForComplication(_ complication: CLKComplication,
                               withHandler handler: (CLKComplicationTemplate?) -> Void)

// show the information show in lock screen or not
func getPrivacyBehaviorForComplication(_ complication: CLKComplication,
                           withHandler handler: (CLKComplicationPrivacyBehavior) -> Void)