| Flutter macOS Embedder |

FlutterViewController.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_HEADERS_FLUTTERVIEWCONTROLLER_H_
6 #define FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_HEADERS_FLUTTERVIEWCONTROLLER_H_
7
8 #import <Cocoa/Cocoa.h>
9
10 #import "FlutterEngine.h"
11 #import "FlutterMacros.h"
12 #import "FlutterPlatformViews.h"
13 #import "FlutterPluginRegistrarMacOS.h"
14
15 /**
16 * A unique identifier for a view within which Flutter content is hosted.
17 *
18 * Identifiers are guaranteed to be unique for views owned by a given engine but
19 * may collide for views owned by different engines.
20 */
21 typedef int64_t FlutterViewIdentifier;
22
23 /**
24 * Values for the `mouseTrackingMode` property.
25 */
26 typedef NS_ENUM(NSInteger, FlutterMouseTrackingMode) {
27 // Hover events will never be sent to Flutter.
28 kFlutterMouseTrackingModeNone = 0,
29 // NOLINTNEXTLINE(readability-identifier-naming)
30 FlutterMouseTrackingModeNone __attribute__((deprecated)) = kFlutterMouseTrackingModeNone,
31
32 // Hover events will be sent to Flutter when the view is in the key window.
33 kFlutterMouseTrackingModeInKeyWindow = 1,
34 // NOLINTNEXTLINE(readability-identifier-naming)
35 FlutterMouseTrackingModeInKeyWindow
36 __attribute__((deprecated)) = kFlutterMouseTrackingModeInKeyWindow,
37
38 // Hover events will be sent to Flutter when the view is in the active app.
39 kFlutterMouseTrackingModeInActiveApp = 2,
40 // NOLINTNEXTLINE(readability-identifier-naming)
41 FlutterMouseTrackingModeInActiveApp
42 __attribute__((deprecated)) = kFlutterMouseTrackingModeInActiveApp,
43
44 // Hover events will be sent to Flutter regardless of window and app focus.
45 kFlutterMouseTrackingModeAlways = 3,
46 // NOLINTNEXTLINE(readability-identifier-naming)
47 FlutterMouseTrackingModeAlways __attribute__((deprecated)) = kFlutterMouseTrackingModeAlways,
48 };
49
50 /**
51 * Controls a view that displays Flutter content and manages input.
52 *
53 * A FlutterViewController works with a FlutterEngine. Upon creation, the view
54 * controller is always added to an engine, either a given engine, or it implicitly
55 * creates an engine and add itself to that engine.
56 *
57 * The FlutterEngine assigns each view controller attached to it a unique ID.
58 * Each view controller corresponds to a view, and the ID is used by the framework
59 * to specify which view to operate.
60 *
61 * A FlutterViewController can also be unattached to an engine after it is manually
62 * unset from the engine, or transiently during the initialization process.
63 * An unattached view controller is invalid. Whether the view controller is attached
64 * can be queried using FlutterViewController#attached.
65 *
66 * The FlutterViewController strongly references the FlutterEngine, while
67 * the engine weakly the view controller. When a FlutterViewController is deallocated,
68 * it automatically removes itself from its attached engine. When a FlutterEngine
69 * has no FlutterViewControllers attached, it might shut down itself or not depending
70 * on its configuration.
71 */
72 FLUTTER_DARWIN_EXPORT
73 @interface FlutterViewController : NSViewController <FlutterPluginRegistry>
74
75 /**
76 * The Flutter engine associated with this view controller.
77 */
78 @property(nonatomic, nonnull, readonly) FlutterEngine* engine;
79
80 /**
81 * The style of mouse tracking to use for the view. Defaults to
82 * FlutterMouseTrackingModeInKeyWindow.
83 */
84 @property(nonatomic) FlutterMouseTrackingMode mouseTrackingMode;
85
86 /**
87 * Initializes a controller that will run the given project.
88 *
89 * In this initializer, this controller creates an engine, and is attached to
90 * that engine as the default controller. In this way, this controller can not
91 * be set to other engines. This initializer is suitable for the first Flutter
92 * view controller of the app. To use the controller with an existing engine,
93 * use initWithEngine:nibName:bundle: instead.
94 *
95 * @param project The project to run in this view controller. If nil, a default `FlutterDartProject`
96 * will be used.
97 */
98 - (nonnull instancetype)initWithProject:(nullable FlutterDartProject*)project
99 NS_DESIGNATED_INITIALIZER;
100
101 - (nonnull instancetype)initWithNibName:(nullable NSString*)nibNameOrNil
102 bundle:(nullable NSBundle*)nibBundleOrNil
103 NS_DESIGNATED_INITIALIZER;
104 - (nonnull instancetype)initWithCoder:(nonnull NSCoder*)nibNameOrNil NS_DESIGNATED_INITIALIZER;
105 /**
106 * Initializes this FlutterViewController with an existing `FlutterEngine`.
107 *
108 * The initialized view controller will add itself to the engine as part of this process.
109 *
110 * This initializer is suitable for both the first Flutter view controller and
111 * the following ones of the app.
112 *
113 * @param engine The `FlutterEngine` instance to attach to. Cannot be nil.
114 * @param nibName The NIB name to initialize this controller with.
115 * @param nibBundle The NIB bundle.
116 */
117 - (nonnull instancetype)initWithEngine:(nonnull FlutterEngine*)engine
118 nibName:(nullable NSString*)nibName
119 bundle:(nullable NSBundle*)nibBundle NS_DESIGNATED_INITIALIZER;
120
121 /**
122 * The identifier for this view controller, if it is attached.
123 *
124 * The identifier is assigned when the view controller is attached to a
125 * `FlutterEngine`.
126 *
127 * If the view controller is detached (see `FlutterViewController#attached`),
128 * reading this property throws an assertion.
129 */
130 @property(nonatomic, readonly) FlutterViewIdentifier viewIdentifier;
131
132 /**
133 * Return YES if the view controller is attached to an engine.
134 */
135 - (BOOL)attached;
136
137 /**
138 * Invoked by the engine right before the engine is restarted.
139 *
140 * This should reset states to as if the application has just started. It
141 * usually indicates a hot restart (Shift-R in Flutter CLI.)
142 */
143 - (void)onPreEngineRestart;
144
145 /**
146 * Returns the file name for the given asset.
147 * The returned file name can be used to access the asset in the application's
148 * main bundle.
149 *
150 * @param asset The name of the asset. The name can be hierarchical.
151 * @return The file name to be used for lookup in the main bundle.
152 */
153 - (nonnull NSString*)lookupKeyForAsset:(nonnull NSString*)asset;
154
155 /**
156 * Returns the file name for the given asset which originates from the specified
157 * package.
158 * The returned file name can be used to access the asset in the application's
159 * main bundle.
160 *
161 * @param asset The name of the asset. The name can be hierarchical.
162 * @param package The name of the package from which the asset originates.
163 * @return The file name to be used for lookup in the main bundle.
164 */
165 - (nonnull NSString*)lookupKeyForAsset:(nonnull NSString*)asset
166 fromPackage:(nonnull NSString*)package;
167
168 /**
169 * The contentView (FlutterView)'s background color is set to black during
170 * its instantiation.
171 *
172 * The containing layer's color can be set to the NSColor provided to this method.
173 *
174 * For example, the background may be set after the FlutterViewController
175 * is instantiated in MainFlutterWindow.swift in the Flutter project.
176 * ```swift
177 * import Cocoa
178 * import FlutterMacOS
179 *
180 * class MainFlutterWindow: NSWindow {
181 * override func awakeFromNib() {
182 * let flutterViewController = FlutterViewController()
183 *
184 * // The background color of the window and `FlutterViewController`
185 * // are retained separately.
186 * //
187 * // In this example, both the MainFlutterWindow and FlutterViewController's
188 * // FlutterView's backgroundColor are set to clear to achieve a fully
189 * // transparent effect.
190 * //
191 * // If the window's background color is not set, it will use the system
192 * // default.
193 * //
194 * // If the `FlutterView`'s color is not set via `FlutterViewController.setBackgroundColor`
195 * // it's default will be black.
196 * self.backgroundColor = NSColor.clear
197 * flutterViewController.backgroundColor = NSColor.clear
198 *
199 * let windowFrame = self.frame
200 * self.contentViewController = flutterViewController
201 * self.setFrame(windowFrame, display: true)
202 *
203 * RegisterGeneratedPlugins(registry: flutterViewController)
204 *
205 * super.awakeFromNib()
206 * }
207 * }
208 * ```
209 */
210 @property(readwrite, nonatomic, nullable, copy) NSColor* backgroundColor;
211
212 @end
213
214 #endif // FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_HEADERS_FLUTTERVIEWCONTROLLER_H_
FlutterEngine.h
FlutterMacros.h
FLUTTER_DARWIN_EXPORT
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
FlutterPlatformViews.h
FlutterPluginRegistrarMacOS.h
FlutterViewIdentifier
int64_t FlutterViewIdentifier
Definition: FlutterViewController.h:21
NS_ENUM
typedef NS_ENUM(NSInteger, FlutterMouseTrackingMode)
Definition: FlutterViewController.h:26
FlutterDartProject
Definition: FlutterDartProject.mm:39
FlutterEngine
Definition: FlutterEngine.h:32
FlutterViewController
Definition: FlutterViewController.h:73
-[FlutterViewController onPreEngineRestart]
void onPreEngineRestart()
Definition: FlutterViewController.mm:455
FlutterViewController::backgroundColor
NSColor * backgroundColor
Definition: FlutterViewController.h:210
FlutterViewController::engine
FlutterEngine * engine
Definition: FlutterViewController.h:78
FlutterViewController::mouseTrackingMode
FlutterMouseTrackingMode mouseTrackingMode
Definition: FlutterViewController.h:84
-[FlutterViewController attached]
BOOL attached()
Definition: FlutterViewController.mm:490
FlutterViewController::viewIdentifier
FlutterViewIdentifier viewIdentifier
Definition: FlutterViewController.h:130
FlutterPluginRegistry-p
Definition: FlutterPluginRegistrarMacOS.h:143