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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### CachedEngineFragmentBuilder

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

  - ### Method Detail

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