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