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 
6 
7 #import <Cocoa/Cocoa.h>
8 
9 #include <memory>
10 
12 
17 
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 @interface FlutterEngine ()
70 
71 /**
72  * True if the engine is currently running.
73  */
74 @property(nonatomic, readonly) BOOL running;
75 
76 /**
77  * Provides the renderer config needed to initialize the engine and also handles external
78  * texture management.
79  */
80 @property(nonatomic, readonly, nullable) FlutterRenderer* renderer;
81 
82 /**
83  * Function pointers for interacting with the embedder.h API.
84  */
85 @property(nonatomic) FlutterEngineProcTable& embedderAPI;
86 
87 /**
88  * True if the semantics is enabled. The Flutter framework starts sending
89  * semantics update through the embedder as soon as it is set to YES.
90  */
91 @property(nonatomic) BOOL semanticsEnabled;
92 
93 /**
94  * The executable name for the current process.
95  */
96 @property(nonatomic, readonly, nonnull) NSString* executableName;
97 
98 /**
99  * This just returns the NSPasteboard so that it can be mocked in the tests.
100  */
101 @property(nonatomic, readonly, nonnull) NSPasteboard* pasteboard;
102 
103 /**
104  * The command line arguments array for the engine.
105  */
106 @property(nonatomic, readonly) std::vector<std::string> switches;
107 
108 /**
109  * Provides the |FlutterEngineTerminationHandler| to be used for this engine.
110  */
111 @property(nonatomic, readonly) FlutterEngineTerminationHandler* terminationHandler;
112 
113 /**
114  * Attach a view controller to the engine as its default controller.
115  *
116  * Practically, since FlutterEngine can only be attached with one controller,
117  * the given controller, if successfully attached, will always have the default
118  * view ID kFlutterImplicitViewId.
119  *
120  * The engine holds a weak reference to the attached view controller.
121  *
122  * If the given view controller is already attached to an engine, this call
123  * throws an assertion.
124  */
125 - (void)addViewController:(FlutterViewController*)viewController;
126 
127 /**
128  * Dissociate the given view controller from this engine.
129  *
130  * If the view controller is not associated with this engine, this call throws an
131  * assertion.
132  *
133  * Practically, since FlutterEngine can only be attached with one controller for
134  * now, the given controller must be the current view controller.
135  */
136 - (void)removeViewController:(FlutterViewController*)viewController;
137 
138 /**
139  * The |FlutterViewController| associated with the given view ID, if any.
140  */
141 - (nullable FlutterViewController*)viewControllerForId:(FlutterViewId)viewId;
142 
143 /**
144  * Informs the engine that the specified view controller's window metrics have changed.
145  */
146 - (void)updateWindowMetricsForViewController:(FlutterViewController*)viewController;
147 
148 /**
149  * Dispatches the given pointer event data to engine.
150  */
151 - (void)sendPointerEvent:(const FlutterPointerEvent&)event;
152 
153 /**
154  * Dispatches the given pointer event data to engine.
155  */
156 - (void)sendKeyEvent:(const FlutterKeyEvent&)event
157  callback:(nullable FlutterKeyEventCallback)callback
158  userData:(nullable void*)userData;
159 
160 /**
161  * Registers an external texture with the given id. Returns YES on success.
162  */
163 - (BOOL)registerTextureWithID:(int64_t)textureId;
164 
165 /**
166  * Marks texture with the given id as available. Returns YES on success.
167  */
168 - (BOOL)markTextureFrameAvailable:(int64_t)textureID;
169 
170 /**
171  * Unregisters an external texture with the given id. Returns YES on success.
172  */
173 - (BOOL)unregisterTextureWithID:(int64_t)textureID;
174 
175 - (nonnull FlutterPlatformViewController*)platformViewController;
176 
177 /**
178  * Handles changes to the application state, sending them to the framework.
179  *
180  * @param state One of the lifecycle constants in app_lifecycle_state.h,
181  * corresponding to the Dart enum AppLifecycleState.
182  */
183 - (void)setApplicationState:(flutter::AppLifecycleState)state;
184 
185 // Accessibility API.
186 
187 /**
188  * Dispatches semantics action back to the framework. The semantics must be enabled by calling
189  * the updateSemanticsEnabled before dispatching semantics actions.
190  */
191 - (void)dispatchSemanticsAction:(FlutterSemanticsAction)action
192  toTarget:(uint16_t)target
193  withData:(fml::MallocMapping)data;
194 
195 /**
196  * Handles accessibility events.
197  */
198 - (void)handleAccessibilityEvent:(NSDictionary<NSString*, id>*)annotatedEvent;
199 
200 /**
201  * Announces accessibility messages.
202  */
203 - (void)announceAccessibilityMessage:(NSString*)message
204  withPriority:(NSAccessibilityPriorityLevel)priority;
205 
206 @end
207 
209 - (nonnull FlutterThreadSynchronizer*)testThreadSynchronizer;
210 @end
211 
FlutterEngine(Tests)
Definition: FlutterEngine_Internal.h:208
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:196
NS_ENUM
typedef NS_ENUM(NSInteger, FlutterAppExitType)
Definition: FlutterEngine_Internal.h:32
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)