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