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 
9 
10 #import <Cocoa/Cocoa.h>
11 
12 #include <memory>
13 
15 
19 
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 
228 - (nonnull FlutterThreadSynchronizer*)testThreadSynchronizer;
229 @end
230 
232 
233 #endif // FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_SOURCE_FLUTTERENGINE_INTERNAL_H_
FlutterPasteboard
Definition: FlutterEngine.mm:286
FlutterEngine(Tests)
Definition: FlutterEngine_Internal.h:227
FlutterEngine
Definition: FlutterEngine.h:30
FlutterViewController
Definition: FlutterViewController.h:73
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:59
AccessibilityBridgeMac.h
app_lifecycle_state.h
FlutterRenderer
Definition: FlutterRenderer.h:18
FlutterThreadSynchronizer
Definition: FlutterThreadSynchronizer.h:18
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:34
-[FlutterPasteboard clearContents]
NSInteger clearContents()
Definition: FlutterEngine.mm:288
flutter::AppLifecycleState
AppLifecycleState
Definition: app_lifecycle_state.h:32
FlutterEngineTerminationHandler::acceptingRequests
BOOL acceptingRequests
Definition: FlutterEngine_Internal.h:60
FlutterEngineTerminationHandler
Definition: FlutterEngine.mm:188
FlutterViewIdentifier
int64_t FlutterViewIdentifier
Definition: FlutterViewController.h:21
FlutterTerminationCallback
NS_ASSUME_NONNULL_BEGIN typedef void(^ FlutterTerminationCallback)(id _Nullable sender)