io.flutter.embedding.android

Class FlutterFragment.NewEngineFragmentBuilder

java.lang.Object

io.flutter.embedding.android.FlutterFragment.NewEngineFragmentBuilder

Enclosing class:

FlutterFragment

public static class FlutterFragment.NewEngineFragmentBuilder
extends Object

Builder that creates a new FlutterFragment with arguments that correspond to the values set on this NewEngineFragmentBuilder.

To create a FlutterFragment with default arguments, invoke FlutterFragment.createDefault().

Subclasses of FlutterFragment that do not introduce any new arguments can use this NewEngineFragmentBuilder to construct instances of the subclass without subclassing this NewEngineFragmentBuilder. MyFlutterFragment f = new FlutterFragment.NewEngineFragmentBuilder(MyFlutterFragment.class) .someProperty(...) .someOtherProperty(...) .build<MyFlutterFragment>();

Subclasses of FlutterFragment that introduce new arguments should subclass this NewEngineFragmentBuilder to add the new properties:

1. Ensure the FlutterFragment subclass has a no-arg constructor.
2. Subclass this NewEngineFragmentBuilder.
3. Override the new NewEngineFragmentBuilder's no-arg constructor and invoke the super constructor to set the FlutterFragment subclass: public MyBuilder() { super(MyFlutterFragment.class); }
4. Add appropriate property methods for the new properties.
5. Override createArgs(), call through to the super method, then add the new properties as arguments in the Bundle.

Once a NewEngineFragmentBuilder subclass is defined, the FlutterFragment subclass can be instantiated as follows. MyFlutterFragment f = new MyBuilder() .someExistingProperty(...) .someNewProperty(...) .build<MyFlutterFragment>();

Constructor Summary

Constructors

Constructor and Description
NewEngineFragmentBuilder() Constructs a NewEngineFragmentBuilder that is configured to construct an instance of FlutterFragment.
NewEngineFragmentBuilder(Class<? extends FlutterFragment> subclass) Constructs a NewEngineFragmentBuilder that is configured to construct an instance of subclass, which extends FlutterFragment.

Method Summary

Modifier and Type	Method and Description
FlutterFragment.NewEngineFragmentBuilder	appBundlePath(String appBundlePath) The path to the app bundle which contains the Dart app to execute.
<T extends FlutterFragment> T	build() Constructs a new FlutterFragment (or a subclass) that is configured based on properties set on this Builder.
protected Bundle	createArgs() Creates a Bundle of arguments that are assigned to the new FlutterFragment.
FlutterFragment.NewEngineFragmentBuilder	dartEntrypoint(String dartEntrypoint) The name of the initial Dart method to invoke, defaults to "main".
FlutterFragment.NewEngineFragmentBuilder	flutterShellArgs(FlutterShellArgs shellArgs) Any special configuration arguments for the Flutter engine
FlutterFragment.NewEngineFragmentBuilder	initialRoute(String initialRoute) The initial route that a Flutter app will render in this FlutterFragment, defaults to "/".
FlutterFragment.NewEngineFragmentBuilder	renderMode(RenderMode renderMode) Render Flutter either as a RenderMode.surface or a RenderMode.texture.
FlutterFragment.NewEngineFragmentBuilder	shouldAttachEngineToActivity(boolean shouldAttachEngineToActivity) Whether or not this FlutterFragment should automatically attach its Activity as a control surface for its FlutterEngine.
FlutterFragment.NewEngineFragmentBuilder	transparencyMode(TransparencyMode transparencyMode) Support a TransparencyMode.transparent background within FlutterView, or force an TransparencyMode.opaque background.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NewEngineFragmentBuilder

public NewEngineFragmentBuilder()

Constructs a NewEngineFragmentBuilder that is configured to construct an instance of FlutterFragment.

NewEngineFragmentBuilder

public NewEngineFragmentBuilder(@NonNull
                                Class<? extends FlutterFragment> subclass)

Constructs a NewEngineFragmentBuilder that is configured to construct an instance of subclass, which extends FlutterFragment.

