pebble/devsite/source/_guides/user-interfaces/content-size.md
2025-02-24 18:58:29 -08:00

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
ContentSize
UnobstructedArea
title url
Simple Example https://github.com/pebble-examples/feature-content-size

{% 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.

ContentSize >{pebble-screenshot,pebble-screenshot--time-red}

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 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.

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