A set of methods for communicating the progress of a preview interaction.
- iOS 10.0+
- Mac Catalyst 13.0+
- tvOS 10.0+
A preview interaction abstracts a 3D Touch interaction into a state machine and communicates its progress through the state machine via a delegate. The developer is responsible for implementing the appropriate UI behavior.
Create an object that conforms to this protocol and assign it to the
delegate property on an instance of
UIPreview. Use this delegate object to respond to the state changes that occur within the preview interaction as the user performs 3D Touch interactions.
Controlling Preview Interaction State Changes
The methods on
UIPreview allow you to control whether a preview interaction is allowed to begin, and to observe its progress through the phases of a preview interaction. This allows you to provide a custom user experience while maintaining coherence with the system.
A preview interaction consists of two main phases: preview and commit. Figure 1 is a visualization of the underlying state machine associated with a preview interaction.
preview method is called as the user begins to press on a view that has a preview interaction associated with it. Implement this method and return
NO to prevent the preview interaction from continuing. Returning
YES, or not implementing this optional method, will allow the preview interaction to continue.
Once a preview interaction begins, it enters the first phase—also called preview—through which it progresses as the user presses harder on the view. During this phase, the
preview method is called repeatedly, reporting the progress through the transition as a
CGFloat with a value from
1. Implement this method and use the
transition parameter to update the UI, providing visual feedback to the user.
ended parameter changes from
YES, the preview interaction transitions to the second phase—commit. There are no further calls to the
preview delegate method.
The progress through the commit phase is reported to the
preview delegate method. Implement this method and use the
rogress parameter to update the UI appropriately. The preview interaction is said to be completed when the
ended parameter is true, at which point you should complete any UI changes.
At any point before the preview interaction is completed, it can be canceled, either when the user lifts their finger from the screen, or when the
cancel method is called on the
UIPreview instance. When this happens, the
preview delegate method is called. You should use this method to cancel any UI transitions currently in progress.
Preview Interaction User Interface Updates
UIPreview abstracts 3D Touch interactions away from touch force, allowing you to provide your own user interface updates for an interaction pattern that is well understood by your users. The preview interaction sits between view controller previewing (peek and pop) and the force values in
UITouch, in that you are required to provide your own user interface updates but don't need to handle raw touch force values.
It is important that during the preview and commit phases, you update the UI in such a way that the user is aware that the interaction is taking place. For example, pressing a table row in the Mail app first progressively blurs the other rows (the preview phase), and then shows a popover of the email as the commit phase begins. Throughout the commit phase, the popover grows, before finally transitioning to the email detail view at the end of the commit phase.
You can provide any user experience you want to accompany the preview and commit phases, but be sure to follow the appropriate section on 3D Touch in the iOS Human Interface Guidelines. Consider using
UIView to implement the UI changes that track the progress through the preview and commit phases of the preview interaction. This class allows you to build an animation and then scrub through that animation, using the
fraction property. This maps perfectly to the
transition property provided in the
preview methods, allowing you to use
UIView to update the UI in response to the user's touch force.