One of my favorite parts of ClockKit are the new text providers (CLKTextProvider) that they’ve added to the framework. These text providers help you display text in Apple Watch complications in multiple ways. Depending on the provider, you can use these to smart-truncate text, implement a countdown and much more. I wish that these were available in iOS also – it would make handling dates and times much simpler. While we wait, you can always check out awesome resources such as NSDateFormatter.com to get you by for now.

Here’re all of the different text providers and how to use them:

CLKSimpleTextProvider

This is your basic wrapper around a regular string. In the best case, this will allow you to smart-truncate your text if you know how you want to abbreviate it. However, even if you don’t have anything to smart truncate, you’ll still have to use this provider to display text in your complication.

//Swift
let textProvider = CLKSimpleTextProvider(text: "your string here", shortText: "string")

//Objective-C
CLKSimpleTextProvider *textProvider = [CLKSimpleTextProvider textProviderWithText:@"your string here" shortText:@"string";

CLKTimeTextProvider

This provides smart truncation for any time-related text. Note that this doesn’t deal with dates, just the time of day, e.g. 11:15 AM. A good example of this would be dropping the AM or PM from your time if there isn’t enough space. You can also pass in a specific time zone if needed.

//Swift
let textProvider = CLKTimeTextProvider(date: NSDate())
let textProvider = CLKTimeTextProvider(date: NSDate(), timeZone: NSTimeZone.systemTimeZone())

//Objective-C
CLKTimeTextProvider *textProvider = [CLKTimeTextProvider textProviderWithDate:[NSDate date]];
CLKTimeTextProvider *textProvider = [CLKTimeTextProvider textProviderWithDate:[NSDate date] timeZone:NSTimeZone.systemTimeZone];

CLKDateTextProvider

Probably one of the more useful text providers, CLKDateTextProvider introduces the ability to shorten dates. This is particularly useful when you’re building for multiple complication templates (here’s an awesome cheat sheet). Here’s what the truncation breakdown looks like:

Thursday, January 14, 2016
Thursday, January 14
Thursday, Jan 14
Thurs, Jan 14
Jan 14
14

Not all calendar units of time are supported though so make sure the one you’d like to use is one of the ones below:

• NSCalendarUnitYear
• NSCalendarUnitMonth
• NSCalendarUnitDay
• NSCalendarUnitWeekday

//Swift
let textProvider = CLKDateTextProvider(date: NSDate(), units: .Day)

//Objective-C
CLKDateTextProvider *textProvider = [CLKDateTextProvider textProviderWithDate:[NSDate date] units:NSCalendarUnitDay];

CLKRelativeDateTextProvider

This one provides a way to display the difference in time between the current date and a date that you specify. Think of it as a way to display a timer without having to do the calculations yourself. The only thing you’ll need to provide is the date that you want to count to and the formatting style.

There are 3 different formatting styles – Natural, Offset and Timer. Here’re a few examples of what those look like according to Apple’s CLKRelativeDateTextProvider class documentation:

Natural:

• Now
• 2hrs 7mins
• 13mins 5secs
• 3wks 4days
• 2yrs 3mos

Offset:

• Now
• +14 seconds
• -59 minutes
• +2 hours
• -6 days
• +12 weeks

Timer (only supports hours, minutes, seconds):

• 0:14
• 2:32
• 21:15:59

The number of calendar units supported here is a bit more than the CLKDateTextProvider:

• NSCalendarUnitYear
• NSCalendarUnitMonth
• NSCalendarUnitWeekOfMonth
• NSCalendarUnitDay
• NSCalendarUnitHour
• NSCalendarUnitMinute
• NSCalendarUnitSecond

//Swift
let textProvider = CLKRelativeDateTextProvider(date: NSDate(), style: .Timer, units: .Hour)

//Objective-C
CLKRelativeDateTextProvider *textProvider = [CLKRelativeDateTextProvider textProviderWithDate:[NSDate date] style:CLKRelativeDateStyleTimer units:NSCalendarUnitHour];

CLKTimeIntervalProvider

Another time-related text provider, this looks at properly displaying intervals of time, e.g. 8:00 – 10:30 AM or May 5 – May 7.

//Swift
let textProvider = CLKTimeIntervalTextProvider(startDate: NSDate(), endDate: .distantFuture())

//Objective-C
CLKTimeIntervalTextProvider *textProvider = [CLKTimeIntervalTextProvider textProviderWithStartDate:[NSDate date] endDate:[NSDate distantFuture]];

CLKTextProvider

You can create your own custom text provider using the base CLKTextProvider class. Additionally, you can pass in other text providers to the format substitutions and add text around multiple text providers. This is super powerful, although you have to make sure the text you want to display will fit in the complication you want to display it in.

For some reason, the Swift version of the libraries doesn’t have the equivalent of the textProviderWithFormat function so you’re a bit out of luck if you want to use it. I’m assuming this is a bug. The comment explaining how to use the base class is in the CLKTextProvider file, but not the public function declaration. Super strange.

//Swift
???????

//Objective-C
CLKTextProvider *textProvider = [CLKTextProvider textProviderWithFormat:@"your chosen format"];

CLKSimpleTextProvider *textProvider1 = [CLKSimpleTextProvider textProviderWithText:@"your string here" shortText:@"string"];
CLKSimpleTextProvider *textProvider2 = [CLKSimpleTextProvider textProviderWithText:@"your string here" shortText:@"string"];
CLKTextProvider *textProvider = [CLKTextProvider textProviderWithFormat:@"%@ + %@", textProvider1, textProvider2];

Check out the Apple documentation for CLKTextProviders for more information.

---

Have any cool use cases for text providers? I’d love to hear about them. Comment below if you have any issues.