Class

WKInterfaceObject

An object that provides information that is common to all interface objects in your watchOS app.

Overview

Your WatchKit extension uses interface objects to manipulate the visual elements displayed on Apple Watch. Specifically, you use the methods of this class to change the size, alignment, and visibility of those elements. You can also configure the accessibility information displayed through assistive technologies like VoiceOver.

Do not subclass or create instances of this class, or any of its subclasses, 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 a button in your interface, define a property with the following syntax in your interface controller class:

@IBOutlet weak var button: WKInterfaceButton!

At runtime, WatchKit creates the appropriate interface objects and assigns them to the outlets in your interface controller.

Communication between an interface object in your extension and the corresponding interface element in your Watch app is one way. You can set the values of an interface object, but you cannot get the current values. If you want to know the current value of an attribute, you must save the value yourself.

Additional Information for watchOS 1

In watchOS 1, calling a setter method on an interface object has performance and latency implications for your app. All data must be transmitted wirelessly to the user’s Apple Watch before the corresponding interface elements can be updated. To minimize the performance impact, 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 group interface object in your storyboard file. Table 1 lists the attributes you can configure in your storyboard and their meaning.

Table 1

WatchKit object attributes

Attribute

Description

Alpha

The opacity of the object. A value of 1.0 represents fully opaque and a value of 0.0 represents fully transparent.

Hidden

A checkbox indicating whether the item is hidden initially. You can change the visibility of the item programmatically by calling the setHidden(_:) method.

Installed

A checkbox indicating whether the item is installed for the current device.

Horizontal

The horizontal alignment of the item. Use this attribute to configure the horizontal position of the item relative to its immediate parent.

Vertical

The vertical alignment of the item. Use this attribute to configure the vertical position of the item relative to its immediate parent.

Width

The width of the object. Specify a fixed width or set the value of the object to be a percentage of its container’s width.

Height

The height of the object. Specify a fixed height or set the value of the object to be a percentage of its container’s height.

Symbols

Hiding and Showing an Object

func setHidden(Bool)

Hides or shows the interface object in your user interface.

func setAlpha(CGFloat)

Sets the opacity of the interface object.

Getting the Property Name

var interfaceProperty: String

The name of the outlet in your interface controller to which the object is bound.

Changing an Object’s Size

func setWidth(CGFloat)

Sets the absolute width (in points) of the object.

func setHeight(CGFloat)

Sets the absolute height (in points) of the object.

func setRelativeWidth(CGFloat, withAdjustment: CGFloat)

Sets the width of the object relative to its container.

func setRelativeHeight(CGFloat, withAdjustment: CGFloat)

Sets the height of the object relative to its container.

func sizeToFitWidth()

Sets the width of the object to fit its current content.

func sizeToFitHeight()

Sets the height of the object so that it fills the available vertical space.

Setting an Object’s Alignment

func setHorizontalAlignment(WKInterfaceObjectHorizontalAlignment)

Sets the horizontal alignment of an object relative to its container’s bounds.

func setVerticalAlignment(WKInterfaceObjectVerticalAlignment)

Sets the vertical alignment of an object relative to its container’s bounds.

Configuring the Accessibility Attributes

func setAccessibilityIdentifier(String?)

Sets the unique identifier string for the interface object.

func setAccessibilityLabel(String?)

Sets a succinct label on the object that identifies the accessibility element.

func setAccessibilityHint(String?)

Sets the description of what happens when performing an action on the accessibility element.

func setAccessibilityValue(String?)

Sets the value of the accessibility element.

func setIsAccessibilityElement(Bool)

Sets whether the object is an accessibility element that an assistive app can access.

func setAccessibilityTraits(UIAccessibilityTraits)

Sets the combination of accessibility traits that best characterize the accessibility element.

func setAccessibilityImageRegions([WKAccessibilityImageRegion])

Marks portions of an image as separate accessible elements.

Setting the Layout Direction

func setSemanticContentAttribute(WKInterfaceSemanticContentAttribute)

Sets the semantic description of the object’s contents, used to determine whether its content should be flipped when switching between left-to-right and right-to-left layouts.

Constants

WKInterfaceObjectHorizontalAlignment

Constants for horizontally aligning objects in their container.

WKInterfaceObjectVerticalAlignment

Constants for vertically aligning objects in their container.

Relationships

Inherits From

Conforms To