public class FlutterFragment extends android.support.v4.app.Fragment
Fragment
which displays a Flutter UI that takes up all available Fragment
space.
Using a FlutterFragment
requires forwarding a number of calls from an Activity
to
ensure that the internal Flutter app behaves as expected:
onPostResume()
onBackPressed()
onRequestPermissionsResult(int, String[], int[])
()}onNewIntent(Intent)
()}onUserLeaveHint()
onTrimMemory(int)
Activity
for a result from this Fragment
, be sure
to invoke Fragment.startActivityForResult(Intent, int)
rather than
Activity.startActivityForResult(Intent, int)
. If the Activity
version
of the method is invoked then this Fragment
will never receive its
Fragment.onActivityResult(int, int, Intent)
callback.
If convenient, consider using a FlutterActivity
instead of a FlutterFragment
to
avoid the work of forwarding calls.
FlutterFragment
supports the use of an existing, cached FlutterEngine
. To use a
cached FlutterEngine
, ensure that the FlutterEngine
is stored in
FlutterEngineCache
and then use withCachedEngine(String)
to build a
FlutterFragment
with the cached FlutterEngine
's ID.
It is generally recommended to use a cached FlutterEngine
to avoid a momentary delay
when initializing a new FlutterEngine
. The two exceptions to using a cached
FlutterEngine
are:
FlutterFragment
is in the first Activity
displayed by the app, because
pre-warming a FlutterEngine
would have no impact in this situation.
The following illustrates how to pre-warm and cache a FlutterEngine
:
// Create and pre-warm a FlutterEngine.
FlutterEngine flutterEngine = new FlutterEngine(context);
flutterEngine
.getDartExecutor()
.executeDartEntrypoint(DartEntrypoint.createDefault());
// Cache the pre-warmed FlutterEngine in the FlutterEngineCache.
FlutterEngineCache.getInstance().put("my_engine", flutterEngine);
If Flutter is needed in a location that can only use a View
, consider using a
FlutterView
. Using a FlutterView
requires forwarding some calls from an
Activity
, as well as forwarding lifecycle calls from an Activity
or a
Fragment
.
Modifier and Type | Class and Description |
---|---|
static class |
FlutterFragment.CachedEngineFragmentBuilder
Builder that creates a new
FlutterFragment that uses a cached FlutterEngine
with arguments that correspond to the values set on this Builder . |
static class |
FlutterFragment.NewEngineFragmentBuilder
Builder that creates a new
FlutterFragment with arguments that correspond
to the values set on this NewEngineFragmentBuilder . |
android.support.v4.app.Fragment.InstantiationException, android.support.v4.app.Fragment.SavedState
Modifier and Type | Field and Description |
---|---|
protected static String |
ARG_APP_BUNDLE_PATH
Path to Flutter's Dart code.
|
protected static String |
ARG_CACHED_ENGINE_ID
The ID of a
FlutterEngine cached in FlutterEngineCache that will be used within
the created FlutterFragment . |
protected static String |
ARG_DART_ENTRYPOINT
The Dart entrypoint method name that is executed upon initialization.
|
protected static String |
ARG_DESTROY_ENGINE_WITH_FRAGMENT
True if the
FlutterEngine in the created FlutterFragment should be destroyed
when the FlutterFragment is destroyed, false if the FlutterEngine should
outlive the FlutterFragment . |
protected static String |
ARG_FLUTTER_INITIALIZATION_ARGS
Flutter shell arguments.
|
protected static String |
ARG_FLUTTERVIEW_RENDER_MODE
|
protected static String |
ARG_FLUTTERVIEW_TRANSPARENCY_MODE
|
protected static String |
ARG_INITIAL_ROUTE
Initial Flutter route that is rendered in a Navigator widget.
|
protected static String |
ARG_SHOULD_ATTACH_ENGINE_TO_ACTIVITY
|
Constructor and Description |
---|
FlutterFragment() |
Modifier and Type | Method and Description |
---|---|
void |
cleanUpFlutterEngine(FlutterEngine flutterEngine)
Hook for the host to cleanup references that were established in
configureFlutterEngine(FlutterEngine) before the host is destroyed or detached. |
void |
configureFlutterEngine(FlutterEngine flutterEngine)
Configures a
FlutterEngine after its creation. |
static FlutterFragment |
createDefault()
Creates a
FlutterFragment with a default configuration. |
Activity |
getActivity()
|
String |
getAppBundlePath()
Returns the file path to the desired Flutter app's bundle of code.
|
String |
getCachedEngineId()
Returns the ID of a statically cached
FlutterEngine to use within this
FlutterFragment , or null if this FlutterFragment does not want to
use a cached FlutterEngine . |
Context |
getContext()
|
String |
getDartEntrypointFunctionName()
Returns the name of the Dart method that this
FlutterFragment should execute to
start a Flutter app. |
FlutterEngine |
getFlutterEngine()
Hook for subclasses to obtain a reference to the
FlutterEngine that is owned
by this FlutterActivity . |
FlutterShellArgs |
getFlutterShellArgs()
FlutterActivityAndFragmentDelegate.Host method that is used by
FlutterActivityAndFragmentDelegate to obtain Flutter shell arguments when
initializing Flutter. |
String |
getInitialRoute()
Returns the initial route that should be rendered within Flutter, once the Flutter app starts.
|
android.arch.lifecycle.Lifecycle |
getLifecycle()
|
FlutterView.RenderMode |
getRenderMode()
|
FlutterView.TransparencyMode |
getTransparencyMode()
Returns the desired
FlutterView.TransparencyMode for the FlutterView displayed in
this FlutterFragment . |
void |
onActivityCreated(Bundle savedInstanceState) |
void |
onActivityResult(int requestCode,
int resultCode,
Intent data)
A result has been returned after an invocation of
Fragment.startActivityForResult(Intent, int) . |
void |
onAttach(Context context) |
void |
onBackPressed()
The hardware back button was pressed.
|
View |
onCreateView(LayoutInflater inflater,
ViewGroup container,
Bundle savedInstanceState) |
void |
onDestroyView() |
void |
onDetach() |
void |
onFlutterUiDisplayed()
Invoked after the
FlutterView within this FlutterFragment starts rendering
pixels to the screen. |
void |
onFlutterUiNoLongerDisplayed()
Invoked after the
FlutterView within this FlutterFragment stops rendering
pixels to the screen. |
void |
onLowMemory()
Callback invoked when memory is low.
|
void |
onNewIntent(Intent intent)
|
void |
onPause() |
void |
onPostResume() |
void |
onRequestPermissionsResult(int requestCode,
String[] permissions,
int[] grantResults)
The result of a permission request has been received.
|
void |
onResume() |
void |
onSaveInstanceState(Bundle outState) |
void |
onStart() |
void |
onStop() |
void |
onTrimMemory(int level)
Callback invoked when memory is low.
|
void |
onUserLeaveHint()
|
FlutterEngine |
provideFlutterEngine(Context context)
Hook for subclasses to return a
FlutterEngine with whatever configuration
is desired. |
PlatformPlugin |
providePlatformPlugin(Activity activity,
FlutterEngine flutterEngine)
Hook for the host to create/provide a
PlatformPlugin if the associated
Flutter experience should control system chrome. |
SplashScreen |
provideSplashScreen()
Provides a
SplashScreen to display while Flutter initializes and renders its first
frame. |
boolean |
shouldAttachEngineToActivity()
|
boolean |
shouldDestroyEngineWithHost()
Returns false if the
FlutterEngine within this FlutterFragment should outlive
the FlutterFragment , itself. |
static FlutterFragment.CachedEngineFragmentBuilder |
withCachedEngine(String engineId)
Returns a
FlutterFragment.CachedEngineFragmentBuilder to create a FlutterFragment with a cached
FlutterEngine in FlutterEngineCache . |
static FlutterFragment.NewEngineFragmentBuilder |
withNewEngine()
Returns a
FlutterFragment.NewEngineFragmentBuilder to create a FlutterFragment with a new
FlutterEngine and a desired engine configuration. |
dump, equals, getActivity, getAllowEnterTransitionOverlap, getAllowReturnTransitionOverlap, getArguments, getChildFragmentManager, getContext, getEnterTransition, getExitTransition, getFragmentManager, getHost, getId, getLayoutInflater, getLayoutInflater, getLifecycle, getLoaderManager, getParentFragment, getReenterTransition, getResources, getRetainInstance, getReturnTransition, getSharedElementEnterTransition, getSharedElementReturnTransition, getString, getString, getTag, getTargetFragment, getTargetRequestCode, getText, getUserVisibleHint, getView, getViewLifecycleOwner, getViewLifecycleOwnerLiveData, getViewModelStore, hashCode, hasOptionsMenu, instantiate, instantiate, isAdded, isDetached, isHidden, isInLayout, isMenuVisible, isRemoving, isResumed, isStateSaved, isVisible, onAttach, onAttachFragment, onConfigurationChanged, onContextItemSelected, onCreate, onCreateAnimation, onCreateAnimator, onCreateContextMenu, onCreateOptionsMenu, onDestroy, onDestroyOptionsMenu, onGetLayoutInflater, onHiddenChanged, onInflate, onInflate, onMultiWindowModeChanged, onOptionsItemSelected, onOptionsMenuClosed, onPictureInPictureModeChanged, onPrepareOptionsMenu, onViewCreated, onViewStateRestored, postponeEnterTransition, registerForContextMenu, requestPermissions, requireActivity, requireContext, requireFragmentManager, requireHost, setAllowEnterTransitionOverlap, setAllowReturnTransitionOverlap, setArguments, setEnterSharedElementCallback, setEnterTransition, setExitSharedElementCallback, setExitTransition, setHasOptionsMenu, setInitialSavedState, setMenuVisibility, setReenterTransition, setRetainInstance, setReturnTransition, setSharedElementEnterTransition, setSharedElementReturnTransition, setTargetFragment, setUserVisibleHint, shouldShowRequestPermissionRationale, startActivity, startActivity, startActivityForResult, startActivityForResult, startIntentSenderForResult, startPostponedEnterTransition, toString, unregisterForContextMenu
protected static final String ARG_DART_ENTRYPOINT
protected static final String ARG_INITIAL_ROUTE
protected static final String ARG_APP_BUNDLE_PATH
protected static final String ARG_FLUTTER_INITIALIZATION_ARGS
protected static final String ARG_FLUTTERVIEW_RENDER_MODE
protected static final String ARG_FLUTTERVIEW_TRANSPARENCY_MODE
protected static final String ARG_SHOULD_ATTACH_ENGINE_TO_ACTIVITY
protected static final String ARG_CACHED_ENGINE_ID
FlutterEngine
cached in FlutterEngineCache
that will be used within
the created FlutterFragment
.protected static final String ARG_DESTROY_ENGINE_WITH_FRAGMENT
FlutterEngine
in the created FlutterFragment
should be destroyed
when the FlutterFragment
is destroyed, false if the FlutterEngine
should
outlive the FlutterFragment
.@NonNull public static FlutterFragment createDefault()
FlutterFragment
with a default configuration.
FlutterFragment
's default configuration creates a new FlutterEngine
within
the FlutterFragment
and uses the following settings:
To use a new FlutterEngine
with different settings, use withNewEngine()
.
To use a cached FlutterEngine
instead of creating a new one, use
withCachedEngine(String)
.
@NonNull public static FlutterFragment.NewEngineFragmentBuilder withNewEngine()
FlutterFragment.NewEngineFragmentBuilder
to create a FlutterFragment
with a new
FlutterEngine
and a desired engine configuration.@NonNull public static FlutterFragment.CachedEngineFragmentBuilder withCachedEngine(@NonNull String engineId)
FlutterFragment.CachedEngineFragmentBuilder
to create a FlutterFragment
with a cached
FlutterEngine
in FlutterEngineCache
.
An IllegalStateException
will be thrown during the lifecycle of the
FlutterFragment
if a cached FlutterEngine
is requested but does not exist in
the cache.
To create a FlutterFragment
that uses a new FlutterEngine
, use
createDefault()
or withNewEngine()
.
public void onAttach(@NonNull Context context)
onAttach
in class android.support.v4.app.Fragment
@Nullable public View onCreateView(LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState)
onCreateView
in class android.support.v4.app.Fragment
public void onActivityCreated(@Nullable Bundle savedInstanceState)
onActivityCreated
in class android.support.v4.app.Fragment
public void onStart()
onStart
in class android.support.v4.app.Fragment
public void onResume()
onResume
in class android.support.v4.app.Fragment
public void onPostResume()
public void onPause()
onPause
in class android.support.v4.app.Fragment
public void onStop()
onStop
in class android.support.v4.app.Fragment
public void onDestroyView()
onDestroyView
in class android.support.v4.app.Fragment
public void onSaveInstanceState(Bundle outState)
onSaveInstanceState
in class android.support.v4.app.Fragment
public void onDetach()
onDetach
in class android.support.v4.app.Fragment
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults)
See Activity.onRequestPermissionsResult(int, String[], int[])
onRequestPermissionsResult
in class android.support.v4.app.Fragment
requestCode
- identifier passed with the initial permission requestpermissions
- permissions that were requestedgrantResults
- permission grants or denialspublic void onBackPressed()
public void onActivityResult(int requestCode, int resultCode, Intent data)
Fragment.startActivityForResult(Intent, int)
.
onActivityResult
in class android.support.v4.app.Fragment
requestCode
- request code sent with Fragment.startActivityForResult(Intent, int)
resultCode
- code representing the result of the Activity
that was launcheddata
- any corresponding return data, held within an Intent
public void onUserLeaveHint()
public void onTrimMemory(int level)
This implementation forwards a memory pressure warning to the running Flutter app.
level
- levelpublic void onLowMemory()
This implementation forwards a memory pressure warning to the running Flutter app.
onLowMemory
in interface ComponentCallbacks
onLowMemory
in class android.support.v4.app.Fragment
@NonNull public FlutterShellArgs getFlutterShellArgs()
FlutterActivityAndFragmentDelegate.Host
method that is used by
FlutterActivityAndFragmentDelegate
to obtain Flutter shell arguments when
initializing Flutter.@Nullable public String getCachedEngineId()
FlutterEngine
to use within this
FlutterFragment
, or null
if this FlutterFragment
does not want to
use a cached FlutterEngine
.public boolean shouldDestroyEngineWithHost()
FlutterEngine
within this FlutterFragment
should outlive
the FlutterFragment
, itself.
Defaults to true if no custom is provided
, false if a custom
FlutterEngine
is provided.
@NonNull public String getDartEntrypointFunctionName()
FlutterFragment
should execute to
start a Flutter app.
Defaults to "main".
Used by this FlutterFragment
's FlutterActivityAndFragmentDelegate.Host
@NonNull public String getAppBundlePath()
Defaults to FlutterMain.findAppBundlePath()
.
Used by this FlutterFragment
's FlutterActivityAndFragmentDelegate.Host
@Nullable public String getInitialRoute()
Defaults to null
, which signifies a route of "/" in Flutter.
Used by this FlutterFragment
's FlutterActivityAndFragmentDelegate.Host
@NonNull public FlutterView.RenderMode getRenderMode()
FlutterView.RenderMode
for the FlutterView
displayed in
this FlutterFragment
.
Defaults to FlutterView.RenderMode.surface
.
Used by this FlutterFragment
's FlutterActivityAndFragmentDelegate.Host
@NonNull public FlutterView.TransparencyMode getTransparencyMode()
FlutterView.TransparencyMode
for the FlutterView
displayed in
this FlutterFragment
.
Defaults to FlutterView.TransparencyMode.transparent
.
Used by this FlutterFragment
's FlutterActivityAndFragmentDelegate.Host
@Nullable public SplashScreen provideSplashScreen()
SplashScreenProvider
SplashScreen
to display while Flutter initializes and renders its first
frame.@Nullable public FlutterEngine provideFlutterEngine(@NonNull Context context)
FlutterEngine
with whatever configuration
is desired.
By default this method defers to this FlutterFragment
's surrounding Activity
,
if that Activity
implements FlutterEngineProvider
. If this method is
overridden, the surrounding Activity
will no longer be given an opportunity to
provide a FlutterEngine
, unless the subclass explicitly implements that behavior.
Consider returning a cached FlutterEngine
instance from this method to avoid the
typical warm-up time that a new FlutterEngine
instance requires.
If null is returned then a new default FlutterEngine
will be created to back this
FlutterFragment
.
Used by this FlutterFragment
's FlutterActivityAndFragmentDelegate.Host
@Nullable public FlutterEngine getFlutterEngine()
FlutterEngine
that is owned
by this FlutterActivity
.@Nullable public PlatformPlugin providePlatformPlugin(@Nullable Activity activity, @NonNull FlutterEngine flutterEngine)
PlatformPlugin
if the associated
Flutter experience should control system chrome.public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine)
FlutterEngine
after its creation.
This method is called after provideFlutterEngine(Context)
, and after the given
FlutterEngine
has been attached to the owning FragmentActivity
. See
ActivityControlSurface.attachToActivity(Activity, Lifecycle)
.
It is possible that the owning FragmentActivity
opted not to connect itself as
an ActivityControlSurface
. In that
case, any configuration, e.g., plugins, must not expect or depend upon an available
Activity
at the time that this method is invoked.
The default behavior of this method is to defer to the owning FragmentActivity
as a FlutterEngineConfigurator
. Subclasses can override this method if the
subclass needs to override the FragmentActivity
's behavior, or add to it.
Used by this FlutterFragment
's FlutterActivityAndFragmentDelegate.Host
public void cleanUpFlutterEngine(@NonNull FlutterEngine flutterEngine)
configureFlutterEngine(FlutterEngine)
before the host is destroyed or detached.
This method is called in onDetach()
.
public boolean shouldAttachEngineToActivity()
shouldAttachEngineToActivity()
and
shouldAttachEngineToActivity()
.
Used by this FlutterFragment
's FlutterActivityAndFragmentDelegate
public void onFlutterUiDisplayed()
FlutterView
within this FlutterFragment
starts rendering
pixels to the screen.
This method forwards onFlutterUiDisplayed()
to its attached Activity
, if
the attached Activity
implements FlutterUiDisplayListener
.
Subclasses that override this method must call through to the super
method.
Used by this FlutterFragment
's FlutterActivityAndFragmentDelegate.Host
public void onFlutterUiNoLongerDisplayed()
FlutterView
within this FlutterFragment
stops rendering
pixels to the screen.
This method forwards onFlutterUiNoLongerDisplayed()
to its attached Activity
,
if the attached Activity
implements FlutterUiDisplayListener
.
Subclasses that override this method must call through to the super
method.
Used by this FlutterFragment
's FlutterActivityAndFragmentDelegate.Host
@NonNull public android.arch.lifecycle.Lifecycle getLifecycle()