// Copyright 2014 The Flutter Authors. All rights reserved.

// Use of this source code is governed by a BSD-style license that can be

// found in the LICENSE file.

/// @docImport 'dart:ui';

/// @docImport 'package:flutter/cupertino.dart';

/// @docImport 'package:flutter/material.dart';

/// @docImport 'package:flutter/widgets.dart';

library;

import 'dart:math' as math;

import 'dart:ui'

as ui

show Image, ImageFilter, SemanticsHitTestBehavior, SemanticsInputType, TextHeightBehavior;

import 'package:flutter/animation.dart';

import 'package:flutter/foundation.dart';

import 'package:flutter/gestures.dart';

import 'package:flutter/rendering.dart';

import 'package:flutter/services.dart';

import 'binding.dart';

import 'debug.dart';

import 'framework.dart';

import 'indexed_stack.dart';

import 'localizations.dart';

import 'widget_span.dart';

export 'package:flutter/animation.dart';

export 'package:flutter/foundation.dart'

show ChangeNotifier, FlutterErrorDetails, Listenable, TargetPlatform, ValueNotifier;

export 'package:flutter/painting.dart';

export 'package:flutter/rendering.dart'

show

AlignmentGeometryTween,

AlignmentTween,

Axis,

BackdropKey,

BoxConstraints,

BoxConstraintsTransform,

CrossAxisAlignment,

CustomClipper,

CustomPainter,

CustomPainterSemantics,

DecorationPosition,

FlexFit,

FlowDelegate,

FlowPaintingContext,

FractionalOffsetTween,

HitTestBehavior,

ImageFilterConfig,

LayerLink,

MainAxisAlignment,

MainAxisSize,

MouseCursor,

MultiChildLayoutDelegate,

PaintingContext,

PointerCancelEvent,

PointerCancelEventListener,

PointerDownEvent,

PointerDownEventListener,

PointerEvent,

PointerMoveEvent,

PointerMoveEventListener,

PointerUpEvent,

PointerUpEventListener,

RelativeRect,

SemanticsBuilderCallback,

ShaderCallback,

ShapeBorderClipper,

SingleChildLayoutDelegate,

StackFit,

SystemMouseCursors,

TextOverflow,

ValueChanged,

ValueGetter,

WrapAlignment,

WrapCrossAlignment;

export 'package:flutter/services.dart' show AssetBundle;

// Examples can assume:

// class TestWidget extends StatelessWidget { const TestWidget({super.key}); @override Widget build(BuildContext context) => const Placeholder(); }

// late WidgetTester tester;

// late bool _visible;

// class Sky extends CustomPainter { @override void paint(Canvas c, Size s) {} @override bool shouldRepaint(Sky s) => false; }

// late BuildContext context;

// String userAvatarUrl = '';

// BIDIRECTIONAL TEXT SUPPORT

/// An [InheritedElement] that has hundreds of dependencies but will

/// infrequently change. This provides a performance tradeoff where building

/// the [Widget]s is faster but performing updates is slower.

///

/// | | _UbiquitousInheritedElement | InheritedElement |

/// |---------------------|------------------------------|------------------|

/// | insert (best case) | O(1) | O(1) |

/// | insert (worst case) | O(1) | O(n) |

/// | search (best case) | O(n) | O(1) |

/// | search (worst case) | O(n) | O(n) |

///

/// Insert happens when building the [Widget] tree, search happens when updating

/// [Widget]s.

class _UbiquitousInheritedElement extends InheritedElement {

/// Creates an element that uses the given widget as its configuration.

_UbiquitousInheritedElement(super.widget);

@override

void setDependencies(Element dependent, Object? value) {

// This is where the cost of [InheritedElement] is incurred during build

// time of the widget tree. Omitting this bookkeeping is where the

// performance savings come from.

assert(value == null);

}

@override

Object? getDependencies(Element dependent) {

return null;

}

@override

void notifyClients(InheritedWidget oldWidget) {

_recurseChildren(this, (Element element) {

if (element.doesDependOnInheritedElement(this)) {

notifyDependent(oldWidget, element);

}

});

}

static void _recurseChildren(Element element, ElementVisitor visitor) {

element.visitChildren((Element child) {

_recurseChildren(child, visitor);

});

visitor(element);

}

}

