Protocol

CLKComplicationDataSource

A protocol that communicates with ClockKit, providing information about your complication.

Declaration

protocol CLKComplicationDataSource

Overview

Apps that support a complication must define a class that supports the CLKComplicationDataSource protocol and register it with the system. Your data source is responsible for providing timeline entries and data for all of the complication families that you support. You do this by implementing the protocol methods, returning the timeline entries displayed by your complication and information about the features that your complication supports.

You do not instantiate your data source class explicitly. After defining your class, specify the class name in the General tab of the project settings for your WatchKit extension. When the system needs data, ClockKit instantiates your data source and initializes it by calling its init method. Once initialized, ClockKit calls the corresponding protocol methods to gather any needed data. (You can also specify your class name in your app’s Info.plist file using the CLKComplicationsPrincipalClass key.)

When the user installs your complication on the clock face, ClockKit creates an appropriate CLKComplication object for the selected complication family. That complication object is passed to your data source so that you know how to format your timeline entries. Use the General tab of your WatchKit extension’s project settings to specify the families you support.

Your complication data source class must implement the following CLKComplicationDataSource methods:

You may implement other methods as needed to support the data in your complication. ClockKit calls the methods of your data source on your watchOS app’s main thread.

For more information, see Designing Complications.

Topics

Getting the Timeline Information

func getSupportedTimeTravelDirections(for: CLKComplication, withHandler: (CLKComplicationTimeTravelDirections) -> Void)

Determines whether your complication can provide timeline entries for the future or the past.

Required.

func getTimelineStartDate(for: CLKComplication, withHandler: (Date?) -> Void)

Retrieves the earliest date for which your complication is prepared to supply data.

func getTimelineEndDate(for: CLKComplication, withHandler: (Date?) -> Void)

Retrieves the latest date for which your complication is prepared to supply data.

Providing Templates

func getPlaceholderTemplate(for: CLKComplication, withHandler: (CLKComplicationTemplate?) -> Void)

Gets a static template to display in the selection screen for your complication.

Deprecated
func getLocalizableSampleTemplate(for: CLKComplication, withHandler: (CLKComplicationTemplate?) -> Void)

Gets a localizable template that shows sample data for the specified complication.

Determining the Privacy Behavior

Launch Options

let CLKLaunchedTimelineEntryDateKey: String

A key indicating the date with which the complication was launched.

Information Property Keys

property list key CLKComplicationPrincipalClass

The name of the class that implements the complication data source protocol.

Name: ClockKit Complication - Principal Class

Deprecated Methods

func getNextRequestedUpdateDate(handler: (Date?) -> Void)

Gets the next time at which to update your complication.

Deprecated
func requestedUpdateDidBegin()

Indicates that a requested update has begun so that you have an opportunity to extend or reload your timeline.

Deprecated
func requestedUpdateBudgetExhausted()

Indicates that your complication’s time budget is exhausted.

Deprecated

Relationships

Inherits From

See Also

Essentials

Adding a Complication to Your watchOS App

Build a better watchOS experience using complications.