Fragments: rebuilding the internals
Fragments, more than most Android APIs, have evolved very organically over the years. They started as part of the Android platform itself, became a mirrored existence in the Android platform and as part of the Android Support Library, and now exist solely as part of Jetpack as AndroidX Fragments.
Note: you should under no circumstances use the Android framework version of Fragments. Besides being fully deprecated in Android 10, they weren’t receiving fixes for a considerable amount of time before that and, being baked into the framework, no backporting of fixes or consistency across devices and API levels can be expected.
While Architecture Components have taken over many of the roles that traditionally needed a Fragment (such as using a
LifecycleObserver for Lifecycle callbacks or a
ViewModel for retained state), if you’re using Fragments, you’re adding, removing, and interacting with them through a
1.3.0-alpha08, some of the most significant restructuring of the internals of
FragmentManager have been completed. This release swaps out much of the logic that used to live directly in
FragmentManager with smaller, testable, and maintainable (internal) classes, the core of which is
Note: I’m going to be talking a lot about the internals of
FragmentManagerin this post. TL/DR: please pay extra attention to regression testing with Fragment
1.3.0-alpha08and file issues as soon as possible if you discover any regressions.
This new state manager is responsible for some pretty key parts of Fragments:
- Moving Fragments through their lifecycle methods
- Running animations and transitions
- Handling postponed transactions
We’ve taken a ground up look at how those systems previously work, found them wanting, and rewrote them from scratch. They’re now better than ever, we were able to close out 10+ long standing related issues, and the internal restructuring has cleared the way to build support for multiple back stacks in a single
FragmentManager and simplify the Fragment lifecycle.
FragmentManager is associated with a host. In the vast majority of cases for fragments, this is a
FragmentActivity (there is an entire layer of
FragmentHostCallback for building your own custom host, but let’s avoid that discussion here). As the activity moves to
FragmentManager dispatches those changes down to its fragments. This is the role of
Of course, it isn’t quite that straightforward. There is a lot of conditional logic to determine exactly what state the fragment should be in — the activity lifecycle state (or the parent fragment’s state for nested fragments) is only the first part and serves as the maximum state the fragment can be in. This maximum is there to ensure that the lifecycle of the activity, fragments, and their child fragments are all properly nested.
So our first order of business in simplifying
moveToState() was to collapse all of that logic into one place. Thus was born
FragmentStateManager. Each fragment instance is tied to a
FragmentStateManager under the hood. By introducing this class internally, we were able to take much of code that interacts with the fragment (such as calling the fragment’s
onCreateView and other lifecycle methods) out of
That split also allowed us to write a single method that would take all of the backward compatible required logic for what state the fragment should actually be in and centralize it in one place:
computeExpectedState(). This one method keeps track of all of the current state and determines what state the fragment should be in. 98% of the time, it is the same state as the host / parent fragment, but that 2% makes a big difference to those apps built on fragments.
However, we ran into one case where we didn’t have a way to determine the right state: postponed fragments.
Fragments, for better or worse, inherited a lot of the same nomenclature and API surface as activities. Part of this inheritance was around transitions and the ability to postpone your enter transition until you’re ready. This is critical to shared element transitions (where you really want to have an image loaded to know its dimensions and position on the screen before starting the transition over to that location), but also allows you to ensure that more intensive loading calls don’t happen at the same time as your transition, avoiding jank.
A postponed fragment has two important qualities:
- Its view was created, but is not visible
- Its lifecycle is capped at
As soon as you call
startPostponedEnterTransition(), the fragment’s transition would run, the view would become visible, and the fragment would be able to move to
RESUMED. This is, in fact, exactly what the new state manager does, but it was not how Fragments worked before. To quote the Postponed Fragments leave the Fragments and FragmentManager in an inconsistent state bug:
When a Fragment is postponed using
postponeEnterTransition(), the expected behavior is that the container the Fragment is added to does not run any enter animations or previously queued up exit animations (i.e., for a
replace()operation) until the Fragment calls
startPostponedEnterTransition(). It is also expected that the Fragment does not reach the
RESUMEDstate while its container is postponed.
However, it seems like FragmentManager isn’t just doing that, but instead is moving the Fragment and the whole FragmentManager into a weird, inconsistent state.
Namely, any FragmentTransaction that touches the container of the postponed Fragment is ‘rolled back’ (i.e., done in reverse), but those Fragments aren’t actually moved to their proper state.
This led to a litany of issues:
- The Fragment’s view is created, but the fragment isn’t added (
findFragmentById()doesn't return the newly added Fragment over the one it replaces, even when using
- Fragments stuck in this limbo state don’t get started when the FragmentManager is started (https://issuetracker.google.com/issues/129035555)
- FragmentTransactions can be executed out of order (https://issuetracker.google.com/issues/147297731)
- Other animations on the container (such as previously started pop animations) still run (https://issuetracker.google.com/issues/37140383)
onCreateView()can be called a second time (https://issuetracker.google.com/issues/143915710)
Actually fixing any of these issues meant replacing the entire roll back process used by postponed fragments with a system that keeps the
FragmentManager in a consistent, up to date state, while still maintaining the important qualities of postponed fragments.
Working at the container level
FragmentManager has this nice (read: handy, but not fun as the maintainer) property where it lets you pass in any container ID for where you want to place a Fragment. Even for a single
FragmentTransaction, you can
add a fragment to one container,
remove another from a different container,
replace a third container’s topmost fragment, etc. The rub comes in when it comes to animating in/out the fragments — something that happens solely at the container level.
Fragments support a number of animating systems:
- The old and busted framework
- The framework
- The framework
TransitionAPI (only API 21+, also pretty busted)
- The AndroidX
As you might know, naming is one of the hardest problems in Computer Science, so when we went to build a class that could control all of these APIs, it took a while to settle on
SpecialEffectsController (this class isn’t part of the public API, so names are still subject to change, thankfully). This class exists on the container level and coordinates all of the “special effects” associated with entering and exiting fragments.
SpecialEffectsController is the single source of truth on what should be happening to that container. This means that if the topmost added fragment is postponed, the entire container is postponed. There’s no more logic needed at the
FragmentManager layer, nor any rollback of transactions (which, as we mentioned, can affect multiple containers). Thus, the
FragmentManager is in the correct state and we still get all of the special properties of postponed fragments.
This base API then allowed us to centralize all of the crazy special effects APIs that fragment has into a single
DefaultSpecialEffectsController that is responsible for running transitions and animations and animators. Again, moving logic that used to be scattered across
FragmentManager into a single place.
So what does a ‘new state manager’ mean
Well, it means that instead of this architecture:
It looks more like this:
By splitting up the internals of
FragmentManager, the logic has been greatly simplified at each layer:
FragmentManageronly has state that applies to all fragments
FragmentStateManagermanages the state at the fragment level
SpecialEffectsControllermanages the state at the container level
This separation of responsibilities has let us expand our test suite by almost 30%, covering many more scenarios that were near impossible to test in isolation.
Should I expect behavior changes?
No. In fact, we run a significant portion of the internal fragment tests against both the old and new state managers specifically to ensure we have a strong set of regression tests in place.
However, if you were relying on the inconsistent state a postponed fragment put the
FragmentManager into, then yeah, you’ll find that you now actually get the correct state. You’ll find the list of bug fixes associated with the new state manager as part of the release notes, so take a look through that to make sure that your issues aren’t caused by your own workarounds for the old broken behavior that you can now just remove.
Similar to the changes to
onDestroyView timing in Fragment
1.2.0, the new state manager will keep your fragment in the
STARTED state until its transitions/animations/animators/special effects all finish, thus bringing consistency across all fragments, whether they are postponed directly or postponed because of other fragments in that same container.
What if I *do* see behavior changes?
After you upgrade to Fragment
1.3.0-alpha08, the new state manager is enabled by default. If you see differences in your app, the first step is to see if it is related to the new state manager by using the new experimental API:
This API is an escape hatch back into the old world and lets you verify that any changes you’re seeing are tied to the new state manager. This unblocks you from upgrading the Fragment
1.3.0-alpha08 and lets you build a sample project that reproduces the issue that you can attach when you file an issue against Fragments.
FragmentManager.enableNewStateManager()API is experimental. That means that it is not considered part of the stable API surface of Fragments and can be removed at any point. Removing all of the old code is a significant code reduction, but given the importance of getting this right, we likely won’t remove the API until after the stable release of Fragment 1.3.0 — i.e., consider it on notice for removal in a Fragment 1.3.1 release.
With over 100 individual changes over an 11 month period, this is absolutely the largest internal change to Fragments in a while and sets us up for a much more maintainable, sustainable, and understandable code base. That means more consistent behavior across Fragments and a firm base you can rely on when building your app. We’d appreciate any help you can offer in making sure this new state manager is the best it can be by continuing to file issues and offering feedback.