/// See also:

///

/// * [_UbiquitousInheritedElement], the [Element] for [_UbiquitousInheritedWidget].

abstract class _UbiquitousInheritedWidget extends InheritedWidget {

const _UbiquitousInheritedWidget({super.key, required super.child});

@override

InheritedElement createElement() => _UbiquitousInheritedElement(this);

}

/// A widget that determines the ambient directionality of text and

/// text-direction-sensitive render objects.

///

/// For example, [Padding] depends on the [Directionality] to resolve

/// [EdgeInsetsDirectional] objects into absolute [EdgeInsets] objects.

///

/// {@tool snippet}

///

/// This example uses a right-to-left [TextDirection] and draws a blue box with

/// a right margin of 8 pixels.

///

/// ```dart

/// Directionality(

/// textDirection: TextDirection.rtl,

/// child: Container(

/// margin: const EdgeInsetsDirectional.only(start: 8),

/// color: Colors.blue,

/// ),

/// )

/// ```

/// {@end-tool}

class Directionality extends _UbiquitousInheritedWidget {

/// Creates a widget that determines the directionality of text and

/// text-direction-sensitive render objects.

const Directionality({super.key, required this.textDirection, required super.child});

/// The text direction for this subtree.

final TextDirection textDirection;

/// The text direction from the closest instance of this class that encloses

/// the given context.

///

/// If there is no [Directionality] ancestor widget in the tree at the given

/// context, then this will throw a descriptive [FlutterError] in debug mode

/// and an exception in release mode.

///

/// Typical usage is as follows:

///

/// ```dart

/// TextDirection textDirection = Directionality.of(context);

/// ```

///

/// See also:

///

/// * [maybeOf], which will return null if no [Directionality] ancestor

/// widget is in the tree.

static TextDirection of(BuildContext context) {

assert(debugCheckHasDirectionality(context));

final Directionality widget = context.dependOnInheritedWidgetOfExactType<Directionality>()!;

return widget.textDirection;

}

/// The text direction from the closest instance of this class that encloses

/// the given context.

///

/// If there is no [Directionality] ancestor widget in the tree at the given

/// context, then this will return null.

///

/// Typical usage is as follows:

///

/// ```dart

/// TextDirection? textDirection = Directionality.maybeOf(context);

/// ```

///

/// See also:

///

/// * [of], which will throw if no [Directionality] ancestor widget is in the

/// tree.

static TextDirection? maybeOf(BuildContext context) {

final Directionality? widget = context.dependOnInheritedWidgetOfExactType<Directionality>();

return widget?.textDirection;

}

@override

bool updateShouldNotify(Directionality oldWidget) => textDirection != oldWidget.textDirection;

@override

void debugFillProperties(DiagnosticPropertiesBuilder properties) {

super.debugFillProperties(properties);

properties.add(EnumProperty<TextDirection>('textDirection', textDirection));

}

}

// PAINTING NODES

/// A widget that makes its child partially transparent.

///

/// This class paints its child into an intermediate buffer and then blends the

/// child back into the scene partially transparent.

///

/// For values of opacity other than 0.0 and 1.0, this class is relatively

/// expensive because it requires painting the child into an intermediate

/// buffer. For the value 0.0, the child is not painted at all. For the

/// value 1.0, the child is painted immediately without an intermediate buffer.

///

/// The presence of the intermediate buffer which has a transparent background

/// by default may cause some child widgets to behave differently. For example

/// a [BackdropFilter] child will only be able to apply its filter to the content

/// between this widget and the backdrop child and may require adjusting the

/// [BackdropFilter.blendMode] property to produce the desired results.

///

/// {@youtube 560 315 https://www.youtube.com/watch?v=9hltevOHQBw}

///

/// {@tool snippet}

///

/// This example shows some [Text] when the `_visible` member field is true, and

/// hides it when it is false:

///

/// ```dart

/// Opacity(

/// opacity: _visible ? 1.0 : 0.0,

/// child: const Text("Now you see me, now you don't!"),

/// )

/// ```

/// {@end-tool}

