#include <FlutterViewController.h>

Inheritance diagram for FlutterViewController:

Instance Methods
(instancetype)	- initWithEngine:nibName:bundle:

(instancetype)	- initWithProject:nibName:bundle:

(instancetype)	- initWithProject:initialRoute:nibName:bundle:

(instancetype)	- initWithCoder:

(void)	- setFlutterViewDidRenderCallback:

(NSString *)	- lookupKeyForAsset:

(NSString *)	- lookupKeyForAsset:fromPackage:

(void)	- setInitialRoute:

(void)	- popRoute

(void)	- pushRoute:

(id< FlutterPluginRegistry >)	- pluginRegistry

(BOOL)	- loadDefaultSplashScreenView

(nonnull instancetype)	- initWithProject:

(nonnull instancetype)	- initWithNibName:bundle:

(nonnull instancetype)	- initWithCoder:

(nonnull instancetype)	- initWithEngine:nibName:bundle:

(BOOL)	- attached

(void)	- onPreEngineRestart

(nonnull NSString *)	- lookupKeyForAsset:

(nonnull NSString *)	- lookupKeyForAsset:fromPackage:

(void)	- onAccessibilityStatusChanged:

(std::shared_ptr< flutter::AccessibilityBridgeMac >)	- createAccessibilityBridgeWithEngine:

(nonnull FlutterView *)	- createFlutterViewWithMTLDevice:commandQueue:

Instance Methods inherited from <FlutterTextureRegistry>
(int64_t)	- registerTexture:

(void)	- textureFrameAvailable:

(void)	- unregisterTexture:

Instance Methods inherited from <FlutterPluginRegistry>
(nullable NSObject< FlutterPluginRegistrar > *)	- registrarForPlugin:

(BOOL)	- hasPlugin:

(nullable NSObject *)	- valuePublishedByPlugin:

(nonnull id< FlutterPluginRegistrar >)	- registrarForPlugin:

(nullable NSObject *)	- valuePublishedByPlugin:

Class Methods
(BOOL)	+ isUIAccessibilityIsVoiceOverRunning

Properties
BOOL	displayingFlutterUI

UIView *	splashScreenView

BOOL	viewOpaque

FlutterEngine *	engine

NSObject< FlutterBinaryMessenger > *	binaryMessenger

BOOL	engineAllowHeadlessExecution

FlutterMouseTrackingMode	mouseTrackingMode

FlutterViewIdentifier	viewIdentifier

NSColor *	backgroundColor

Detailed Description

A UIViewController implementation for Flutter views.

Dart execution, channel communication, texture registration, and plugin registration are all handled by FlutterEngine. Calls on this class to those members all proxy through to the FlutterEngine attached FlutterViewController.

A FlutterViewController can be initialized either with an already-running FlutterEngine via the initWithEngine: initializer, or it can be initialized with a FlutterDartProject that will be used to implicitly spin up a new FlutterEngine. Creating a FlutterEngine before showing a FlutterViewController can be used to pre-initialize the Dart VM and to prepare the isolate in order to reduce the latency to the first rendered frame. See https://docs.flutter.dev/development/add-to-app/performance for more details on loading latency.

Holding a FlutterEngine independently of FlutterViewControllers can also be used to not to lose Dart-related state and asynchronous tasks when navigating back and forth between a FlutterViewController and other UIViewControllers.

Controls a view that displays Flutter content and manages input.

A FlutterViewController works with a FlutterEngine. Upon creation, the view controller is always added to an engine, either a given engine, or it implicitly creates an engine and add itself to that engine.

The FlutterEngine assigns each view controller attached to it a unique ID. Each view controller corresponds to a view, and the ID is used by the framework to specify which view to operate.

A FlutterViewController can also be unattached to an engine after it is manually unset from the engine, or transiently during the initialization process. An unattached view controller is invalid. Whether the view controller is attached can be queried using attached (FlutterViewController).

