An image that can be displayed in the interface of your watchOS app.
- iOS 8.2+
- watchOS 2.0+
The images you display in your watchOS app can be static or animated. You use
WKInterface objects to specify the image data you want to display and to start and stop animations.
Do not subclass or create instances of this class yourself. Instead, define outlets in your interface controller class and connect them to the corresponding objects in your storyboard file. For example, to refer to an image object in your interface, define a property with the following syntax in your interface controller class:
During the initialization of your interface controller, WatchKit creates any needed image objects and assigns them to their associated outlets. At that point, you can use those objects to make changes to the onscreen images.
The images you use in your interface can be embedded in your Watch app bundle, created dynamically, or downloaded from the Internet. Images in your Watch app bundle represent the images that are part of your app’s user interface. Images that you download or create dynamically exist either in memory or as files in your WatchKit extension’s container directory. The
WKInterface class provides setter methods for getting your images onscreen regardless of their location.
The images you use in your interface can come from many different locations, and you load and manage those images in different ways:
Store images that are part of your standard interface in your Watch app bundle. Use asset catalogs to store your images and to customize those images for different device sizes as needed. Use the
setmethod of this class to display an image located in an asset catalog or in your Watch app bundle.
You can store animated image sequences in your Watch app bundle, but your image files must use specific naming conventions. For information about these conventions, see Animating a Series of Images.
Store downloaded image files in your WatchKit extension’s container directory. Image files must be stored locally in your extension’s container directory and loaded into memory at runtime. When loading an image file that you want to display without modification, load the raw image data into an
NSDataobject and use the
setmethod to display it in your interface. Raw image data is typically compressed and can be sent more quickly than a
Set dynamically created images directly. For content that you draw programmatically, create a
UIImageof the final results and display it using the
setmethod. You also use this technique for animated images sequences you create dynamically using the
Image Named(_: duration:)
When creating your images, always create them at a size that is appropriate for the underlying device. Whenever possible, try to use the same size image regardless of the underlying device. In cases where you need different images for different device sizes, use asset catalogs to store the different versions of the image using the same image name. If the image you specify is too large or too small, WatchKit uses the mode attribute you set in Interface Builder to determine how to render the image.
Supported Image Formats
You can specify images using any image formats supported by iOS, but it is recommended that you use JPEG and PNG images whenever possible. Specifying images in formats other than JPEG and PNG can introduce a performance penalty when rendering those images. All images should be designed for Retina displays, and image filenames you provide yourself should include the
@2x modifier in the filename.
For more information about the supported image formats, see
Animating a Series of Images
Animated images are an easy and fast way to make your interface more dynamic and engaging for users. You create animated images from existing images in your asset catalog or by creating a
UIImage object using the images you want.
For animations based on images in your asset catalogs, name your image resources using the convention <name><number>, where the <name> string is the same for all images and the <number> value indicates the position of the image in the animation sequence. The number of the first image in the sequence must be
1. For example, an animation with three images could have the file names
image3. If you store image resource files in your Watch app bundle without using asset catalogs, the naming convention for your image files is the same except your files should also have the appropriate filename extension.
Whenever possible, place image resources in an asset catalog in your Watch app bundle (not in your WatchKit extension’s bundle). Placing them in the Watch app bundle lets you use the
set method to load the animated image at runtime, which simplifies the loading process. For animations you generate dynamically, use the
animated method of
UIImage to assemble your animation in your WatchKit extension, and then set that animation using the
Additional Information About Images in watchOS 1
Storing images in your Watch app bundle is preferable because it avoids the need to transfer them wirelessly to the user’s Apple Watch before they can be used. For frequently used images, you can cache the images in advance using the methods of the
WKInterface class. Image caching is not supported in watchOS 2.
WatchKit coalesces the data from all setter method calls made during the same run loop iteration and transmits that data to the user’s Apple Watch at the end of the run loop. If you set an attribute to different values in the same run loop iteration, only the last value is transmitted. If you set an attribute to the same value in the same run loop iteration, WatchKit generates a log message so that you can track down the duplicate change.
Interface Builder Configuration Options
Xcode lets you configure information about your image interface object in your storyboard file. Table 1 lists the attributes you can configure and their meaning.
The name of the image to be displayed. This image must be in the Watch app’s bundle. If you do not set the image in your storyboard, set it programmatically using the methods of this class.
The content mode for the image. The mode defines how the image fills the available space. Some modes let you scale the image with or without maintaining the current aspect ratio. Other modes position the image relative to a fixed point in the image interface object’s bounds.
The color applied to a template image. You can change the tint color programmatically by calling the
A Boolean value indicating whether the image is animatable. Set the value to Yes to configure the animation parameters, including its duration (in seconds) and whether it starts immediately when the parent interface controller appears onscreen. Animations started at load time run continuously in a loop.