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