Package io.flutter.embedding.android

# Class FlutterFragment.CachedEngineFragmentBuilder

java.lang.Object
io.flutter.embedding.android.FlutterFragment.CachedEngineFragmentBuilder

Enclosing class:
  FlutterFragment

public static class FlutterFragment.CachedEngineFragmentBuilder extends Object
Builder that creates a new `FlutterFragment` that uses a cached `FlutterEngine` with `arguments` that correspond to the values set on this `Builder`.

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

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

1. Ensure the `FlutterFragment` subclass has a no-arg constructor.
2. Subclass this `CachedEngineFragmentBuilder`.
3. Override the new `CachedEngineFragmentBuilder`'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 `CachedEngineFragmentBuilder` subclass is defined, the `FlutterFragment` subclass can be instantiated as follows. `MyFlutterFragment f = new MyBuilder() .someExistingProperty(...) .someNewProperty(...) .build<MyFlutterFragment>();`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CachedEngineFragmentBuilder(Class<? extends FlutterFragment> subclass, String engineId)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<T extends FlutterFragment>
  T`
  `build()`
  Constructs a new `FlutterFragment` (or a subclass) that is configured based on properties set on this `CachedEngineFragmentBuilder`.
  `protected Bundle`
  `createArgs()`
  Creates a `Bundle` of arguments that are assigned to the new `FlutterFragment`.
  `FlutterFragment.CachedEngineFragmentBuilder`
  `destroyEngineWithFragment(boolean destroyEngineWithFragment)`
  Pass `true` to destroy the cached `FlutterEngine` when this `FlutterFragment` is destroyed, or `false` for the cached `FlutterEngine` to outlive this `FlutterFragment`.
  `FlutterFragment.CachedEngineFragmentBuilder`
  `handleDeeplinking(Boolean handleDeeplinking)`
  Whether to handle the deeplinking from the `Intent` automatically if the `getInitialRoute` returns null.
  `FlutterFragment.CachedEngineFragmentBuilder`
  `renderMode(RenderMode renderMode)`
  Render Flutter either as a `RenderMode.surface` or a `RenderMode.texture`.
  `FlutterFragment.CachedEngineFragmentBuilder`
  `shouldAttachEngineToActivity(boolean shouldAttachEngineToActivity)`
  Whether or not this `FlutterFragment` should automatically attach its `Activity` as a control surface for its `FlutterEngine`.
  `FlutterFragment.CachedEngineFragmentBuilder`
  `shouldAutomaticallyHandleOnBackPressed(boolean shouldAutomaticallyHandleOnBackPressed)`
  Whether or not this `FlutterFragment` should automatically receive `FlutterFragment.onBackPressed()` events, rather than requiring an explicit activity call through.
  `FlutterFragment.CachedEngineFragmentBuilder`
  `shouldDelayFirstAndroidViewDraw(boolean shouldDelayFirstAndroidViewDraw)`
  Whether to delay the Android drawing pass till after the Flutter UI has been displayed.
  `FlutterFragment.CachedEngineFragmentBuilder`
  `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

  - ### CachedEngineFragmentBuilder

    public CachedEngineFragmentBuilder(@NonNull Class<? extends FlutterFragment> subclass, @NonNull String engineId)

- ## Method Details

  - ### destroyEngineWithFragment

    @NonNull public FlutterFragment.CachedEngineFragmentBuilder destroyEngineWithFragment(boolean destroyEngineWithFragment)
    Pass `true` to destroy the cached `FlutterEngine` when this `FlutterFragment` is destroyed, or `false` for the cached `FlutterEngine` to outlive this `FlutterFragment`.

  - ### renderMode

    @NonNull public FlutterFragment.CachedEngineFragmentBuilder 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.CachedEngineFragmentBuilder transparencyMode(@NonNull TransparencyMode transparencyMode)
    Support a `TransparencyMode.transparent` background within `FlutterView`, or force an `TransparencyMode.opaque` background.

    See `TransparencyMode` for implications of this selection.

  - ### handleDeeplinking

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

  - ### shouldAttachEngineToActivity

    @NonNull public FlutterFragment.CachedEngineFragmentBuilder 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.CachedEngineFragmentBuilder 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.

    Enabling this behavior relies on explicit behavior in `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.CachedEngineFragmentBuilder shouldDelayFirstAndroidViewDraw(@NonNull 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 `CachedEngineFragmentBuilder`.