Flutter macOS Embedder
FlutterEngine_Internal.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_SOURCE_FLUTTERENGINE_INTERNAL_H_
6 #define FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_SOURCE_FLUTTERENGINE_INTERNAL_H_
7 
9 
10 #import <Cocoa/Cocoa.h>
11 
12 #include <memory>
13 
15 
22 
24 
25 #pragma mark - Typedefs
26 
27 typedef void (^FlutterTerminationCallback)(id _Nullable sender);
28 
29 #pragma mark - Enumerations
30 
31 /**
32  * An enum for defining the different request types allowed when requesting an
33  * application exit.
34  *
35  * Must match the entries in the `AppExitType` enum in the Dart code.
36  */
37 typedef NS_ENUM(NSInteger, FlutterAppExitType) {
38  kFlutterAppExitTypeCancelable = 0,
39  kFlutterAppExitTypeRequired = 1,
40 };
41 
42 /**
43  * An enum for defining the different responses the framework can give to an
44  * application exit request from the engine.
45  *
46  * Must match the entries in the `AppExitResponse` enum in the Dart code.
47  */
48 typedef NS_ENUM(NSInteger, FlutterAppExitResponse) {
49  kFlutterAppExitResponseCancel = 0,
50  kFlutterAppExitResponseExit = 1,
51 };
52 
53 #pragma mark - FlutterEngineTerminationHandler
54 
55 /**
56  * A handler interface for handling application termination that the
57  * FlutterAppDelegate can use to coordinate an application exit by sending
58  * messages through the platform channel managed by the engine.
59  */
60 @interface FlutterEngineTerminationHandler : NSObject
61 
62 @property(nonatomic, readonly) BOOL shouldTerminate;
63 @property(nonatomic, readwrite) BOOL acceptingRequests;
64 
65 - (instancetype)initWithEngine:(FlutterEngine*)engine
66  terminator:(nullable FlutterTerminationCallback)terminator;
67 - (void)handleRequestAppExitMethodCall:(NSDictionary<NSString*, id>*)data
68  result:(FlutterResult)result;
69 - (void)requestApplicationTermination:(NSApplication*)sender
70  exitType:(FlutterAppExitType)type
71  result:(nullable FlutterResult)result;
72 @end
73 
74 /**
75  * An NSPasteboard wrapper object to allow for substitution of a fake in unit tests.
76  */
77 @interface FlutterPasteboard : NSObject
78 - (NSInteger)clearContents;
79 - (NSString*)stringForType:(NSPasteboardType)dataType;
80 - (BOOL)setString:(NSString*)string forType:(NSPasteboardType)dataType;
81 @end
82 
83 @interface FlutterEngine ()
84 
85 /**
86  * True if the engine is currently running.
87  */
88 @property(nonatomic, readonly) BOOL running;
89 
90 /**
91  * Provides the renderer config needed to initialize the engine and also handles external
92  * texture management.
93  */
94 @property(nonatomic, readonly, nullable) FlutterRenderer* renderer;
95 
96 /**
97  * Function pointers for interacting with the embedder.h API.
98  */
99 @property(nonatomic) FlutterEngineProcTable& embedderAPI;
100 
101 /**
102  * True if the semantics is enabled. The Flutter framework starts sending
103  * semantics update through the embedder as soon as it is set to YES.
104  */
105 @property(nonatomic) BOOL semanticsEnabled;
106 
107 /**
108  * The executable name for the current process.
109  */
110 @property(nonatomic, readonly, nonnull) NSString* executableName;
111 
112 /**
113  * This just returns the NSPasteboard so that it can be mocked in the tests.
114  */
115 @property(nonatomic, nonnull) FlutterPasteboard* pasteboard;
116 
117 /**
118  * The command line arguments array for the engine.
119  */
120 @property(nonatomic, readonly) std::vector<std::string> switches;
121 
122 /**
123  * Provides the |FlutterEngineTerminationHandler| to be used for this engine.
124  */
125 @property(nonatomic, readonly) FlutterEngineTerminationHandler* terminationHandler;
126 
127 /**
128  * Attach a view controller to the engine as its default controller.
129  *
130  * Since FlutterEngine can only handle the implicit view for now, the given
131  * controller will always be assigned to the implicit view, if there isn't an
132  * implicit view yet. If the engine already has an implicit view, this call
133  * throws an assertion.
134  *
135  * The engine holds a weak reference to the attached view controller.
136  *
137  * If the given view controller is already attached to an engine, this call
138  * throws an assertion.
139  */
140 - (void)addViewController:(FlutterViewController*)viewController;
141 
142 /**
143  * Notify the engine that a view for the given view controller has been loaded.
144  */
145 - (void)viewControllerViewDidLoad:(FlutterViewController*)viewController;
146 
147 /**
148  * Dissociate the given view controller from this engine.
149  *
150  * If the view controller is not associated with this engine, this call throws an
151  * assertion.
152  */
153 - (void)removeViewController:(FlutterViewController*)viewController;
154 
155 /**
156  * The |FlutterViewController| associated with the given view ID, if any.
157  */
158 - (nullable FlutterViewController*)viewControllerForIdentifier:
159  (FlutterViewIdentifier)viewIdentifier;
160 
161 /**
162  * Informs the engine that the specified view controller's window metrics have changed.
163  */
164 - (void)updateWindowMetricsForViewController:(FlutterViewController*)viewController;
165 
166 /**
167  * Dispatches the given pointer event data to engine.
168  */
169 - (void)sendPointerEvent:(const FlutterPointerEvent&)event;
170 
171 /**
172  * Registers an external texture with the given id. Returns YES on success.
173  */
174 - (BOOL)registerTextureWithID:(int64_t)textureId;
175 
176 /**
177  * Marks texture with the given id as available. Returns YES on success.
178  */
179 - (BOOL)markTextureFrameAvailable:(int64_t)textureID;
180 
181 /**
182  * Unregisters an external texture with the given id. Returns YES on success.
183  */
184 - (BOOL)unregisterTextureWithID:(int64_t)textureID;
185 
186 - (nonnull FlutterPlatformViewController*)platformViewController;
187 
188 /**
189  * Handles changes to the application state, sending them to the framework.
190  *
191  * @param state One of the lifecycle constants in app_lifecycle_state.h,
192  * corresponding to the Dart enum AppLifecycleState.
193  */
194 - (void)setApplicationState:(flutter::AppLifecycleState)state;
195 
196 // Accessibility API.
197 
198 /**
199  * Dispatches semantics action back to the framework. The semantics must be enabled by calling
200  * the updateSemanticsEnabled before dispatching semantics actions.
201  */
202 - (void)dispatchSemanticsAction:(FlutterSemanticsAction)action
203  toTarget:(uint16_t)target
204  withData:(fml::MallocMapping)data;
205 
206 /**
207  * Handles accessibility events.
208  */
209 - (void)handleAccessibilityEvent:(NSDictionary<NSString*, id>*)annotatedEvent;
210 
211 /**
212  * Announces accessibility messages.
213  */
214 - (void)announceAccessibilityMessage:(NSString*)message
215  withPriority:(NSAccessibilityPriorityLevel)priority;
216 
217 /**
218  * Returns keyboard manager for the engine.
219  */
220 @property(nonatomic, readonly) FlutterKeyboardManager* keyboardManager;
221 
222 /**
223  * Returns text input plugin for the engine.
224  */
225 @property(nonatomic, readonly) FlutterTextInputPlugin* textInputPlugin;
226 
227 @property(nonatomic, readonly) FlutterWindowController* windowController;
228 
229 /**
230  * Enables multi-view support.
231  *
232  * Called by [FlutterWindowController] before the first view is added. This
233  * affects the behavior when adding view controllers:
234  *
235  * - When multiview is disabled, the engine will only assign views to the
236  * implicit view ID. The implicit view ID can be reused if and only if the
237  * implicit view ID is unassigned.
238  * - When multiview is enabled, the engine will assign views to a
239  * self-incrementing ID.
240  *
241  * Calling enableMultiView when multiview is already enabled is a noop.
242  */
243 - (void)enableMultiView;
244 
245 /**
246  * Notifies the engine that window with the given identifier has been made key.
247  */
248 - (void)windowDidBecomeKey:(FlutterViewIdentifier)viewIdentifier;
249 
250 /**
251  * Notifies the engine that window with the given identifier has resigned being key.
252  */
253 - (void)windowDidResignKey:(FlutterViewIdentifier)viewIdentifier;
254 
255 /**
256  * Returns an array of screen objects representing all of the screens available on the system.
257  */
258 - (NSArray<NSScreen*>*)screens;
259 
260 /**
261  * Returns engine for the identifier. The identifier must be valid for an engine
262  * that is currently running, otherwise the behavior is undefined.
263  *
264  * The identifier can be obtained in Dart code through
265  * `PlatformDispatcher.instance.engineId`.
266  *
267  * This function must be called on the main thread.
268  */
269 + (nullable FlutterEngine*)engineForIdentifier:(int64_t)identifier;
270 
271 @end
272 
274 
275 #endif // FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_SOURCE_FLUTTERENGINE_INTERNAL_H_
void(^ FlutterResult)(id _Nullable result)
NS_ASSUME_NONNULL_BEGIN typedef void(^ FlutterTerminationCallback)(id _Nullable sender)
typedef NS_ENUM(NSInteger, FlutterAppExitType)
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
int64_t FlutterViewIdentifier
NSInteger clearContents()