///

/// This is more efficient than adding and removing the child widget from the

/// tree on demand.

///

/// ## Performance considerations for opacity animation

///

/// Animating an [Opacity] widget directly causes the widget (and possibly its

/// subtree) to rebuild each frame, which is not very efficient. Consider using

/// one of these alternative widgets instead:

///

/// * [AnimatedOpacity], which uses an animation internally to efficiently

/// animate opacity.

/// * [FadeTransition], which uses a provided animation to efficiently animate

/// opacity.

///

/// ## Transparent image

///

/// If only a single [Image] or [Color] needs to be composited with an opacity

/// between 0.0 and 1.0, it's much faster to directly use them without [Opacity]

/// widgets.

///

/// For example, `Container(color: Color.fromRGBO(255, 0, 0, 0.5))` is much

/// faster than `Opacity(opacity: 0.5, child: Container(color: Colors.red))`.

///

/// {@tool snippet}

///

/// The following example draws an [Image] with 0.5 opacity without using

/// [Opacity]:

///

/// ```dart

/// Image.network(

/// 'https://raw.githubusercontent.com/flutter/assets-for-api-docs/main/packages/diagrams/assets/blend_mode_destination.jpeg',

/// color: const Color.fromRGBO(255, 255, 255, 0.5),

/// colorBlendMode: BlendMode.modulate

/// )

/// ```

/// {@end-tool}

///

/// Directly drawing an [Image] or [Color] with opacity is faster than using

/// [Opacity] on top of them because [Opacity] could apply the opacity to a

/// group of widgets and therefore a costly offscreen buffer will be used.

/// Drawing content into the offscreen buffer may also trigger render target

/// switches and such switching is particularly slow in older GPUs.

///

/// ## Hit testing

///

/// Setting the [opacity] to zero does not prevent hit testing from being applied

/// to the descendants of the [Opacity] widget. This can be confusing for the

/// user, who may not see anything, and may believe the area of the interface

/// where the [Opacity] is hiding a widget to be non-interactive.

///

/// With certain widgets, such as [Flow], that compute their positions only when

/// they are painted, this can actually lead to bugs (from unexpected geometry

/// to exceptions), because those widgets are not painted by the [Opacity]

/// widget at all when the [opacity] is zero.

///

/// To avoid such problems, it is generally a good idea to use an

/// [IgnorePointer] widget when setting the [opacity] to zero. This prevents

/// interactions with any children in the subtree.

///

/// See also:

///

/// * [Visibility], which can hide a child more efficiently (albeit less

/// subtly, because it is either visible or hidden, rather than allowing

/// fractional opacity values). Specifically, the [Visibility.maintain]

/// constructor is equivalent to using an opacity widget with values of

/// `0.0` or `1.0`.

/// * [ShaderMask], which can apply more elaborate effects to its child.

/// * [Transform], which applies an arbitrary transform to its child widget at

/// paint time.

/// * [SliverOpacity], the sliver version of this widget.

class Opacity extends SingleChildRenderObjectWidget {

/// Creates a widget that makes its child partially transparent.

///

/// The [opacity] argument must be between zero and one, inclusive.

const Opacity({

super.key,

required this.opacity,

this.alwaysIncludeSemantics = false,

super.child,

}) : assert(opacity >= 0.0 && opacity <= 1.0);

/// The fraction to scale the child's alpha value.

///

/// An opacity of one is fully opaque. An opacity of zero is fully transparent

/// (i.e., invisible).

///

/// Values one and zero are painted with a fast path. Other values require

/// painting the child into an intermediate buffer, which is expensive.

final double opacity;

/// Whether the semantic information of the children is always included.

///

/// Defaults to false.

///

/// When true, regardless of the opacity settings the child semantic

/// information is exposed as if the widget were fully visible. This is

/// useful in cases where labels may be hidden during animations that

/// would otherwise contribute relevant semantics.

final bool alwaysIncludeSemantics;

@override

RenderOpacity createRenderObject(BuildContext context) {

return RenderOpacity(opacity: opacity, alwaysIncludeSemantics: alwaysIncludeSemantics);

}

@override

void updateRenderObject(BuildContext context, RenderOpacity renderObject) {

renderObject

..opacity = opacity

..alwaysIncludeSemantics = alwaysIncludeSemantics;

}

@override

void debugFillProperties(DiagnosticPropertiesBuilder properties) {

super.debugFillProperties(properties);

properties.add(DoubleProperty('opacity', opacity));

properties.add(

FlagProperty(

'alwaysIncludeSemantics',

value: alwaysIncludeSemantics,

ifTrue: 'alwaysIncludeSemantics',

),

);

}

}

