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 CLKTextProvider
s 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.
Thanks for copy of documentation)
Nice to see screenshots.
For example I have problem with CLKRelativeDateTextProvider in SmallModular. Apple’s code somehow displays 1hr 23min, and on the next launch can display 2h. Precision is poor.