UiPageScaffold class

Preferred page shell: coordinates background, top/bottom bars, safe viewport policy, and system bar syncing in a single widget.

Defaults are tuned for production use:

  • Background comes from UiThemeTokens.colors.background.
  • Scroll fade is enabled by default.
  • Top and bottom system insets are moved into the faded body layer so the page remains vertically edge-to-edge.
  • Left and right system insets remain physical safe-area padding for landscape notches and rounded display corners.
  • Status/navigation bar icons sync to the page background so they stay legible when the theme flips between light and dark.

Wrap forms that present a keyboard in safeViewportMode: UiSafeViewportMode.keyboardAware so the composer stays above the keyboard without double-stacking the home-indicator inset. Screens that do their own inset management can opt out with UiSafeViewportMode.none and syncSystemBars: false.

Inheritance

Constructors

UiPageScaffold({Key? key, required Widget body, Widget? topBar, Widget? bottomBar, Color? backgroundColor, UiSafeViewportMode safeViewportMode = UiSafeViewportMode.all, EdgeInsets safeAreaMinimum = EdgeInsets.zero, SystemUiOverlayStyle? systemOverlayStyle, bool syncSystemBars = true, bool leftSafeInset = true, bool rightSafeInset = true, bool showTopDivider = false, bool showBottomDivider = false, bool paintTopInsetWithTopBar = false, Color? topInsetColor, bool scrollFade = true, Color? scrollFadeBackgroundColor, bool scrollFadeTop = true, bool scrollFadeBottom = true, double scrollFadeExtent = 128, double scrollFadeWideExtent = 72, double scrollFadeBottomExtent = 48, double scrollFadeHorizontalInset = 0, double scrollFadeMaxOpacity = 0.84, bool scrollFadeUsesSafeArea = true, bool resizeBodyForKeyboard = false, Future<void> onRefresh()?, UiRefresherController? refreshController, UiRefreshIndicatorBuilder? refreshIndicatorBuilder, ValueChanged<UiRefreshStatus>? onRefreshStatusChanged, UiRefreshErrorCallback? onRefreshError, bool refreshEnabled = true, double refreshEdgeOffset = 0})
const

Properties

backgroundColor → Color?
Page background. Defaults to UiThemeTokens.colors.background.
final
body → Widget
final
bottomBar → Widget?
final
hashCode → int
The hash code for this object.
no setterinherited
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
leftSafeInset → bool
final
onRefresh → Future<void> Function()?
Enables page-owned pull-to-refresh for the vertical scrollable in body.
final
onRefreshError → UiRefreshErrorCallback?
Receives errors thrown by onRefresh.
final
onRefreshStatusChanged → ValueChanged<UiRefreshStatus>?
Reports lifecycle changes from the page-owned refresher.
final
paintTopInsetWithTopBar → bool
Paint the status-bar safe inset using a dedicated surface color, typically matching the top bar.
final
refreshController → UiRefresherController?
Optional controller for the page-owned refresher.
final
refreshEdgeOffset → double
Additional spacing below the physical top safe inset.
final
refreshEnabled → bool
Whether page-owned pull-to-refresh is interactive.
final
refreshIndicatorBuilder → UiRefreshIndicatorBuilder?
Optional replacement for the page-owned refresh indicator.
final
resizeBodyForKeyboard → bool
Reduces the body's layout height by the live keyboard inset.
final
rightSafeInset → bool
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
safeAreaMinimum → EdgeInsets
Minimum inset enforced by the safe viewport even when the system reports zero padding (e.g. desktop / emulated devices).
final
safeViewportMode → UiSafeViewportMode
How insets are applied around body. Defaults to UiSafeViewportMode.all. See UiSafeViewportMode.
final
scrollFade → bool
Applies a soft top/bottom edge mask to the page body.
final
scrollFadeBackgroundColor → Color?
Surface color sampled by the edge fade.
final
scrollFadeBottom → bool
Paint the fade at the bottom edge of body.
final
scrollFadeBottomExtent → double
Physical fade distance at the bottom edge. Kept shorter than the top by default so resting content is not unnecessarily veiled.
final
scrollFadeExtent → double
Physical fade distance in logical pixels.
final
scrollFadeHorizontalInset → double
Optional horizontal inset for the fade overlay.
final
scrollFadeMaxOpacity → double
Maximum opacity used at the outer fade edge.
final
scrollFadeTop → bool
Paint the fade at the top edge of body. Disable this when an in-scroll sticky region owns the transition into scrolling content.
final
scrollFadeUsesSafeArea → bool
Moves top/bottom safe-area padding into the faded body layer.
final
scrollFadeWideExtent → double
Top fade distance used on tablet and desktop viewports.
final
showBottomDivider → bool
Whether to draw a UiDivider between the body and the bottom bar.
final
showTopDivider → bool
Whether to draw a UiDivider between the top bar and the body.
final
syncSystemBars → bool
Install a UiSystemBars annotation above the scaffold. Default true — set false if an ancestor already owns system-bar styling.
final
systemOverlayStyle → SystemUiOverlayStyle?
Explicit overlay style. Usually leave null and let UiSystemBars infer icon brightness from backgroundColor.
final
topBar → Widget?
final
topInsetColor → Color?
Color used when paintTopInsetWithTopBar is true.
final

Methods

build(BuildContext context) → Widget
Describes the part of the user interface represented by this widget.
override
createElement() → StatelessElement
Creates a StatelessElement to manage this widget's location in the tree.
inherited
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.
inherited
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