Method Detail

dartEntrypoint

@NonNull
public FlutterFragment.NewEngineFragmentBuilder dartEntrypoint(@NonNull
                                                                        String dartEntrypoint)

The name of the initial Dart method to invoke, defaults to "main".

initialRoute

@NonNull
public FlutterFragment.NewEngineFragmentBuilder initialRoute(@NonNull
                                                                      String initialRoute)

The initial route that a Flutter app will render in this FlutterFragment, defaults to "/".

appBundlePath

@NonNull
public FlutterFragment.NewEngineFragmentBuilder appBundlePath(@NonNull
                                                                       String appBundlePath)

The path to the app bundle which contains the Dart app to execute. Null when unspecified, which defaults to FlutterLoader#findAppBundlePath()

flutterShellArgs

@NonNull
public FlutterFragment.NewEngineFragmentBuilder flutterShellArgs(@NonNull
                                                                          FlutterShellArgs shellArgs)

Any special configuration arguments for the Flutter engine

renderMode

@NonNull
public FlutterFragment.NewEngineFragmentBuilder renderMode(@NonNull
                                                                    RenderMode renderMode)

Render Flutter either as a RenderMode.surface or a RenderMode.texture. You should use surface unless you have a specific reason to use texture. texture comes with a significant performance impact, but texture can be displayed beneath other Android Views and animated, whereas surface cannot.

transparencyMode

@NonNull
public FlutterFragment.NewEngineFragmentBuilder transparencyMode(@NonNull
                                                                          TransparencyMode transparencyMode)

Support a TransparencyMode.transparent background within FlutterView, or force an TransparencyMode.opaque background.

See TransparencyMode for implications of this selection.

shouldAttachEngineToActivity

@NonNull
public FlutterFragment.NewEngineFragmentBuilder shouldAttachEngineToActivity(boolean shouldAttachEngineToActivity)

Whether or not this FlutterFragment should automatically attach its Activity as a control surface for its FlutterEngine.

Control surfaces are used to provide Android resources and lifecycle events to plugins that are attached to the FlutterEngine. If shouldAttachEngineToActivity is true then this FlutterFragment will connect its FlutterEngine to the surrounding Activity, along with any plugins that are registered with that FlutterEngine. This allows plugins to access the Activity, as well as receive Activity-specific calls, e.g., Activity.onNewIntent(Intent). If shouldAttachEngineToActivity is false, then this FlutterFragment will not automatically manage the connection between its FlutterEngine and the surrounding Activity. The Activity will need to be manually connected to this FlutterFragment's FlutterEngine by the app developer. See FlutterEngine.getActivityControlSurface().

One reason that a developer might choose to manually manage the relationship between the Activity and FlutterEngine is if the developer wants to move the FlutterEngine somewhere else. For example, a developer might want the FlutterEngine to outlive the surrounding Activity so that it can be used later in a different Activity. To accomplish this, the FlutterEngine will need to be disconnected from the surrounding Activity at an unusual time, preventing this FlutterFragment from correctly managing the relationship between the FlutterEngine and the surrounding Activity.

Another reason that a developer might choose to manually manage the relationship between the Activity and FlutterEngine is if the developer wants to prevent, or explicitly control when the FlutterEngine's plugins have access to the surrounding Activity. For example, imagine that this FlutterFragment only takes up part of the screen and the app developer wants to ensure that none of the Flutter plugins are able to manipulate the surrounding Activity. In this case, the developer would not want the FlutterEngine to have access to the Activity, which can be accomplished by setting shouldAttachEngineToActivity to false.

createArgs

@NonNull
protected Bundle createArgs()

Creates a Bundle of arguments that are assigned to the new FlutterFragment.

Subclasses should override this method to add new properties to the Bundle. Subclasses must call through to the super method to collect all existing property values.

build

@NonNull
public <T extends FlutterFragment> T build()

Constructs a new FlutterFragment (or a subclass) that is configured based on properties set on this Builder.