4.9 KiB
title | description | guide_group | order | related_docs | related_examples | |||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Content Size | Details on how to use the ContentSize API to adapt your watchface layout based on user text size preferences. | user-interfaces | 6 |
|
|
{% alert notice %} The ContentSize API is currently only available in SDK 4.2-BETA. {% endalert %}
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:
- Small
- Medium
- Large
Whereas, the
ContentSize
API will return different content sizes based on
the Text Size
setting, varying by platform. The list of content sizes is:
- Small
- Medium
- Large
- Extra Large
An example of the varying content sizes:
Text Size
:small
onBasalt
isContentSize
:small
Text Size
:small
onEmery
isContentSize
: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.
Detecting ContentSize
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();
// ...
}
Adapting Layouts
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;
}
// ...
}
Additional Considerations
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