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