| 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
8 #import "flutter/shell/platform/darwin/macos/framework/Headers/FlutterEngine.h"
9
10 #import <Cocoa/Cocoa.h>
11
12 #include <memory>
13
14 #include "flutter/shell/platform/common/app_lifecycle_state.h"
15
16 #import "flutter/shell/platform/darwin/macos/framework/Source/AccessibilityBridgeMac.h"
17 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardManager.h"
18 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterPlatformViewController.h"
19 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterRenderer.h"
20 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterTextInputPlugin.h"
21 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterWindowController.h"
22
23 NS_ASSUME_NONNULL_BEGIN
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 * The project associated with this engine.
92 */
93 @property(nonatomic, readonly, nonnull) FlutterDartProject* project;
94
95 /**
96 * Provides the renderer config needed to initialize the engine and also handles external
97 * texture management.
98 */
99 @property(nonatomic, readonly, nullable) FlutterRenderer* renderer;
100
101 /**
102 * Function pointers for interacting with the embedder.h API.
103 */
104 @property(nonatomic) FlutterEngineProcTable& embedderAPI;
105
106 /**
107 * True if the semantics is enabled. The Flutter framework starts sending
108 * semantics update through the embedder as soon as it is set to YES.
109 */
110 @property(nonatomic) BOOL semanticsEnabled;
111
112 /**
113 * The executable name for the current process.
114 */
115 @property(nonatomic, readonly, nonnull) NSString* executableName;
116
117 /**
118 * This just returns the NSPasteboard so that it can be mocked in the tests.
119 */
120 @property(nonatomic, nonnull) FlutterPasteboard* pasteboard;
121
122 /**
123 * The command line arguments array for the engine.
124 */
125 @property(nonatomic, readonly) std::vector<std::string> switches;
126
127 /**
128 * Provides the |FlutterEngineTerminationHandler| to be used for this engine.
129 */
130 @property(nonatomic, readonly) FlutterEngineTerminationHandler* terminationHandler;
131
132 /**
133 * Attach a view controller to the engine as its default controller.
134 *
135 * Since FlutterEngine can only handle the implicit view for now, the given
136 * controller will always be assigned to the implicit view, if there isn't an
137 * implicit view yet. If the engine already has an implicit view, this call
138 * throws an assertion.
139 *
140 * The engine holds a weak reference to the attached view controller.
141 *
142 * If the given view controller is already attached to an engine, this call
143 * throws an assertion.
144 */
145 - (void)addViewController:(FlutterViewController*)viewController;
146
147 /**
148 * Notify the engine that a view for the given view controller has been loaded.
149 */
150 - (void)viewControllerViewDidLoad:(FlutterViewController*)viewController;
151
152 /**
153 * Dissociate the given view controller from this engine.
154 *
155 * If the view controller is not associated with this engine, this call throws an
156 * assertion.
157 */
158 - (void)removeViewController:(FlutterViewController*)viewController;
159
160 /**
161 * The |FlutterViewController| associated with the given view ID, if any.
162 */
163 - (nullable FlutterViewController*)viewControllerForIdentifier:
164 (FlutterViewIdentifier)viewIdentifier;
165
166 /**
167 * Informs the engine that the specified view controller's window metrics have changed.
168 */
169 - (void)updateWindowMetricsForViewController:(FlutterViewController*)viewController;
170
171 /**
172 * Dispatches the given pointer event data to engine.
173 */
174 - (void)sendPointerEvent:(const FlutterPointerEvent&)event;
175
176 /**
177 * Registers an external texture with the given id. Returns YES on success.
178 */
179 - (BOOL)registerTextureWithID:(int64_t)textureId;
180
181 /**
182 * Marks texture with the given id as available. Returns YES on success.
183 */
184 - (BOOL)markTextureFrameAvailable:(int64_t)textureID;
185
186 /**
187 * Unregisters an external texture with the given id. Returns YES on success.
188 */
189 - (BOOL)unregisterTextureWithID:(int64_t)textureID;
190
191 - (nonnull FlutterPlatformViewController*)platformViewController;
192
193 /**
194 * Handles changes to the application state, sending them to the framework.
195 *
196 * @param state One of the lifecycle constants in app_lifecycle_state.h,
197 * corresponding to the Dart enum AppLifecycleState.
198 */
199 - (void)setApplicationState:(flutter::AppLifecycleState)state;
200
201 // Accessibility API.
202
203 /**
204 * Dispatches semantics action back to the framework. The semantics must be enabled by calling
205 * the updateSemanticsEnabled before dispatching semantics actions.
206 */
207 - (void)dispatchSemanticsAction:(FlutterSemanticsAction)action
208 toTarget:(uint16_t)target
209 withData:(fml::MallocMapping)data;
210
211 /**
212 * Handles accessibility events.
213 */
214 - (void)handleAccessibilityEvent:(NSDictionary<NSString*, id>*)annotatedEvent;
215
216 /**
217 * Announces accessibility messages.
218 */
219 - (void)announceAccessibilityMessage:(NSString*)message
220 withPriority:(NSAccessibilityPriorityLevel)priority;
221
222 /**
223 * Returns keyboard manager for the engine.
224 */
225 @property(nonatomic, readonly) FlutterKeyboardManager* keyboardManager;
226
227 /**
228 * Returns text input plugin for the engine.
229 */
230 @property(nonatomic, readonly) FlutterTextInputPlugin* textInputPlugin;
231
232 @property(nonatomic, readonly) FlutterWindowController* windowController;
233
234 /**
235 * Enables multi-view support.
236 *
237 * Called by [FlutterWindowController] before the first view is added. This
238 * affects the behavior when adding view controllers:
239 *
240 * - When multiview is disabled, the engine will only assign views to the
241 * implicit view ID. The implicit view ID can be reused if and only if the
242 * implicit view ID is unassigned.
243 * - When multiview is enabled, the engine will assign views to a
244 * self-incrementing ID.
245 *
246 * Calling enableMultiView when multiview is already enabled is a noop.
247 */
248 - (void)enableMultiView;
249
250 /**
251 * Notifies the engine that window with the given identifier has been made key.
252 */
253 - (void)windowDidBecomeKey:(FlutterViewIdentifier)viewIdentifier;
254
255 /**
256 * Notifies the engine that window with the given identifier has resigned being key.
257 */
258 - (void)windowDidResignKey:(FlutterViewIdentifier)viewIdentifier;
259
260 /**
261 * Returns an array of screen objects representing all of the screens available on the system.
262 */
263 - (NSArray<NSScreen*>*)screens;
264
265 /**
266 * Returns engine for the identifier. The identifier must be valid for an engine
267 * that is currently running, otherwise the behavior is undefined.
268 *
269 * The identifier can be obtained in Dart code through
270 * `PlatformDispatcher.instance.engineId`.
271 *
272 * This function must be called on the main thread.
273 */
274 + (nullable FlutterEngine*)engineForIdentifier:(int64_t)identifier;
275
276 /**
277 * Invoked right before the engine is restarted.
278 *
279 * This should reset states to as if the application has just started. It
280 * usually indicates a hot restart (Shift-R in Flutter CLI.)
281 */
282 - (void)engineCallbackOnPreEngineRestart;
283 @end
284
285 NS_ASSUME_NONNULL_END
286
287 #endif // FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_SOURCE_FLUTTERENGINE_INTERNAL_H_
AccessibilityBridgeMac.h
FlutterResult
void(^ FlutterResult)(id _Nullable result)
Definition: FlutterChannels.h:194
FlutterEngine.h
FlutterTerminationCallback
NS_ASSUME_NONNULL_BEGIN typedef void(^ FlutterTerminationCallback)(id _Nullable sender)
NS_ENUM
typedef NS_ENUM(NSInteger, FlutterAppExitType)
Definition: FlutterEngine_Internal.h:37
FlutterKeyboardManager.h
NS_ASSUME_NONNULL_BEGIN
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
NS_ASSUME_NONNULL_END
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
FlutterPlatformViewController.h
FlutterRenderer.h
FlutterTextInputPlugin.h
FlutterViewIdentifier
int64_t FlutterViewIdentifier
Definition: FlutterViewController.h:21
FlutterWindowController.h
app_lifecycle_state.h
FlutterDartProject
Definition: FlutterDartProject.mm:39
FlutterEngineTerminationHandler
Definition: FlutterEngine.mm:190
FlutterEngineTerminationHandler::shouldTerminate
BOOL shouldTerminate
Definition: FlutterEngine_Internal.h:62
FlutterEngineTerminationHandler::acceptingRequests
BOOL acceptingRequests
Definition: FlutterEngine_Internal.h:63
FlutterPasteboard
Definition: FlutterEngine.mm:288
-[FlutterPasteboard clearContents]
NSInteger clearContents()
Definition: FlutterEngine.mm:290
FlutterEngine
Definition: FlutterEngine.h:32
FlutterKeyboardManager
Definition: FlutterKeyboardManager.h:79
FlutterPlatformViewController
Definition: FlutterPlatformViewController.h:18
FlutterRenderer
Definition: FlutterRenderer.h:19
FlutterTextInputPlugin
Definition: FlutterTextInputPlugin.h:42
FlutterViewController
Definition: FlutterViewController.h:73
FlutterWindowController
Definition: FlutterWindowController.h:16
flutter
Definition: AccessibilityBridgeMac.h:16
flutter::AppLifecycleState
AppLifecycleState
Definition: app_lifecycle_state.h:32