Flutter Engine
FlutterViewController Class Reference

#import <FlutterViewController.h>

Inheritance diagram for FlutterViewController:
NoStatusBarFlutterViewController

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:
 

Properties

BOOL displayingFlutterUI
 
UIView * splashScreenView
 
BOOL viewOpaque
 
FlutterEngineengine
 
NSObject< FlutterBinaryMessenger > * binaryMessenger
 
BOOL engineAllowHeadlessExecution
 
FlutterMouseTrackingMode mouseTrackingMode
 

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://flutter.dev/docs/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.

Definition at line 51 of file FlutterViewController.h.

Method Documentation

◆ initWithCoder:() [1/2]

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

◆ initWithCoder:() [2/2]

- (instancetype) initWithCoder: (NSCoder*)  NS_DESIGNATED_INITIALIZER

◆ initWithEngine:nibName:bundle:()

- (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
engineThe FlutterEngine instance to attach to. Cannot be nil.
nibNameThe NIB name to initialize this UIViewController with.
nibBundleThe NIB bundle.

Definition at line 87 of file FlutterViewController.mm.

References _engine, _engineNeedsLaunch, _flutterView, _ongoingTouches, _viewOpaque, _weakFactory, FML_LOG, initWithProject:nibName:bundle:, and FlutterEngine::viewController.

87  :(FlutterEngine*)engine
88  nibName:(nullable NSString*)nibName
89  bundle:(nullable NSBundle*)nibBundle {
90  NSAssert(engine != nil, @"Engine is required");
91  self = [super initWithNibName:nibName bundle:nibBundle];
92  if (self) {
93  _viewOpaque = YES;
94  if (engine.viewController) {
95  FML_LOG(ERROR) << "The supplied FlutterEngine " << [[engine description] UTF8String]
96  << " is already used with FlutterViewController instance "
97  << [[engine.viewController description] UTF8String]
98  << ". One instance of the FlutterEngine can only be attached to one "
99  "FlutterViewController at a time. Set FlutterEngine.viewController "
100  "to nil before attaching it to another FlutterViewController.";
101  }
102  _engine.reset([engine retain]);
103  _engineNeedsLaunch = NO;
104  _flutterView.reset([[FlutterView alloc] initWithDelegate:_engine opaque:self.isViewOpaque]);
105  _weakFactory = std::make_unique<fml::WeakPtrFactory<FlutterViewController>>(self);
106  _ongoingTouches.reset([[NSMutableSet alloc] init]);
107 
108  [self performCommonViewControllerInitialization];
109  [engine setViewController:self];
110  }
111 
112  return self;
113 }
std::unique_ptr< fml::WeakPtrFactory< FlutterEngine > > _weakFactory
fml::scoped_nsobject< FlutterView > _flutterView
#define FML_LOG(severity)
Definition: logging.h:65
BOOL _engineNeedsLaunch
fml::scoped_nsobject< FlutterEngine > _engine
fml::scoped_nsobject< NSMutableSet< NSNumber * > > _ongoingTouches
BOOL _viewOpaque
FlutterViewController * viewController

◆ initWithNibName:bundle:()

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

◆ initWithProject:()

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

◆ 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
projectThe FlutterDartProject to initialize the FlutterEngine with.
initialRouteThe initial Navigator route to load.
nibNameThe NIB name to initialize this UIViewController with.
nibBundleThe 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
projectThe FlutterDartProject to initialize the FlutterEngine with.
nibNameThe NIB name to initialize this UIViewController with.
nibBundleThe NIB bundle.

Referenced by initWithCoder:, and initWithEngine:nibName:bundle:.

◆ 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 508 of file FlutterViewController.mm.

References _splashScreenView, fml::scoped_nsprotocol< NST >::get(), name, and fml::scoped_nsprotocol< NST >::reset().

Referenced by initWithCoder:.

508  {
509  NSString* launchscreenName =
510  [[[NSBundle mainBundle] infoDictionary] objectForKey:@"UILaunchStoryboardName"];
511  if (launchscreenName == nil) {
512  return NO;
513  }
514  UIView* splashView = [self splashScreenFromStoryboard:launchscreenName];
515  if (!splashView) {
516  splashView = [self splashScreenFromXib:launchscreenName];
517  }
518  if (!splashView) {
519  return NO;
520  }
521  self.splashScreenView = splashView;
522  return YES;
523 }

◆ lookupKeyForAsset:()

- (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
assetThe 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 1382 of file FlutterViewController.mm.

References FlutterDartProject::lookupKeyForAsset:.

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

◆ lookupKeyForAsset:fromPackage:()

- (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
assetThe name of the asset. The name can be hierarchical.
packageThe 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 1386 of file FlutterViewController.mm.

References FlutterDartProject::lookupKeyForAsset:fromPackage:.

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

◆ pluginRegistry()

- (id< FlutterPluginRegistry >) pluginRegistry

The FlutterPluginRegistry used by this FlutterViewController.

Definition at line 1390 of file FlutterViewController.mm.

References _engine.

1390  {
1391  return _engine;
1392 }
fml::scoped_nsobject< FlutterEngine > _engine

◆ popRoute()

- (void) popRoute

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

Definition at line 317 of file FlutterViewController.mm.

317  {
318  [[_engine.get() navigationChannel] invokeMethod:@"popRoute" arguments:nil];
319 }

◆ pushRoute:()

- (void) pushRoute: (NSString*)  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 567 of file FlutterViewController.mm.

References _engine, _engineNeedsLaunch, _flutterView, _flutterViewRenderedCallback, _ongoingTouches, _orientationPreferences, _scrollView, _statusBarStyle, _viewportMetrics, flutter::PointerData::change, flutter::PointerData::Clear(), fml::Status::code(), flutter::PointerData::device, flutter::ViewportMetrics::device_pixel_ratio, event, flutter::flags, FlutterBinaryReply, FML_DLOG, FML_LOG, fml::TimeDelta::FromMilliseconds(), flutter::kAccessibleNavigation, flutter::PointerData::kAdd, flutter::kBoldText, flutter::PointerData::kCancel, fml::kDeadlineExceeded, flutter::PointerData::kDown, flutter::kHighContrast, flutter::PointerData::kHover, flutter::PointerData::kind, flutter::kInvertColors, kMicrosecondsPerSecond, flutter::PointerData::kMove, flutter::kReduceMotion, flutter::PointerData::kRemove, kScrollViewContentSize, flutter::PointerData::kStylus, flutter::PointerData::kTouch, flutter::PointerData::kUp, flutter::PointerData::orientation, phase, flutter::PointerData::physical_delta_x, flutter::PointerData::physical_delta_y, flutter::ViewportMetrics::physical_height, flutter::ViewportMetrics::physical_padding_bottom, flutter::ViewportMetrics::physical_padding_left, flutter::ViewportMetrics::physical_padding_right, flutter::ViewportMetrics::physical_padding_top, flutter::ViewportMetrics::physical_view_inset_bottom, flutter::ViewportMetrics::physical_width, flutter::PointerData::physical_x, flutter::PointerData::physical_y, flutter::PointerData::pointer_identifier, flutter::PointerData::pressure, flutter::PointerData::pressure_max, flutter::PointerData::radius_major, flutter::PointerData::radius_max, flutter::PointerData::radius_min, fml::Retain, flutter::PointerData::tilt, flutter::PointerData::time_stamp, TRACE_EVENT0, UIAccessibilityContrastHigh, and flutter::Shell::WaitForFirstFrame().

567  :(void (^)(void))callback {
569 }
fml::ScopedBlock< void(^)(void)> _flutterViewRenderedCallback

◆ 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
routeThe name of the first route to show.

Property Documentation

◆ 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 227 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 183 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 219 of file FlutterViewController.h.

Referenced by NS_ENUM().

◆ 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 238 of file FlutterViewController.h.

◆ mouseTrackingMode

- (FlutterMouseTrackingMode) mouseTrackingMode
readwritenonatomicassign

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

Definition at line 40 of file FlutterViewController.h.

◆ 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 theFlutter 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.

Definition at line 194 of file FlutterViewController.h.

◆ 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 212 of file FlutterViewController.h.


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