UnobstructedArea

Events about when the app's unobstructed area changes for visually adapting

Unobstructed Area enables a watchface to adapt to overlays partially obstructing it. Timeline Peek is the only overlay, and it partially obstructs the bottom of watchfaces, displaying the immediately upcoming or newly began event. Unobstructed Area is for use only with watchfaces. There will be no Unobstructed Area events emitted for apps that are not watchfaces. Timeline Peek is also limited to rectangular platforms, thus using Unobstructed Area on Chalk will also result in no events.

Watchfaces are encouraged to respect Unobstructed Area in order to dynamically resize within the remaining screen area that isn't obstructed by an overlay. Unobstructed Area provides handlers for when the screen area will begin and end changing as well as progress for every frame of the animation, allowing one to animate the watchface to resize while the overlay animates into or out of the screen. Additionally, at any point, a watchface can query the Unobstructed Area using layer_get_unobstructed_bounds even if there was not event or if it didn't subscribe to them.

The simplest usage of Unobstructed Area is to change rendering of your watchface to render within the unobstructed bounds obtained by layer_get_unobstructed_bounds. This is accomplished by modifying your layer update procedure that you setup a layer with using layer_set_update_proc to use layer_get_unobstructed_bounds instead of layer_get_bounds or layer_get_frame and adjusting all the rendering logic within it to handle resizing bounds. The app will redraw automatically whenever the Unobstructed Area changes, even if you did not subscribe to the events.

Subscribing to will_change, change, and did_change events with app_unobstructed_area_service_subscribe will allow you to obtain the final unobstructed area as soon as the animation begins and the current animation progress for each frame as they occur should you need that information to resize your watchface.

When designing your watchface resizing logic or animation, take into consideration the way Timeline Peek animates. Timeline Peek appears from the bottom with an animation that moves slightly at first and snaps across with a bounce back. Because there is a bounce back in the animation, there will be momentary frames where the unobstructed area is slightly smaller than when Timeline Peek is visible but not animating.

If you intend to hide or show layers on the screen depending on the unobstructed area, there are two ways to do this. For anything inside a layer update procedure the simple solution would be sufficient. That is, in your update procedure, you can to determine whether something is to be rendered or not based on the remaining height available to you determined from layer_get_unobstructed_bounds.

The other method for deciding whether to show or hide layers is to subscribe to events using app_unobstructed_area_service_subscribe. Note that hiding or showing elements in your will_change can be too early due to the nature of the Timeline Peek animation where it moves slowly in the first few frames. After judging the animation visually, you may instead show or hide your layers based on both the final unobstructed area obtained from will_change in combination with the progress obtained from change, or check the current height available to you by calling layer_get_unobstructed_bounds in your change handler to update your state.

For more advance usages such as functionally defined animations whose animation frames are a function of animation progress, you will want to subscribe to will_change, change, and optionally did_change events if you need to clean up resources or layers created in your will_change handler. For example, in your will_change handler, you may use layer_get_unobstructed_bounds to get the current unobstructed area, and combine it with the final unobstructed area passed into will_change to set up a PropertyAnimation. A separate example would be to save the animation progress passed to your change handler for use in your own custom easing curve in your layer update procedure.

Function Documentation

Data Structure Documentation

Typedef Documentation