The FlutterViewController strongly references the FlutterEngine, while the engine weakly the view controller. When a FlutterViewController is deallocated, it automatically removes itself from its attached engine. When a FlutterEngine has no FlutterViewControllers attached, it might shut down itself or not depending on its configuration.

Definition at line 57 of file FlutterViewController.h.

Method Documentation

◆ attached

- (BOOL) attached

Return YES if the view controller is attached to an engine.

Definition at line 319 of file FlutterViewController.mm.

                 {
  return _engine != nil;
}

References engine, engine, and viewIdentifier.

◆ createAccessibilityBridgeWithEngine:

- (shared_ptr<) flutter: (nonnull FlutterEngine *) engine

Reimplemented in AccessibilityBridgeTestViewController.

Provided by category FlutterViewController(TestMethods).

◆ createFlutterViewWithMTLDevice:commandQueue:

- (nonnull FlutterView *) createFlutterViewWithMTLDevice:	(nonnull id< MTLDevice >)	device
commandQueue:	(nonnull id< MTLCommandQueue >)	commandQueue

Provided by category FlutterViewController(TestMethods).

◆ initWithCoder: [1/2]

- (nonnull instancetype) initWithCoder: (nonnull NSCoder *) NS_DESIGNATED_INITIALIZER

◆ initWithCoder: [2/2]

- (instancetype) initWithCoder: (NSCoder*) NS_DESIGNATED_INITIALIZER

Initializer that is called from loading a FlutterViewController from a XIB.

Definition at line 166 of file FlutterViewController.mm.

                             :(NSCoder*)aDecoder {
  self = [super initWithCoder:aDecoder];
  return self;
}

◆ initWithEngine:nibName:bundle: [1/2]

- (instancetype) initWithEngine:	(FlutterEngine*)	engine
nibName:	(nullable NSString*)	nibName
bundle:	(nullable NSBundle*)	NS_DESIGNATED_INITIALIZER

Initializes this FlutterViewController with the specified FlutterEngine.

The initialized viewcontroller will attach itself to the engine as part of this process.

Parameters

engine	The `FlutterEngine` instance to attach to. Cannot be nil.
nibName	The NIB name to initialize this UIViewController with.
nibBundle	The NIB bundle.

Definition at line 166 of file FlutterViewController.mm.

                              :(FlutterEngine*)engine
                       nibName:(nullable NSString*)nibName
                        bundle:(nullable NSBundle*)nibBundle {
  FML_CHECK(engine) << "initWithEngine:nibName:bundle: must be called with non-nil engine";
  self = [super initWithNibName:nibName bundle:nibBundle];
  if (self) {
    _viewOpaque = YES;
    if (engine.viewController) {
      NSString* errorMessage =
          [NSString stringWithFormat:
                        @"The supplied FlutterEngine %@ is already used with FlutterViewController "
                         "instance %@. One instance of the FlutterEngine can only be attached to "
                         "one FlutterViewController at a time. Set FlutterEngine.viewController to "
                         "nil before attaching it to another FlutterViewController.",
                        engine.description, engine.viewController.description];
      [FlutterLogger logError:errorMessage];
    }
    _engine = engine;
    _engineNeedsLaunch = NO;
    _flutterView = [[FlutterView alloc] initWithDelegate:_engine
                                                  opaque:self.isViewOpaque
                                         enableWideGamut:engine.project.isWideGamutEnabled];
    _ongoingTouches = [[NSMutableSet alloc] init];
 
    // TODO(cbracken): https://github.com/flutter/flutter/issues/157140
    // Eliminate method calls in initializers and dealloc.
    [self performCommonViewControllerInitialization];
    [engine setViewController:self];
  }
 
  return self;
}

◆ initWithEngine:nibName:bundle: [2/2]

- (instancetype) initWithEngine:	(nonnull FlutterEngine*)	engine
nibName:	(nullable NSString*)	nibName
bundle:	(nullable NSBundle*)	NS_DESIGNATED_INITIALIZER

