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"
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  */
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_
-[FlutterViewController attached]
BOOL attached()
Definition: FlutterViewController.mm:517
FlutterEngine
Definition: FlutterEngine.h:30
FlutterPlatformViews.h
FlutterViewController
Definition: FlutterViewController.h:73
FlutterEngine.h
FlutterPluginRegistry-p
Definition: FlutterPluginRegistrarMacOS.h:130
FlutterViewController::engine
FlutterEngine * engine
Definition: FlutterViewController.h:78
FlutterMacros.h
FlutterPluginRegistrarMacOS.h
-[FlutterViewController onPreEngineRestart]
void onPreEngineRestart()
Definition: FlutterViewController.mm:476
FlutterViewController::backgroundColor
NSColor * backgroundColor
Definition: FlutterViewController.h:210
NS_ENUM
typedef NS_ENUM(NSInteger, FlutterMouseTrackingMode)
Definition: FlutterViewController.h:26
FlutterViewController::viewIdentifier
FlutterViewIdentifier viewIdentifier
Definition: FlutterViewController.h:130
FLUTTER_DARWIN_EXPORT
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
FlutterDartProject
Definition: FlutterDartProject.mm:24
FlutterViewIdentifier
int64_t FlutterViewIdentifier
Definition: FlutterViewController.h:21
FlutterViewController::mouseTrackingMode
FlutterMouseTrackingMode mouseTrackingMode
Definition: FlutterViewController.h:84