/// A widget that applies a mask generated by a [Shader] to its child.

///

/// For example, [ShaderMask] can be used to gradually fade out the edge

/// of a child by using a [RadialGradient] mask.

///

/// {@youtube 560 315 https://www.youtube.com/watch?v=7sUL66pTQ7Q}

///

/// {@tool snippet}

///

/// This example makes the text look like it is on fire:

///

/// ```dart

/// ShaderMask(

/// shaderCallback: (Rect bounds) {

/// return RadialGradient(

/// center: Alignment.topLeft,

/// radius: 1.0,

/// colors: <Color>[Colors.yellow, Colors.deepOrange.shade900],

/// tileMode: TileMode.mirror,

/// ).createShader(bounds);

/// },

/// child: const Text(

/// "I'm burning the memories",

/// style: TextStyle(color: Colors.white),

/// ),

/// )

/// ```

/// {@end-tool}

///

/// See also:

///

/// * [Opacity], which can apply a uniform alpha effect to its child.

/// * [CustomPaint], which lets you draw directly on the canvas.

/// * [DecoratedBox], for another approach at decorating child widgets.

/// * [BackdropFilter], which applies an image filter to the background.

class ShaderMask extends SingleChildRenderObjectWidget {

/// Creates a widget that applies a mask generated by a [Shader] to its child.

const ShaderMask({

super.key,

required this.shaderCallback,

this.blendMode = BlendMode.modulate,

super.child,

});

/// Called to create the [dart:ui.Shader] that generates the mask.

///

/// The shader callback is called with the current size of the child so that

/// it can customize the shader to the size and location of the child.

///

/// Typically this will use a [LinearGradient], [RadialGradient], or

/// [SweepGradient] to create the [dart:ui.Shader], though the

/// [dart:ui.ImageShader] class could also be used.

final ShaderCallback shaderCallback;

/// The [BlendMode] to use when applying the shader to the child.

///

/// The default, [BlendMode.modulate], is useful for applying an alpha blend

/// to the child. Other blend modes can be used to create other effects.

final BlendMode blendMode;

@override

RenderShaderMask createRenderObject(BuildContext context) {

return RenderShaderMask(shaderCallback: shaderCallback, blendMode: blendMode);

}

@override

void updateRenderObject(BuildContext context, RenderShaderMask renderObject) {

renderObject

..shaderCallback = shaderCallback

..blendMode = blendMode;

}

}

/// A widget that establishes a shared backdrop layer for all child [BackdropFilter]

/// widgets that opt into using it.

///

/// Sharing a backdrop filter layer will improve the performance of multiple

/// backdrop filters. To opt into using a shared [BackdropGroup], the special

/// [BackdropFilter.grouped] constructor must be used.

class BackdropGroup extends InheritedWidget {

/// Create a new [BackdropGroup] widget.

BackdropGroup({super.key, required super.child, BackdropKey? backdropKey})

: backdropKey = backdropKey ?? BackdropKey();

/// The backdrop key this backdrop group will use with shared child layers.

final BackdropKey backdropKey;

@override

bool updateShouldNotify(covariant BackdropGroup oldWidget) {

return oldWidget.backdropKey != backdropKey;

}

/// Look up the nearest [BackdropGroup], or `null` if there is not one.

static BackdropGroup? of(BuildContext context) {

return context.dependOnInheritedWidgetOfExactType<BackdropGroup>();

}

}

/// A widget that applies a filter to the existing painted content and then

/// paints [child].

///

/// The filter will be applied to all the area within its parent or ancestor

/// widget's clip. If there's no clip, the filter will be applied to the full

/// screen.

///

/// The results of the filter will be blended back into the background using