Initializes this FlutterViewController with an existing FlutterEngine.

The initialized view controller will add itself to the engine as part of this process.

This initializer is suitable for both the first Flutter view controller and the following ones of the app.

Parameters

engine	The `FlutterEngine` instance to attach to. Cannot be nil.
nibName	The NIB name to initialize this controller with.
nibBundle	The NIB bundle.

Definition at line 319 of file FlutterViewController.mm.

                              :(nonnull FlutterEngine*)engine
                       nibName:(nullable NSString*)nibName
                        bundle:(nullable NSBundle*)nibBundle {
  NSAssert(engine != nil, @"Engine is required");
 
  self = [super initWithNibName:nibName bundle:nibBundle];
  if (self) {
    CommonInit(self, engine);
  }
 
  return self;
}

◆ initWithNibName:bundle:

- (nonnull instancetype) initWithNibName:	(nullable NSString *)	nibNameOrNil
bundle:	(nullable NSBundle *)	NS_DESIGNATED_INITIALIZER

◆ initWithProject:

- (instancetype) initWithProject: (nullable FlutterDartProject*) NS_DESIGNATED_INITIALIZER

Initializes a controller that will run the given project.

In this initializer, this controller creates an engine, and is attached to that engine as the default controller. In this way, this controller can not be set to other engines. This initializer is suitable for the first Flutter view controller of the app. To use the controller with an existing engine, use initWithEngine:nibName:bundle: instead.

Parameters

project The project to run in this view controller. If nil, a default FlutterDartProject will be used.

Definition at line 319 of file FlutterViewController.mm.

                               :(nullable FlutterDartProject*)project {
  self = [super initWithNibName:nil bundle:nil];
  NSAssert(self, @"Super init cannot be nil");
 
  _project = project;
  CommonInit(self, nil);
  return self;
}

◆ initWithProject:initialRoute:nibName:bundle:

- (instancetype) initWithProject:	(nullable FlutterDartProject *)	project
initialRoute:	(nullable NSString *)	initialRoute
nibName:	(nullable NSString *)	nibName
bundle:	(nullable NSBundle *)	NS_DESIGNATED_INITIALIZER

Initializes a new FlutterViewController and FlutterEngine with the specified FlutterDartProject and initialRoute.

This will implicitly create a new FlutterEngine which is retrievable via the engine property after initialization.

Parameters

project	The `FlutterDartProject` to initialize the `FlutterEngine` with.
initialRoute	The initial `Navigator` route to load.
nibName	The NIB name to initialize this UIViewController with.
nibBundle	The NIB bundle.

◆ initWithProject:nibName:bundle:

- (instancetype) initWithProject:	(nullable FlutterDartProject *)	project
nibName:	(nullable NSString *)	nibName
bundle:	(nullable NSBundle *)	NS_DESIGNATED_INITIALIZER

Initializes a new FlutterViewController and FlutterEngine with the specified FlutterDartProject.

This will implicitly create a new FlutterEngine which is retrievable via the engine property after initialization.

Parameters

project	The `FlutterDartProject` to initialize the `FlutterEngine` with.
nibName	The NIB name to initialize this UIViewController with.
nibBundle	The NIB bundle.

◆ isUIAccessibilityIsVoiceOverRunning

+ (BOOL) isUIAccessibilityIsVoiceOverRunning

A wrapper around UIAccessibilityIsVoiceOverRunning().

As a C function, UIAccessibilityIsVoiceOverRunning() cannot be mocked in testing. Mock this class method to testing features depends on UIAccessibilityIsVoiceOverRunning().

Definition at line 1179 of file FlutterViewController.mm.

                                            {
  return UIAccessibilityIsVoiceOverRunning();
}

References FML_DLOG, flutter::PointerData::kMouse, flutter::PointerData::kStylus, and flutter::PointerData::kTouch.

◆ loadDefaultSplashScreenView

- (BOOL) loadDefaultSplashScreenView

