The ContentSize API is currently only available in SDK 4.2-BETA.
The ContentSize
API, added in SDK 4.2, allows developers to dynamically
adapt their watchface and watchapp design based upon the system Text Size
preference (Settings > Notifications > Text Size).
While this allows developers to create highly accessible designs, it also serves to provide a mechanism for creating designs which are less focused upon screen size, and more focused upon content size.
The Text Size
setting displays the following options on all platforms:
Whereas, the
ContentSize
API will return different content sizes based on
the Text Size
setting, varying by platform. The list of content sizes is:
An example of the varying content sizes:
Text Size
: small
on Basalt
is ContentSize
: small
Text Size
: small
on Emery
is ContentSize
: medium
The following table describes the relationship between Text Size
, Platform
and ContentSize
:
Platform | Text Size: Small | Text Size: Medium | Text Size: Large |
---|---|---|---|
Aplite, Basalt, Chalk, Diorite | ContentSize: Small | ContentSize: Medium | ContentSize: Large |
Emery | ContentSize: Medium | ContentSize: Large | ContentSize: Extra Large |
At present the Text Size setting only affects notifications and some system UI components, but other system UI components will be updated to support ContentSize in future versions.
We highly recommend that developers begin to build and update their applications with consideration for ContentSize to provide the best experience to users.
In order to detect the current
ContentSize
developers can use the
preferred_content_size()
function.
The ContentSize
will never change during runtime, so it's perfectly
acceptable to check this once during init()
.
static PreferredContentSize s_content_size;
void init() {
s_content_size = preferred_content_size();
// ...
}
There are a number of different approaches to adapting the screen layout based upon content size. You could change font sizes, show or hide design elements, or even present an entirely different UI.
In the following example, we will change font sizes based on the ContentSize
static TextLayer *s_text_layer;
static PreferredContentSize s_content_size;
void init() {
s_content_size = preferred_content_size();
// ...
switch (s_content_size) {
case PreferredContentSizeMedium:
// Use a medium font
text_layer_set_font(s_text_layer, fonts_get_system_font(FONT_KEY_GOTHIC_18_BOLD));
break;
case PreferredContentSizeLarge:
case PreferredContentSizeExtraLarge:
// Use a large font
text_layer_set_font(s_text_layer, fonts_get_system_font(FONT_KEY_GOTHIC_28_BOLD));
break;
default:
// Use a small font
text_layer_set_font(s_text_layer, fonts_get_system_font(FONT_KEY_GOTHIC_14_BOLD));
break;
}
// ...
}
When developing an application which dynamically adjusts based on the
ContentSize
setting, try to avoid using fixed widths and heights. Calculate
coordinates and dimensions based upon the size of the root layer,
UnobstructedArea
and
ContentSize