/// the [blendMode] parameter.

/// {@template flutter.widgets.BackdropFilter.blendMode}

/// The only value for [blendMode] that is supported on all platforms is

/// [BlendMode.srcOver] which works well for most scenes. But that value may

/// produce surprising results when a parent of the [BackdropFilter] uses a

/// temporary buffer, or save layer, as does an [Opacity] widget. In that

/// situation, a value of [BlendMode.src] can produce more pleasing results.

/// {@endtemplate}

///

/// Multiple backdrop filters can be combined into a single rendering operation

/// by the Flutter engine if these backdrop filters widgets all share a common

/// [BackdropKey]. The backdrop key uniquely identifies the input for a backdrop

/// filter, and when shared, indicates the filtering can be performed once. This

/// can significantly reduce the overhead of using multiple backdrop filters in

/// a scene. The key can either be provided manually via the `backdropKey`

/// constructor parameter or looked up from a [BackdropGroup] inherited widget

/// via the `.grouped` constructor.

///

/// Backdrop filters that overlap with each other should not use the same

/// backdrop key, otherwise the results may look as if only one filter is

/// applied in the overlapping regions.

///

/// The following snippet demonstrates how to use the backdrop key to allow each

/// list item to have an efficient blur. The engine will perform only one

/// backdrop blur but the results will be visually identical to multiple blurs.

///

/// ```dart

/// Widget build(BuildContext context) {

/// return BackdropGroup(

/// child: ListView.builder(

/// itemCount: 60,

/// itemBuilder: (BuildContext context, int index) {

/// return ClipRect(

/// child: BackdropFilter.grouped(

/// filter: ui.ImageFilter.blur(

/// sigmaX: 40,

/// sigmaY: 40,

/// ),

/// child: Container(

/// color: Colors.black.withValues(alpha: 0.2),

/// height: 200,

/// child: const Text('Blur item'),

/// ),

/// ),

/// );

/// }

/// ),

/// );

/// }

/// ```

///

/// {@youtube 560 315 https://www.youtube.com/watch?v=dYRs7Q1vfYI}

///

/// {@tool snippet}

///

/// If the [BackdropFilter] needs to be applied to an area that exactly matches

/// its child, wraps the [BackdropFilter] with a clip widget that clips exactly

/// to that child.

///

/// ```dart

/// Stack(

/// fit: StackFit.expand,

/// children: <Widget>[

/// Text('0' * 10000),

/// Center(

/// child: ClipRect( // <-- clips to the 200x200 [Container] below

/// child: BackdropFilter(

/// filter: ui.ImageFilter.blur(

/// sigmaX: 5.0,

/// sigmaY: 5.0,

/// ),

/// child: Container(

/// alignment: Alignment.center,

/// width: 200.0,

/// height: 200.0,

/// child: const Text('Hello World'),

/// ),

/// ),

/// ),

/// ),

/// ],

/// )

/// ```

/// {@end-tool}

///

/// This effect is relatively expensive, especially if the filter is non-local,

/// such as a blur.

///

/// If all you want to do is apply an [ImageFilter] to a single widget

/// (as opposed to applying the filter to everything _beneath_ a widget), use

/// [ImageFiltered] instead. For that scenario, [ImageFiltered] is both

/// easier to use and less expensive than [BackdropFilter].

///

/// {@tool snippet}

///

/// This example shows how the common case of applying a [BackdropFilter] blur

/// to a single sibling can be replaced with an [ImageFiltered] widget. This code

/// is generally simpler and the performance will be improved dramatically for

/// complex filters like blurs.

///

/// The implementation below is unnecessarily expensive.

///

/// ```dart

/// Widget buildBackdrop() {

/// return Stack(

/// children: <Widget>[

/// Positioned.fill(child: Image.asset('image.png')),

/// Positioned.fill(

/// child: BackdropFilter(

/// filter: ui.ImageFilter.blur(sigmaX: 6, sigmaY: 6),

/// ),

/// ),

/// ],

/// );

/// }

/// ```

/// {@end-tool}

/// {@tool snippet}

///

/// Instead consider the following approach which directly applies a blur

/// to the child widget.

///

/// ```dart