Attempts to set the splashScreenView property from the UILaunchStoryboardName from the main bundle's Info.plist file. This method will not change the value of splashScreenView if it cannot find a default one from a storyboard or nib.

Returns: YES if successful, NO otherwise.

Definition at line 585 of file FlutterViewController.mm.

                                    {
  NSString* launchscreenName =
      [[[NSBundle mainBundle] infoDictionary] objectForKey:@"UILaunchStoryboardName"];
  if (launchscreenName == nil) {
    return NO;
  }
  UIView* splashView = [self splashScreenFromStoryboard:launchscreenName];
  if (!splashView) {
    splashView = [self splashScreenFromXib:launchscreenName];
  }
  if (!splashView) {
    return NO;
  }
  self.splashScreenView = splashView;
  return YES;
}

References flutter::PointerData::change, flutter::PointerData::physical_x, flutter::PointerData::physical_y, flutter::PointerData::scale, and FlutterEngine::viewController.

◆ lookupKeyForAsset: [1/2]

- (nonnull NSString *) lookupKeyForAsset: (nonnull NSString *) asset

Returns the file name for the given asset. The returned file name can be used to access the asset in the application's main bundle.

Parameters

asset The name of the asset. The name can be hierarchical.

Returns: The file name to be used for lookup in the main bundle.

◆ lookupKeyForAsset: [2/2]

- (NSString *) lookupKeyForAsset: (NSString*) asset

Returns the file name for the given asset. The returned file name can be used to access the asset in the application's main bundle.

Parameters

asset The name of the asset. The name can be hierarchical.

Returns: The file name to be used for lookup in the main bundle.

Definition at line 1179 of file FlutterViewController.mm.

                              :(NSString*)asset {
  return [FlutterDartProject lookupKeyForAsset:asset];
}

◆ lookupKeyForAsset:fromPackage: [1/2]

- (nonnull NSString *) lookupKeyForAsset:	(nonnull NSString *)	asset
fromPackage:	(nonnull NSString *)	package

Returns the file name for the given asset which originates from the specified package. The returned file name can be used to access the asset in the application's main bundle.

Parameters

asset	The name of the asset. The name can be hierarchical.
package	The name of the package from which the asset originates.

Returns: The file name to be used for lookup in the main bundle.

◆ lookupKeyForAsset:fromPackage: [2/2]

- (NSString *) lookupKeyForAsset:	(NSString*)	asset
fromPackage:	(NSString*)	package

Returns the file name for the given asset which originates from the specified package. The returned file name can be used to access the asset in the application's main bundle.

Parameters

asset	The name of the asset. The name can be hierarchical.
package	The name of the package from which the asset originates.

Returns: The file name to be used for lookup in the main bundle.

Definition at line 1179 of file FlutterViewController.mm.

                              :(NSString*)asset fromPackage:(NSString*)package {
  return [FlutterDartProject lookupKeyForAsset:asset fromPackage:package];
}

◆ onAccessibilityStatusChanged:

- (void) onAccessibilityStatusChanged: (BOOL) enabled

Provided by category FlutterViewController(TestMethods).

◆ onPreEngineRestart

- (void) onPreEngineRestart

Invoked by the engine right before the engine is restarted.

This should reset states to as if the application has just started. It usually indicates a hot restart (Shift-R in Flutter CLI.)

Definition at line 319 of file FlutterViewController.mm.

453 {

454}

◆ pluginRegistry

- (id< FlutterPluginRegistry >) pluginRegistry

The FlutterPluginRegistry used by this FlutterViewController.

Definition at line 1179 of file FlutterViewController.mm.

                                            {
  return self.engine;
}

◆ popRoute

- (void) popRoute

Instructs the Flutter Navigator (if any) to go back.

Definition at line 166 of file FlutterViewController.mm.

                 {
  [self.engine.navigationChannel invokeMethod:@"popRoute" arguments:nil];
}

◆ pushRoute:

- (void) pushRoute: (NSString*) route

