Returns a string variation suitable for the specified presentation width.
- iOS 9.0+
- macOS 10.11+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
The desired width of the string variation.
A string variation, or the original string if no variations exist for the specified width.
You can use this method to provide adaptive strings for the user's device—that is, text that avoids truncation and maximizes available space. For example, an app running on an iPad Pro in Landscape orientation might welcome a user with the message “Greetings and Salutations!”, whereas the same app running on an iPhone SE in Portrait orientation might instead show an abbreviated welcome message, like “Hello!”.
Call this method on a string with one or more width variations. You define width variations for a localized string in a Stringsdict file using the
NSString key, and then retrieve a string with variations using
For example, consider the
stringsdict file in the first listing and the corresponding code in the second listing.
Understanding How Width Variants Are Selected
This method selects a variation for a specified width according to the following behavior:
If no variations exist for the string, the original string is returned.
If a variation exists for the specified width, that string is returned.
If no variation is found with a width less than the specified value, the variation with the smallest width is returned.
Otherwise, the variation with the next smallest width value is returned.
Specifying Width Values
Smaller width values correspond to shorter strings, whereas larger values correspond to longer strings. By default, width values do not have an associated unit.
In iOS, width contexts are measured by the number of em units that fit across the app window. This value depends on several factors, including the size and orientation of the device, the user's preferred content size category, whether the Zoom accessibility feature is enabled, and whether the app is displayed in a multitasking context, such as in Split View or Slide Over.