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