Instructs the Flutter Navigator (if any) to push a route on to the navigation stack.

Parameters

route The name of the route to push to the navigation stack.

Definition at line 166 of file FlutterViewController.mm.

                 :(NSString*)route {
  [self.engine.navigationChannel invokeMethod:@"pushRoute" arguments:route];
}

◆ setFlutterViewDidRenderCallback:

- (void) setFlutterViewDidRenderCallback: (void(^)(void)) callback

Registers a callback that will be invoked when the Flutter view has been rendered. The callback will be fired only once.

Replaces an existing callback. Use a nil callback to unregister the existing one.

Definition at line 585 of file FlutterViewController.mm.

                                       :(void (^)(void))callback {
  _flutterViewRenderedCallback = callback;
}

◆ setInitialRoute:

- (void) setInitialRoute: ("Use FlutterViewController initializer to specify initial route") FLUTTER_DEPRECATED

Deprecated API to set initial route.

Attempts to set the first route that the Flutter app shows if the Flutter runtime hasn't yet started. The default is "/".

This method must be called immediately after initWithProject and has no effect when using initWithEngine if the FlutterEngine has already been run.

Setting this after the Flutter started running has no effect. See pushRoute and popRoute to change the route after Flutter started running.

This is deprecated because it needs to be called at the time of initialization and thus should just be in the initWithProject initializer. If using initWithEngine, the initial route should be set on the engine's initializer.

Parameters

route The name of the first route to show.

Property Documentation

◆ backgroundColor

- (NSColor*) backgroundColor

readwritenonatomiccopy

The contentView (FlutterView)'s background color is set to black during its instantiation.

The containing layer's color can be set to the NSColor provided to this method.

For example, the background may be set after the FlutterViewController is instantiated in MainFlutterWindow.swift in the Flutter project.

import Cocoa
import FlutterMacOS
 
class MainFlutterWindow: NSWindow {
  override func awakeFromNib() {
    let flutterViewController = FlutterViewController()
 
    // The background color of the window and `FlutterViewController`
    // are retained separately.
    //
    // In this example, both the MainFlutterWindow and FlutterViewController's
    // FlutterView's backgroundColor are set to clear to achieve a fully
    // transparent effect.
    //
    // If the window's background color is not set, it will use the system
    // default.
    //
    // If the `FlutterView`'s color is not set via `FlutterViewController.setBackgroundColor`
    // it's default will be black.
    self.backgroundColor = NSColor.clear
    flutterViewController.backgroundColor = NSColor.clear
 
    let windowFrame = self.frame
    self.contentViewController = flutterViewController
    self.setFrame(windowFrame, display: true)
 
    RegisterGeneratedPlugins(registry: flutterViewController)
 
    super.awakeFromNib()
  }
}

Definition at line 210 of file FlutterViewController.h.

Referenced by flutter::testing::TEST_F().

◆ binaryMessenger

- (NSObject< FlutterBinaryMessenger > *) binaryMessenger

readnonatomicassign

The FlutterBinaryMessenger associated with this FlutterViewController (used for communicating with channels).

This is just a convenient way to get the |FlutterEngine|'s binary messenger.

Definition at line 244 of file FlutterViewController.h.

◆ displayingFlutterUI

- (BOOL) displayingFlutterUI

readnonatomicassign

True if at least one frame has rendered and the ViewController has appeared.

This property is reset to false when the ViewController disappears. It is guaranteed to only alternate between true and false for observers.

Definition at line 198 of file FlutterViewController.h.

◆ engine

- (FlutterEngine *) engine

readnonatomicassign

The FlutterEngine instance for this view controller. This could be the engine this FlutterViewController is initialized with or a new FlutterEngine implicitly created if no engine was supplied during initialization.

The Flutter engine associated with this view controller.

Definition at line 236 of file FlutterViewController.h.

