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