FOverlay class

A low-level overlay primitive that composites content relative to a child widget using Positioned/ AnimatedPositioneds similar to a Stack.

Unlike a Stack, its children can overflow outside of the bounds and still receive hit events. Since the children are rendered in an overlay, they will not be painted over by widgets in the same layer as the builder/child.

FOverlay(
  control: .managed(controller: controller),
  overlay: [
    Positioned(
      top: -40, // 40px above the child's top edge
      left: 0,
      child: Text('Overlay'),
    ),
  ],
  child: const SizedBox.square(dimension: 40),
)

Overlay positioning & child resizing

As the overlay is laid out before the child, it will be positioned based on the previous frame's child size. Resizing a child while showing the Positioned overlay widgets may cause them to flicker. To avoid this, do not use Positioned.right and Positioned.bottom in conjunction with a resizing child.

// Bad - bottom depends on stale child height, causing flicker.
FOverlay(
  overlay: [
    Positioned(
      bottom: -22,
      child: handle,
    ),
  ],
  child: child,
)

// Good - use top with a known child height since the overlay's origin tracks the child.
FOverlay(
  overlay: [
    Positioned(
      top: childHeight - 22,
      child: handle,
    ),
  ],
  child: SizedBox(height: childHeight, child: child),
)

See:

FPortal for a higher-level overlay with anchor alignment, overflow handling, and spacing.
OverlayPortalController for controlling the overlay's visibility.

Inheritance

Constructors

FOverlay({required List<Widget> overlay, FOverlayControl control = const .managed(), FOverlayBuilder overlayBuilder = defaultOverlayBuilder, ValueWidgetBuilder<OverlayPortalController> builder = defaultBuilder, Widget? child, Key? key}): Creates a low-level overlay.
const

Properties

builder → ValueWidgetBuilder<OverlayPortalController>: An optional builder for the child widget.
final
child → Widget?: The child widget that the overlay is relative to.
final
control → FOverlayControl: The control for showing/hiding the overlay.
final
hashCode → int: The hash code for this object.
no setterinherited
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
overlay → List<Widget>: The widgets to overlay on the child.
final
overlayBuilder → FOverlayBuilder: A builder that transforms overlay widgets before they are displayed.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<FOverlay>: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
override
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

defaultBuilder(BuildContext _, OverlayPortalController _, Widget? child) → Widget: The default builder that returns the child as-is.
defaultOverlayBuilder(BuildContext _, OverlayPortalController _, RenderBox? _, List<Widget> overlay) → List<Widget>: The default overlay builder that returns the overlay widgets as-is.