Referenced by attached, flutter::testing::TEST(), flutter::testing::TEST(), flutter::testing::TEST(), flutter::testing::TEST(), flutter::testing::TEST(), flutter::testing::TEST(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), and flutter::testing::TEST_F().

◆ engineAllowHeadlessExecution

- (BOOL) engineAllowHeadlessExecution

readnonatomicassign

If the FlutterViewController creates a FlutterEngine, this property determines if that FlutterEngine has allowHeadlessExecution set.

The intention is that this is used with the XIB. Otherwise, a FlutterEngine can just be sent to the init methods.

See also: -[FlutterEngine initWithName:project:allowHeadlessExecution:]

Definition at line 255 of file FlutterViewController.h.

◆ mouseTrackingMode

- (FlutterMouseTrackingMode) mouseTrackingMode

readwritenonatomicassign

The style of mouse tracking to use for the view. Defaults to FlutterMouseTrackingModeInKeyWindow.

Definition at line 84 of file FlutterViewController.h.

Referenced by flutter::testing::TEST_F().

◆ splashScreenView

- (UIView*) splashScreenView

readwritenonatomicstrong

Specifies the view to use as a splash screen. Flutter's rendering is asynchronous, so the first frame rendered by the Flutter application might not immediately appear when the Flutter view is initially placed in the view hierarchy. The splash screen view will be used as a replacement until the first frame is rendered.

The view used should be appropriate for multiple sizes; an autoresizing mask to have a flexible width and height will be applied automatically.

Set to nil to remove the splash screen view.

Definition at line 211 of file FlutterViewController.h.

◆ viewIdentifier

- (FlutterViewIdentifier) viewIdentifier

readnonatomicassign

The identifier for this view controller, if it is attached.

The identifier is assigned when the view controller is attached to a FlutterEngine.

If the view controller is detached (see FlutterViewController#attached), reading this property throws an assertion.

Definition at line 130 of file FlutterViewController.h.

Referenced by attached.

◆ viewOpaque

- (BOOL) viewOpaque

readwritenonatomicassign

Controls whether the created view will be opaque or not.

Default is YES. Note that setting this to NO may negatively impact performance when using hardware acceleration, and toggling this will trigger a re-layout of the view.

Definition at line 229 of file FlutterViewController.h.

The documentation for this class was generated from the following files:

shell/platform/darwin/ios/framework/Headers/FlutterViewController.h
shell/platform/darwin/macos/framework/Headers/FlutterViewController.h
shell/platform/darwin/ios/framework/Source/FlutterViewController.mm
shell/platform/darwin/macos/framework/Source/FlutterViewController.mm

Instance Methods

Class Methods

Properties

Detailed Description

Method Documentation

◆ attached

◆ createAccessibilityBridgeWithEngine:

◆ createFlutterViewWithMTLDevice:commandQueue:

◆ initWithCoder: [1/2]

◆ initWithCoder: [2/2]

◆ initWithEngine:nibName:bundle: [1/2]

◆ initWithEngine:nibName:bundle: [2/2]

◆ initWithNibName:bundle:

◆ initWithProject:

◆ initWithProject:initialRoute:nibName:bundle:

◆ initWithProject:nibName:bundle:

◆ isUIAccessibilityIsVoiceOverRunning

◆ loadDefaultSplashScreenView

◆ lookupKeyForAsset: [1/2]

◆ lookupKeyForAsset: [2/2]

◆ lookupKeyForAsset:fromPackage: [1/2]

◆ lookupKeyForAsset:fromPackage: [2/2]

◆ onAccessibilityStatusChanged:

◆ onPreEngineRestart

◆ pluginRegistry

◆ popRoute

◆ pushRoute:

◆ setFlutterViewDidRenderCallback:

◆ setInitialRoute:

Property Documentation

◆ backgroundColor

◆ binaryMessenger

◆ displayingFlutterUI

◆ engine

◆ engineAllowHeadlessExecution

◆ mouseTrackingMode

◆ splashScreenView

◆ viewIdentifier

◆ viewOpaque