public static class FlutterFragment.CachedEngineFragmentBuilder extends Object
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:
FlutterFragment
subclass has a no-arg constructor.CachedEngineFragmentBuilder
.CachedEngineFragmentBuilder
's no-arg constructor and invoke the
super constructor to set the FlutterFragment
subclass: public MyBuilder() {
super(MyFlutterFragment.class);
}
createArgs()
, call through to the super
method, then add the new properties as arguments in the Bundle
.CachedEngineFragmentBuilder
subclass is defined, the FlutterFragment
subclass can be instantiated as follows.
MyFlutterFragment f = new MyBuilder()
.someExistingProperty(...)
.someNewProperty(...)
.build<MyFlutterFragment>();
Modifier | Constructor and Description |
---|---|
protected |
CachedEngineFragmentBuilder(Class<? extends FlutterFragment> subclass,
String engineId) |
Modifier and Type | Method and Description |
---|---|
<T extends FlutterFragment> |
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 |
renderMode(FlutterView.RenderMode renderMode)
Render Flutter either as a
FlutterView.RenderMode.surface or a
FlutterView.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 |
transparencyMode(FlutterView.TransparencyMode transparencyMode)
Support a
FlutterView.TransparencyMode.transparent background within FlutterView ,
or force an FlutterView.TransparencyMode.opaque background. |
protected CachedEngineFragmentBuilder(@NonNull Class<? extends FlutterFragment> subclass, @NonNull String engineId)
@NonNull public FlutterFragment.CachedEngineFragmentBuilder destroyEngineWithFragment(boolean destroyEngineWithFragment)
true
to destroy the cached FlutterEngine
when this
FlutterFragment
is destroyed, or false
for the cached FlutterEngine
to outlive this FlutterFragment
.@NonNull public FlutterFragment.CachedEngineFragmentBuilder renderMode(@NonNull FlutterView.RenderMode renderMode)
FlutterView.RenderMode.surface
or a
FlutterView.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.@NonNull public FlutterFragment.CachedEngineFragmentBuilder transparencyMode(@NonNull FlutterView.TransparencyMode transparencyMode)
FlutterView.TransparencyMode.transparent
background within FlutterView
,
or force an FlutterView.TransparencyMode.opaque
background.
See FlutterView.TransparencyMode
for implications of this selection.
@NonNull public FlutterFragment.CachedEngineFragmentBuilder shouldAttachEngineToActivity(boolean shouldAttachEngineToActivity)
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
.
@NonNull public <T extends FlutterFragment> T build()
FlutterFragment
(or a subclass) that is configured based on
properties set on this CachedEngineFragmentBuilder
.