/// Widget buildFilter() {

/// return ImageFiltered(

/// imageFilter: ui.ImageFilter.blur(sigmaX: 6, sigmaY: 6),

/// child: Image.asset('image.png'),

/// );

/// }

/// ```

/// {@end-tool}

///

/// See also:

///

/// * [ImageFiltered], which applies an [ImageFilter] to its child.

/// * [DecoratedBox], which draws a background under (or over) a widget.

/// * [Opacity], which changes the opacity of the widget itself.

/// * https://flutter.dev/go/ios-platformview-backdrop-filter-blur for details and restrictions when an iOS PlatformView needs to be blurred.

class BackdropFilter extends SingleChildRenderObjectWidget {

/// Creates a backdrop filter.

///

/// The [blendMode] argument will default to [BlendMode.srcOver] and must not be

/// null if provided.

///

/// Exactly one of [filter] or [filterConfig] must be provided.

/// Providing both or neither will result in an assertion error.

const BackdropFilter({

super.key,

this.filter,

this.filterConfig,

super.child,

this.blendMode = BlendMode.srcOver,

this.enabled = true,

this.backdropGroupKey,

}) : assert(

filter != null || filterConfig != null,

'Either filter or filterConfig must be provided.',

),

assert(

filter == null || filterConfig == null,

'Cannot provide both a filter and a filterConfig.',

),

_useSharedKey = false;

/// Creates a backdrop filter that groups itself with the nearest parent

/// [BackdropGroup].

///

/// The [blendMode] argument will default to [BlendMode.srcOver] and must not be

/// null if provided.

///

/// This constructor will automatically look up the nearest [BackdropGroup]

/// and will share the backdrop input with sibling and child [BackdropFilter]

/// widgets.

///

/// Exactly one of [filter] or [filterConfig] must be provided.

/// Providing both or neither will result in an assertion error.

const BackdropFilter.grouped({

super.key,

this.filter,

this.filterConfig,

super.child,

this.blendMode = BlendMode.srcOver,

this.enabled = true,

}) : assert(

filter != null || filterConfig != null,

'Either filter or filterConfig must be provided.',

),

assert(

filter == null || filterConfig == null,

'Cannot provide both a filter and a filterConfig.',

),

backdropGroupKey = null,

_useSharedKey = true;

/// The image filter to apply to the existing painted content before painting the child.

///

/// For example, consider using [ImageFilter.blur] to create a backdrop

/// blur effect.

///

/// The [filter] parameter is equivalent to [filterConfig] (with the help of

/// the [ImageFilterConfig.new] constructor), except for features only

/// supported by [ImageFilterConfig] (such as the `bounds` parameter in

/// [ImageFilterConfig.blur]).

final ui.ImageFilter? filter;

/// The configuration for the image filter to apply to the existing painted content.

///

/// For example, consider using [ImageFilterConfig.blur] to create a backdrop

/// blur effect.

///

/// The [filterConfig] parameter is equivalent to [filter] (with the help of

/// the [ImageFilterConfig.new] constructor), except for features only

/// supported by [ImageFilterConfig] (such as the `bounds` parameter in

/// [ImageFilterConfig.blur]).

final ImageFilterConfig? filterConfig;

/// The blend mode to use to apply the filtered background content onto the background

/// surface.

///

/// {@macro flutter.widgets.BackdropFilter.blendMode}

final BlendMode blendMode;

/// Whether or not to apply the backdrop filter operation to the child of this

/// widget.

///

/// Prefer setting enabled to `false` instead of creating a "no-op" filter

/// type for performance reasons.

final bool enabled;

/// The [BackdropKey] that identifies the backdrop this filter will apply to.

///

/// The default value for the backdrop key is `null`.

final BackdropKey? backdropGroupKey;

// Whether to look up the [backdropKey] from a parent [BackdropGroup].

final bool _useSharedKey;

BackdropKey? _getBackdropGroupKey(BuildContext context) {

if (_useSharedKey) {

return BackdropGroup.of(context)?.backdropKey;

}

return backdropGroupKey;

}

ImageFilterConfig get _effectiveFilterConfig {

return filterConfig ?? ImageFilterConfig(filter!);

}

@override

RenderBackdropFilter createRenderObject(BuildContext context) {

return RenderBackdropFilter(

filterConfig: _effectiveFilterConfig,

blendMode: blendMode,

enabled: enabled,

backdropKey: _getBackdropGroupKey(context),

);

}

@override

void updateRenderObject(BuildContext context, RenderBackdropFilter renderObject) {

renderObject

..filterConfig = _effectiveFilterConfig

..enabled = enabled

..blendMode = blendMode

..backdropKey = _getBackdropGroupKey(context);

}

@override

void debugFillProperties(DiagnosticPropertiesBuilder properties) {

super.debugFillProperties(properties);

properties.add(DiagnosticsProperty<ui.ImageFilter>('filter', filter, defaultValue: null));

properties.add(

DiagnosticsProperty<ImageFilterConfig>('filterConfig', filterConfig, defaultValue: null),

);

properties.add(EnumProperty<BlendMode>('blendMode', blendMode));

properties.add(FlagProperty('enabled', value: enabled, ifTrue: 'enabled'));

}

}

