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
37unsafe impl NSObjectProtocol for UIUpdateActionPhase {}
38
39impl UIUpdateActionPhase {
40 extern_methods!(
41 #[unsafe(method(new))]
42 #[unsafe(method_family = new)]
43 pub unsafe fn new(mtm: MainThreadMarker) -> Retained<Self>;
44
45 #[unsafe(method(init))]
46 #[unsafe(method_family = init)]
47 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
48
49 /// Phase that runs after UI update was scheduled and its timing information is know. This is a good place for things
50 /// that only rely on UI update timing and don't need user input events. Running at this stage allows to utilize time
51 /// that otherwise would be wasted waiting for user input events to arrive. Purely time driven client side animations or
52 /// non-interactive simulations should go here.
53 #[unsafe(method(afterUpdateScheduled))]
54 #[unsafe(method_family = none)]
55 pub unsafe fn afterUpdateScheduled(mtm: MainThreadMarker) -> Retained<UIUpdateActionPhase>;
56
57 /// Before `UIEvent` and `UIGestureRecognizer` handlers run. Use this phase to prepare resources and data structures
58 /// required to process user input events.
59 #[unsafe(method(beforeEventDispatch))]
60 #[unsafe(method_family = none)]
61 pub unsafe fn beforeEventDispatch(mtm: MainThreadMarker) -> Retained<UIUpdateActionPhase>;
62
63 /// After `UIEvent` and `UIGestureRecognizer` handlers run. Past this point, there will be no new user input events sent
64 /// to the application. If low-latency event delivery was requested, more events might be dispatched in
65 /// `LowLatencyEventDispatch` phase. Use this phase to react on application state after processing all user input events
66 /// for the UI update, like starting a parallel rendering thread. Also, if your application uses extrapolation to smooth
67 /// out low-rate event stream, use this phase to detect that certain events were not received to extrapolate them.
68 #[unsafe(method(afterEventDispatch))]
69 #[unsafe(method_family = none)]
70 pub unsafe fn afterEventDispatch(mtm: MainThreadMarker) -> Retained<UIUpdateActionPhase>;
71
72 /// Before `CADisplayLink` callbacks run.
73 #[unsafe(method(beforeCADisplayLinkDispatch))]
74 #[unsafe(method_family = none)]
75 pub unsafe fn beforeCADisplayLinkDispatch(
76 mtm: MainThreadMarker,
77 ) -> Retained<UIUpdateActionPhase>;
78
79 /// After `CADisplayLink` callbacks run.
80 #[unsafe(method(afterCADisplayLinkDispatch))]
81 #[unsafe(method_family = none)]
82 pub unsafe fn afterCADisplayLinkDispatch(
83 mtm: MainThreadMarker,
84 ) -> Retained<UIUpdateActionPhase>;
85
86 /// Before `CATransaction` is flushed.
87 #[unsafe(method(beforeCATransactionCommit))]
88 #[unsafe(method_family = none)]
89 pub unsafe fn beforeCATransactionCommit(
90 mtm: MainThreadMarker,
91 ) -> Retained<UIUpdateActionPhase>;
92
93 /// After `CATransaction` is flushed. Any changes to CoreAnimation layer tree made here (or later) will not appear on
94 /// screen with the current UI update (they will go on screen with the next UI update). There are few exceptions to
95 /// this rule however:
96 /// - It's still possible to `+[CATransaction commit]` or `+[CATransaction flush]` manually which will send latest
97 /// CoreAnimation layer changes to render server immediately. Doing so is not recommended as in addition to intended
98 /// changes other potentially unrelated changes might be sent to the render server prematurely.
99 /// - If low-latency event dispatch will be performed, then all CoreAnimation layer tree changes that done before
100 /// or during `LowLatencyCATransactionCommit` phase will appear on screen with this UI update.
101 #[unsafe(method(afterCATransactionCommit))]
102 #[unsafe(method_family = none)]
103 pub unsafe fn afterCATransactionCommit(
104 mtm: MainThreadMarker,
105 ) -> Retained<UIUpdateActionPhase>;
106
107 /// Before `UIEvent` and `UIGestureRecognizer` handlers run for low-latency eligible events. This stage is
108 /// off by default (skipped) and must be requested explicitly.
109 #[unsafe(method(beforeLowLatencyEventDispatch))]
110 #[unsafe(method_family = none)]
111 pub unsafe fn beforeLowLatencyEventDispatch(
112 mtm: MainThreadMarker,
113 ) -> Retained<UIUpdateActionPhase>;
114
115 /// After `UIEvent` and `UIGestureRecognizer` handlers run for low-latency eligible events. This stage is
116 /// off by default (skipped) and must be requested explicitly.
117 #[unsafe(method(afterLowLatencyEventDispatch))]
118 #[unsafe(method_family = none)]
119 pub unsafe fn afterLowLatencyEventDispatch(
120 mtm: MainThreadMarker,
121 ) -> Retained<UIUpdateActionPhase>;
122
123 /// Before `CATransaction` is flushed. Only runs when low-latency event dispatch was requested.
124 #[unsafe(method(beforeLowLatencyCATransactionCommit))]
125 #[unsafe(method_family = none)]
126 pub unsafe fn beforeLowLatencyCATransactionCommit(
127 mtm: MainThreadMarker,
128 ) -> Retained<UIUpdateActionPhase>;
129
130 /// After `CATransaction` is flushed. Only runs when low-latency event dispatch was requested. Any changes to
131 /// CoreAnimation layer tree made here (or later) will not appear on screen with the current UI update.
132 #[unsafe(method(afterLowLatencyCATransactionCommit))]
133 #[unsafe(method_family = none)]
134 pub unsafe fn afterLowLatencyCATransactionCommit(
135 mtm: MainThreadMarker,
136 ) -> Retained<UIUpdateActionPhase>;
137
138 /// The very end of the UI update. If there's still time until `completionDeadlineTime`, it's generally safe to do any
139 /// idle opportunistic work here, like the one that was deferred from more time critical parts of the UI update. It's
140 /// also a good place to record last presented state, for things like on-screen velocity computations.
141 #[unsafe(method(afterUpdateComplete))]
142 #[unsafe(method_family = none)]
143 pub unsafe fn afterUpdateComplete(mtm: MainThreadMarker) -> Retained<UIUpdateActionPhase>;
144 );
145}