objc2_ui_kit/generated/UIUpdateActionPhase.rs
1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ptr::NonNull;
4use objc2::__framework_prelude::*;
5
6use crate::*;
7
8extern_class!(
9 /// Each UI update consists of several phases which run in order, one after another. There are two phase groups - normal
10 /// and low-latency. Normal phase group consists of phases from `EventDispatch` to `CATransactionCommit`. Low-latency
11 /// phase group consists of phases from `LowLatencyEventDispatch` to `LowLatencyCATransactionCommit`. When phase group
12 /// runs, all phases inside the group run. Phases run one after another in the specified order without exiting back into
13 /// the run loop. Spinning a nested run loop inside any of the phases is not supported. For each UI update, normal phase
14 /// group always runs. Low-latency phase group is optional and is off by default. It will run only when application
15 /// explicitly requests low-latency event delivery. Be aware that handling low-level events is extremely demanding and
16 /// only well profiled and optimized applications can benefit from it. Applications that were not designed to handle
17 /// low-latency events will most likely drop frames. Also not all event types are eligible for low-latency event
18 /// delivery. Currently only pencil events are low-latency eligible. This practically means that only pencil drawing
19 /// and writing applications should request it.
20 /// It's acceptable to block main thread in any of the phases to wait for things that are absolutely required to
21 /// proceed. When done properly, this will donate main thread priority to the thread being waited for, making it more
22 /// likely to get those things in time and meet the completion deadline. Of course, extreme caution should be exercised
23 /// when doing so - maximum wait time should have a hard limit on it that still allows to complete the remaining part
24 /// of the UI update before completion deadline. Use of `-[CAMetalLayer nextDrawable]` is of a particular note - it's
25 /// not advised to use it on the main thread of the UI application as it might block main thread for one or more frames.
26 /// Instead, consider calling `-[CAMetalLayer nextDrawable]` on the background thread and block main thread manually
27 /// in one of the phases. Use small timeout that allows for UI update to proceed without a new drawable and still finish
28 /// before the completion deadline.
29 ///
30 /// See also [Apple's documentation](https://developer.apple.com/documentation/uikit/uiupdateactionphase?language=objc)
31 #[unsafe(super(NSObject))]
32 #[thread_kind = MainThreadOnly]
33 #[derive(Debug, PartialEq, Eq, Hash)]
34 pub struct UIUpdateActionPhase;
35);
36
37extern_conformance!(
38 unsafe impl NSObjectProtocol for UIUpdateActionPhase {}
39);
40
41impl UIUpdateActionPhase {
42 extern_methods!(
43 #[unsafe(method(new))]
44 #[unsafe(method_family = new)]
45 pub unsafe fn new(mtm: MainThreadMarker) -> Retained<Self>;
46
47 #[unsafe(method(init))]
48 #[unsafe(method_family = init)]
49 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
50
51 /// Phase that runs after UI update was scheduled and its timing information is know. This is a good place for things
52 /// that only rely on UI update timing and don't need user input events. Running at this stage allows to utilize time
53 /// that otherwise would be wasted waiting for user input events to arrive. Purely time driven client side animations or
54 /// non-interactive simulations should go here.
55 #[unsafe(method(afterUpdateScheduled))]
56 #[unsafe(method_family = none)]
57 pub unsafe fn afterUpdateScheduled(mtm: MainThreadMarker) -> Retained<UIUpdateActionPhase>;
58
59 /// Before `UIEvent` and `UIGestureRecognizer` handlers run. Use this phase to prepare resources and data structures
60 /// required to process user input events.
61 #[unsafe(method(beforeEventDispatch))]
62 #[unsafe(method_family = none)]
63 pub unsafe fn beforeEventDispatch(mtm: MainThreadMarker) -> Retained<UIUpdateActionPhase>;
64
65 /// After `UIEvent` and `UIGestureRecognizer` handlers run. Past this point, there will be no new user input events sent
66 /// to the application. If low-latency event delivery was requested, more events might be dispatched in
67 /// `LowLatencyEventDispatch` phase. Use this phase to react on application state after processing all user input events
68 /// for the UI update, like starting a parallel rendering thread. Also, if your application uses extrapolation to smooth
69 /// out low-rate event stream, use this phase to detect that certain events were not received to extrapolate them.
70 #[unsafe(method(afterEventDispatch))]
71 #[unsafe(method_family = none)]
72 pub unsafe fn afterEventDispatch(mtm: MainThreadMarker) -> Retained<UIUpdateActionPhase>;
73
74 /// Before `CADisplayLink` callbacks run.
75 #[unsafe(method(beforeCADisplayLinkDispatch))]
76 #[unsafe(method_family = none)]
77 pub unsafe fn beforeCADisplayLinkDispatch(
78 mtm: MainThreadMarker,
79 ) -> Retained<UIUpdateActionPhase>;
80
81 /// After `CADisplayLink` callbacks run.
82 #[unsafe(method(afterCADisplayLinkDispatch))]
83 #[unsafe(method_family = none)]
84 pub unsafe fn afterCADisplayLinkDispatch(
85 mtm: MainThreadMarker,
86 ) -> Retained<UIUpdateActionPhase>;
87
88 /// Before `CATransaction` is flushed.
89 #[unsafe(method(beforeCATransactionCommit))]
90 #[unsafe(method_family = none)]
91 pub unsafe fn beforeCATransactionCommit(
92 mtm: MainThreadMarker,
93 ) -> Retained<UIUpdateActionPhase>;
94
95 /// After `CATransaction` is flushed. Any changes to CoreAnimation layer tree made here (or later) will not appear on
96 /// screen with the current UI update (they will go on screen with the next UI update). There are few exceptions to
97 /// this rule however:
98 /// - It's still possible to `+[CATransaction commit]` or `+[CATransaction flush]` manually which will send latest
99 /// CoreAnimation layer changes to render server immediately. Doing so is not recommended as in addition to intended
100 /// changes other potentially unrelated changes might be sent to the render server prematurely.
101 /// - If low-latency event dispatch will be performed, then all CoreAnimation layer tree changes that done before
102 /// or during `LowLatencyCATransactionCommit` phase will appear on screen with this UI update.
103 #[unsafe(method(afterCATransactionCommit))]
104 #[unsafe(method_family = none)]
105 pub unsafe fn afterCATransactionCommit(
106 mtm: MainThreadMarker,
107 ) -> Retained<UIUpdateActionPhase>;
108
109 /// Before `UIEvent` and `UIGestureRecognizer` handlers run for low-latency eligible events. This stage is
110 /// off by default (skipped) and must be requested explicitly.
111 #[unsafe(method(beforeLowLatencyEventDispatch))]
112 #[unsafe(method_family = none)]
113 pub unsafe fn beforeLowLatencyEventDispatch(
114 mtm: MainThreadMarker,
115 ) -> Retained<UIUpdateActionPhase>;
116
117 /// After `UIEvent` and `UIGestureRecognizer` handlers run for low-latency eligible events. This stage is
118 /// off by default (skipped) and must be requested explicitly.
119 #[unsafe(method(afterLowLatencyEventDispatch))]
120 #[unsafe(method_family = none)]
121 pub unsafe fn afterLowLatencyEventDispatch(
122 mtm: MainThreadMarker,
123 ) -> Retained<UIUpdateActionPhase>;
124
125 /// Before `CATransaction` is flushed. Only runs when low-latency event dispatch was requested.
126 #[unsafe(method(beforeLowLatencyCATransactionCommit))]
127 #[unsafe(method_family = none)]
128 pub unsafe fn beforeLowLatencyCATransactionCommit(
129 mtm: MainThreadMarker,
130 ) -> Retained<UIUpdateActionPhase>;
131
132 /// After `CATransaction` is flushed. Only runs when low-latency event dispatch was requested. Any changes to
133 /// CoreAnimation layer tree made here (or later) will not appear on screen with the current UI update.
134 #[unsafe(method(afterLowLatencyCATransactionCommit))]
135 #[unsafe(method_family = none)]
136 pub unsafe fn afterLowLatencyCATransactionCommit(
137 mtm: MainThreadMarker,
138 ) -> Retained<UIUpdateActionPhase>;
139
140 /// The very end of the UI update. If there's still time until `completionDeadlineTime`, it's generally safe to do any
141 /// idle opportunistic work here, like the one that was deferred from more time critical parts of the UI update. It's
142 /// also a good place to record last presented state, for things like on-screen velocity computations.
143 #[unsafe(method(afterUpdateComplete))]
144 #[unsafe(method_family = none)]
145 pub unsafe fn afterUpdateComplete(mtm: MainThreadMarker) -> Retained<UIUpdateActionPhase>;
146 );
147}