LayeredDialogSessions
Does the bulk of the work of maintaining a set of Dialogs to reflect lists of Overlay, constrained to cover only the bounds of a single View. This is the work modeled by BodyAndOverlaysScreen and executed by BodyAndOverlaysContainer. This class is public to allow implementation of custom Overlay-based layouts if BodyAndOverlaysContainer is too restrictive.
Provides an allowBodyEvents field that reflects the presence or absence of Dialogs driven by ModalOverlay
Makes OverlayArea available in the ViewEnvironment, and uses it to drive calls to OverlayDialogHolder.onUpdateBounds.
Provides a LifecycleOwner per managed Dialog, and view persistence support, both for classic View.onSaveInstanceState and Jetpack SavedStateRegistry.
Supports recursion (e.g. nesting a smaller BodyAndOverlaysScreen in the body field of another) by sharing a single DialogCollator instance across multiple instances of LayeredDialogSessions. See DialogCollator for details.
Lifecycle of a managed Dialog
When update is called with an Overlay that is not Compatible with an existing Dialog, the appropriate OverlayDialogFactory instance is fetched from the ViewEnvironment. That factory builds (but does not show) a new Dialog, wrapped in an OverlayDialogHolder. The holder in turn is held by a DialogSession instance. There is a 1:1:1 relationship between the Dialog, the OverlayDialogHolder which can update it, and the DialogSession that manages its LifecycleOwner and persistence.
When a new DialogSession begins:
a LifecycleOwner is created as a child to the one provided by getParentLifecycleOwner
An appropriately scoped SavedStateRegistry is put in place, provided that onAttachedToWindow and onDetachedFromWindow are called from the like named methods of the nearest container View
Any available classic View state is restored to the new Dialog's content View tree, provided that onSaveInstanceState and onRestoreInstanceState are called from the like named methods of that container View
And the Dialog is shown
The DialogSession is maintained (and its two flavors of View state are recorded as prompted by the Android runtime) so long as update is called with a Compatible rendering.
When update is called without a matching Overlay, or the parent Lifecycle ends, the DialogSession ends, its LifecycleOwner is destroyed, and the Dialog is dismissed.
Parameters
made available to managed dialogs via the ViewEnvironmentKeycom.squareup.workflow1.ui.ViewEnvironmentKey, which drives OverlayDialogHolder.onUpdateBounds.
function to be called when a modal session starts -- that is, when update is first called with a ModalOverlay member, or called again with one after calls with none.
provides the LifecycleOwner to serve as an ancestor to those created for managed Dialogs.
Properties
While this is true, clients should ignore UI events targeting the body view beneath the Dialog windows they manage. It reflects that a ModalOverlay is (or soon will be) showing over the body.
Functions
Must be called whenever the owning view is attached to a window. Must eventually be matched with a call to onDetachedFromWindow.
Must be called whenever the owning view is detached from a window. Must be matched with a call to onAttachedToWindow.
To be called from a container view's View.onRestoreInstanceState.
To be called from a container view's View.onSaveInstanceState.