/// A widget that provides a canvas on which to draw during the paint phase.

///

/// When asked to paint, [CustomPaint] first asks its [painter] to paint on the

/// current canvas, then it paints its child, and then, after painting its

/// child, it asks its [foregroundPainter] to paint. The coordinate system of the

/// canvas matches the coordinate system of the [CustomPaint] object. The

/// painters are expected to paint within a rectangle starting at the origin and

/// encompassing a region of the given size. (If the painters paint outside

/// those bounds, there might be insufficient memory allocated to rasterize the

/// painting commands and the resulting behavior is undefined.) To enforce

/// painting within those bounds, consider wrapping this [CustomPaint] with a

/// [ClipRect] widget.

///

/// Painters are implemented by subclassing [CustomPainter].

///

/// {@youtube 560 315 https://www.youtube.com/watch?v=kp14Y4uHpHs}

///

/// Because custom paint calls its painters during paint, you cannot call

/// `setState` or `markNeedsLayout` during the callback (the layout for this

/// frame has already happened).

///

/// Custom painters normally size themselves to their [child]. If they do not

/// have a child, they attempt to size themselves to the specified [size], which

/// defaults to [Size.zero]. The parent [may enforce constraints on this

/// size](https://docs.flutter.dev/ui/layout/constraints).

///

/// The [isComplex] and [willChange] properties are hints to the compositor's

/// raster cache.

///

/// {@tool snippet}

///

/// This example shows how the sample custom painter shown at [CustomPainter]

/// could be used in a [CustomPaint] widget to display a background to some

/// text.

///

/// ```dart

/// CustomPaint(

/// painter: Sky(),

/// child: const Center(

/// child: Text(

/// 'Once upon a time...',

/// style: TextStyle(

/// fontSize: 40.0,

/// fontWeight: FontWeight.w900,

/// color: Color(0xFFFFFFFF),

/// ),

/// ),

/// ),

/// )

/// ```

/// {@end-tool}

///

/// See also:

///

/// * [CustomPainter], the class to extend when creating custom painters.

/// * [Canvas], the class that a custom painter uses to paint.

