Package 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
  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
  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`
  `dartEntrypointArgs(List<String> dartEntrypointArgs)`
  Arguments passed as a list of string to Dart's entrypoint function.
  `FlutterFragment.NewEngineFragmentBuilder`
  `dartLibraryUri(String dartLibraryUri)`
  `FlutterFragment.NewEngineFragmentBuilder`
  `flutterShellArgs(FlutterShellArgs shellArgs)`
  Any special configuration arguments for the Flutter engine
  `FlutterFragment.NewEngineFragmentBuilder`
  `handleDeeplinking(Boolean handleDeeplinking)`
  Whether to handle the deeplinking from the `Intent` automatically if the `getInitialRoute` returns null.
  `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`
  `shouldAutomaticallyHandleOnBackPressed(boolean shouldAutomaticallyHandleOnBackPressed)`
  Whether or not this `FlutterFragment` should automatically receive `FlutterFragment.onBackPressed()` events, rather than requiring an explicit activity call through.
  `FlutterFragment.NewEngineFragmentBuilder`
  `shouldDelayFirstAndroidViewDraw(boolean shouldDelayFirstAndroidViewDraw)`
  Whether to delay the Android drawing pass till after the Flutter UI has been displayed.
  `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 Details

  - ### 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 Details

  - ### dartEntrypoint

    @NonNull public FlutterFragment.NewEngineFragmentBuilder dartEntrypoint(@NonNull String dartEntrypoint)
    The name of the initial Dart method to invoke, defaults to "main".

  - ### dartLibraryUri

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

  - ### dartEntrypointArgs

    @NonNull public FlutterFragment.NewEngineFragmentBuilder dartEntrypointArgs(@NonNull List<String> dartEntrypointArgs)
    Arguments passed as a list of string to Dart's entrypoint function.

  - ### initialRoute

    @NonNull public FlutterFragment.NewEngineFragmentBuilder initialRoute(@NonNull String initialRoute)
    The initial route that a Flutter app will render in this `FlutterFragment`, defaults to "/".

  - ### handleDeeplinking

    @NonNull public FlutterFragment.NewEngineFragmentBuilder handleDeeplinking(@NonNull Boolean handleDeeplinking)
    Whether to handle the deeplinking from the `Intent` automatically if the `getInitialRoute` returns null.

  - ### 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 `View`s 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`.

  - ### shouldAutomaticallyHandleOnBackPressed

    @NonNull public FlutterFragment.NewEngineFragmentBuilder shouldAutomaticallyHandleOnBackPressed(boolean shouldAutomaticallyHandleOnBackPressed)
    Whether or not this `FlutterFragment` should automatically receive `FlutterFragment.onBackPressed()` events, rather than requiring an explicit activity call through. Disabled by default.

    When enabled, the activity will automatically dispatch back-press events to the fragment's `OnBackPressedCallback`, instead of requiring the activity to manually call `FlutterFragment.onBackPressed()` in client code. If enabled, do not invoke `FlutterFragment.onBackPressed()` manually.

    This behavior relies on the implementation of `FlutterFragment.popSystemNavigator()`. It's not recommended to override that method when enabling this attribute, but if you do, you should always fall back to calling `super.popSystemNavigator()` when not relying on custom behavior.

  - ### shouldDelayFirstAndroidViewDraw

    @NonNull public FlutterFragment.NewEngineFragmentBuilder shouldDelayFirstAndroidViewDraw(boolean shouldDelayFirstAndroidViewDraw)
    Whether to delay the Android drawing pass till after the Flutter UI has been displayed.

    See {#link FlutterActivityAndFragmentDelegate#onCreateView} for more details.

  - ### 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`.