OverlayDialogFactory

Factory for Dialog instances that can show renderings of type OverlayT. Most easily implemented using the ScreenOverlay interface to define the Dialog contentView, and calling the asDialogHolderWithContent extension function to set it.

To really minimize boilerplate, have your rendering classes implement AndroidOverlay to directly associate them with an appropriate OverlayDialogFactory.

e.g., this is all that is required to define a new style of dialog ready for use in the overlays list of BodyAndOverlaysScreen:

data class MyFancyModal(
  override val content: C
): ScreenOverlay, ModalOverlay, AndroidOverlay> {
  override fun  map(transform: (C) -> D) = MyFancyModal(transform(content))

  override val dialogFactory = OverlayDialogFactory> { r, e, c ->
    AppCompatDialog(c).asDialogHolderWithContent(r, e)
  }
}

For more flexibility, and to avoid coupling your workflow directly to the Android runtime, see ViewRegistry.

Details of Dialog management

There is a lot of machinery provided to give control over the placement of Dialog windows, and to ensure that ModalOverlay dialogs behave as expected (i.e., that events in the Activity window are blocked the instant a modal Dialog is shown).

To support the bounds restricting behavior described in the kdoc of BodyAndOverlaysScreen we provide an OverlayArea value in the ViewEnvironment, which holds the bounds of the view created to display the BodyAndOverlaysScreen.body. Well behaved dialogs created to display members of BodyAndOverlaysScreen.overlays restrict themselves to those limits.

Another ViewEnvironment value is maintained to support modality: CoveredByModal. When this value is true, it indicates that a dialog window driven by a ModalOverlay is in play over the view, or is about to be, and so touch and click events should be ignored. This is necessary because there is a long period after a call to Dialog.show before the new Dialog window will start intercepting events -- an issue that has preoccupied Square for a very long time.) The default container view driven by BodyAndOverlaysScreen automatically honors CoveredByModal.

All of this is driven by the LayeredDialogSessions support class, which can also be used to create custom BodyAndOverlaysScreen container views. To put such a custom container in play, see OverlayDialogFactoryFinder.

It is important to note that the modal behavior described here is all keyed to the ModalOverlay interface, not its parent type Overlay. Rendering types that declare the latter but not the former can be used to create dialogs for non-modal windows like toasts and tool tips.