class CustomPaint extends SingleChildRenderObjectWidget {

/// Creates a widget that delegates its painting.

const CustomPaint({

super.key,

this.painter,

this.foregroundPainter,

this.size = Size.zero,

this.isComplex = false,

this.willChange = false,

super.child,

}) : assert(painter != null || foregroundPainter != null || (!isComplex && !willChange));

/// The painter that paints before the children.

final CustomPainter? painter;

/// The painter that paints after the children.

final CustomPainter? foregroundPainter;

/// The size that this [CustomPaint] should aim for, given the layout

/// constraints, if there is no child.

///

/// Defaults to [Size.zero].

///

/// If there's a child, this is ignored, and the size of the child is used

/// instead.

final Size size;

/// Whether the painting is complex enough to benefit from caching.

///

/// The compositor contains a raster cache that holds bitmaps of layers in

/// order to avoid the cost of repeatedly rendering those layers on each

/// frame. If this flag is not set, then the compositor will apply its own

/// heuristics to decide whether the layer containing this widget is complex

/// enough to benefit from caching.

///

/// This flag can't be set to true if both [painter] and [foregroundPainter]

/// are null because this flag will be ignored in such case.

final bool isComplex;

/// Whether the raster cache should be told that this painting is likely

/// to change in the next frame.

///

/// This hint tells the compositor not to cache the layer containing this

/// widget because the cache will not be used in the future. If this hint is

/// not set, the compositor will apply its own heuristics to decide whether

/// the layer is likely to be reused in the future.

///

/// This flag can't be set to true if both [painter] and [foregroundPainter]

/// are null because this flag will be ignored in such case.

final bool willChange;

@override

RenderCustomPaint createRenderObject(BuildContext context) {

return RenderCustomPaint(

painter: painter,

foregroundPainter: foregroundPainter,

preferredSize: size,

isComplex: isComplex,

willChange: willChange,

);

}

@override

void updateRenderObject(BuildContext context, RenderCustomPaint renderObject) {

renderObject

..painter = painter

..foregroundPainter = foregroundPainter

..preferredSize = size

..isComplex = isComplex

..willChange = willChange;

}

@override

void didUnmountRenderObject(RenderCustomPaint renderObject) {

renderObject

..painter = null

..foregroundPainter = null;

}

}

/// A widget that clips its child using a rectangle.

///

/// By default, [ClipRect] prevents its child from painting outside its

/// bounds, but the size and location of the clip rect can be customized using a

/// custom [clipper].

///

/// [ClipRect] is commonly used with these widgets, which commonly paint outside

/// their bounds:

///

/// * [CustomPaint]

/// * [CustomSingleChildLayout]

/// * [CustomMultiChildLayout]

/// * [Align] and [Center] (e.g., if [Align.widthFactor] or

/// [Align.heightFactor] is less than 1.0).

/// * [OverflowBox]

/// * [SizedOverflowBox]

///

/// {@tool snippet}

///

/// For example, by combining a [ClipRect] with an [Align], one can show just

/// the top half of an [Image]:

///

/// ```dart

/// ClipRect(

/// child: Align(

/// alignment: Alignment.topCenter,

/// heightFactor: 0.5,

/// child: Image.network(userAvatarUrl),

/// ),

/// )

/// ```

/// {@end-tool}

///

/// See also:

///

/// * [CustomClipper], for information about creating custom clips.

/// * [ClipRRect], for a clip with rounded corners.

/// * [ClipOval], for an elliptical clip.

/// * [ClipPath], for an arbitrarily shaped clip.

class ClipRect extends SingleChildRenderObjectWidget {

/// Creates a rectangular clip.

///

/// If [clipper] is null, the clip will match the layout size and position of

/// the child.

///

/// If [clipBehavior] is [Clip.none], no clipping will be applied.

const ClipRect({super.key, this.clipper, this.clipBehavior = Clip.hardEdge, super.child});

/// If non-null, determines which clip to use.

final CustomClipper<Rect>? clipper;

/// {@macro flutter.rendering.ClipRectLayer.clipBehavior}

///

/// Defaults to [Clip.hardEdge].

final Clip clipBehavior;

@override

RenderClipRect createRenderObject(BuildContext context) {

return RenderClipRect(clipper: clipper, clipBehavior: clipBehavior);

}

@override

void updateRenderObject(BuildContext context, RenderClipRect renderObject) {

renderObject

..clipper = clipper

..clipBehavior = clipBehavior;

}

@override

void didUnmountRenderObject(RenderClipRect renderObject) {

renderObject.clipper = null;

}

@override

void debugFillProperties(DiagnosticPropertiesBuilder properties) {

super.debugFillProperties(properties);

properties.add(

DiagnosticsProperty<CustomClipper<Rect>>('clipper', clipper, defaultValue: null),

);

}

}

/// A widget that clips its child using a rounded rectangle.

///

/// By default, [ClipRRect] uses its own bounds as the base rectangle for the

/// clip, but the size and location of the clip can be customized using a custom

/// [clipper].

///

/// {@youtube 560 315 https://www.youtube.com/watch?v=eI43jkQkrvs}

///