| 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 * 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
273 NS_ASSUME_NONNULL_END
274
275 #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
FlutterEngineTerminationHandler
Definition: FlutterEngine.mm:194
FlutterEngineTerminationHandler::shouldTerminate
BOOL shouldTerminate
Definition: FlutterEngine_Internal.h:62
FlutterEngineTerminationHandler::acceptingRequests
BOOL acceptingRequests
Definition: FlutterEngine_Internal.h:63
FlutterPasteboard
Definition: FlutterEngine.mm:292
-[FlutterPasteboard clearContents]
NSInteger clearContents()
Definition: FlutterEngine.mm:294
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