Resource qualifiers on Surface Duo

Article
04/06/2022

On dual-screen devices, app layouts should not hide content under the hinge. If your app loads layouts and other resources using qualified folder names, you can accomplish this by creating special configurations for Surface Duo devices. Android provides qualifiers to handle multiple configurations, so whether your app is running on a device with a small screen, a tablet with 10” screen, or a Surface Duo, you can use qualifier values to help optimize your app for different devices.

Resource qualifiers will match any device with the given characteristics, so although the values shown below will match Surface Duo and Surface Duo 2, it's possible that now (or in the future) they may also match other devices. Try to test on as many real devices as possible, especially those with similar screen sizes and aspect ratios, to verify the resources load as you expect.

Load device-specific resources

Because Surface Duo and Surface Duo 2 have different screen dimensions it's possible to use resource qualifiers to load different resources for each model:

Device	Device-specific resource qualifier
Surface Duo	`sw696dp-2784×1740`
Surface Duo 2	`sw732dp-2754×1832`

These qualifiers are matched exactly to the dimensions of each device, to avoid matching with other hardware as much as possible. If no specific resources are available, Surface Duo will apply the existing qualifiers in order of precedence.

Common resource directory names for each device are shown below:

Surface Duo

drawable-sw696dp-2784×1740 - for images
layout-sw696dp-2784×1740 - for layout XML files
values-sw696dp-2784×1740 - for resource values, like strings.xml files

Surface Duo 2

drawable-sw732dp-2754×1832 - for images
layout-sw732dp-2754×1832 - for layout XML files
values-sw732dp-2754×1832 - for resource values, like strings.xml files

You can avoid duplication by using alias resources to reference items for both devices.

Use a single resource qualifier

You can also use a single resource qualifier - sw696dp-2754×1740 - to match both devices. This value combines the maximum common values from the two devices. You should test that it resolves correctly on all your target devices.

Warning

Many apps use sw720dp or sw732dp to provide tablet resources separate from their phone layouts. If your app uses a matching smallest width directory for some resources, this will be resolved before sw696dp-2754×1740 and any Surface Duo-specific resources will not be loaded.

Except for very simple combinations of resource qualifiers, it will be more reliable to use the separate resource qualifiers for each Surface Duo device, as shown at the start of this page.

How the qualifiers are constructed

Resource qualifiers are created by appending configurations to the name of a resource folder. As long as they follow the proper naming conventions, multiple qualifiers can be added to the same folder by using dashes.

The Surface Duo dimensions indicates the device in dual-landscape mode has a smallest width of 720dp for Surface Duo and 756dp for Surface Duo 2. This value doesn’t change when the screen orientation changes, so this value remains constant whether we are in dual-portrait or dual-landscape mode. Because the status bar reduces the screen area available for apps, subtract 24dp to get the correct smallest width value: sw696dp for Surface Duo and sw732dp for Surface Duo 2.

Specifying smallest width will limit the number of devices that will load these resources, but many tablets will be included. The resources can be further restricted by specifying screen dimensions. By adding 2784x1740 for Surface Duo or 2754×1832 for Surface Duo 2 to the resource qualifier, the resources will only be loaded when both the smallest width matches and the screen dimensions are at least as big as the pixel size specified.

Note

Hardcoding resources to specific values can have unintended consequences, if a new device appears with the same screen size then it would also match the qualifier. Plan your resources accordingly.

Smallest screen width in code

The smallest screen width value can also be checked in code, using the resources.configuration.smallestScreenWidthDp which is available on a UI context such as an activity class. Avoid using the value from a non-UI (ie. application) context, and avoid caching the value as it may change on a dual-screen device or other situation where multi-windowing is enabled and the application is started or moved to a portion of the screen rather than the entire screen.

Changes from Android 10

In Android 11 the way that Surface Duo matches the resource qualifier has changed. Previously the entire screen dimension was used to calculate the sizes for resource qualifier matching, but from Android 11 onwards the 60 pixel navigation bar is subtracted before matching.

The following values were previously supported on Surface Duo running Android 10:

values-sw720dp-2754×1800 - for resource values
layout-sw720dp-2754×1800 - for layout XML files