CupertinoDynamicColor class

A Color subclass that represents a family of colors, and the correct effective color in the color family.

When used as a regular color, CupertinoDynamicColor is equivalent to the effective color (i.e. CupertinoDynamicColor.value will come from the effective color), which is determined by the BuildContext it is last resolved against. If it has never been resolved, the light, normal contrast, base elevation variant CupertinoDynamicColor.color will be the default effective color.

Sometimes manually resolving a CupertinoDynamicColor is not necessary, because the Cupertino Library provides built-in support for it.

Using CupertinoDynamicColor in a Cupertino widget

When a Cupertino widget is provided with a CupertinoDynamicColor, either directly in its constructor, or from an InheritedWidget it depends on (for example, DefaultTextStyle), the widget will automatically resolve the color using CupertinoDynamicColor.resolve against its own BuildContext, on a best-effort basis.

By default a CupertinoButton has no background color. The following sample code shows how to build a CupertinoButton that appears white in light mode, and changes automatically to black in dark mode.
link
CupertinoButton(
  // CupertinoDynamicColor works out of box in a CupertinoButton.
  color: const CupertinoDynamicColor.withBrightness(
    color: CupertinoColors.white,
    darkColor: CupertinoColors.black,
  ),
  onPressed: () { },
  child: child,
)

Using a CupertinoDynamicColor from a CupertinoTheme

When referring to a CupertinoTheme color, generally the color will already have adapted to the ambient BuildContext, because CupertinoTheme.of implicitly resolves all the colors used in the retrieved CupertinoThemeData, before returning it.

The following code sample creates a Container with the primaryColor of the current theme. If primaryColor is a CupertinoDynamicColor, the container will be adaptive, thanks to CupertinoTheme.of: it will switch to primaryColor's dark variant once dark mode is turned on, and turns to primaryColor`'s high contrast variant when MediaQueryData.highContrast is requested in the ambient MediaQuery, etc.
link
Container(
  // Container is not a Cupertino widget, but CupertinoTheme.of implicitly
  // resolves colors used in the retrieved CupertinoThemeData.
  color: CupertinoTheme.of(context).primaryColor,
)

Manually Resolving a CupertinoDynamicColor

When used to configure a non-Cupertino widget, or wrapped in an object opaque to the receiving Cupertino component, a CupertinoDynamicColor may need to be manually resolved using CupertinoDynamicColor.resolve, before it can used to paint. For example, to use a custom Border in a CupertinoNavigationBar, the colors used in the Border have to be resolved manually before being passed to CupertinoNavigationBar's constructor.

The following code samples demonstrate two cases where you have to manually resolve a CupertinoDynamicColor.
link
CupertinoNavigationBar(
  // CupertinoNavigationBar does not know how to resolve colors used in
  // a Border class.
  border: Border(
    bottom: BorderSide(
      color: CupertinoDynamicColor.resolve(CupertinoColors.systemBlue, context),
    ),
  ),
)

// ...

Container(
  // Container is not a Cupertino widget.
  color: CupertinoDynamicColor.resolve(CupertinoColors.systemBlue, context),
)

See also:

Inheritance
Mixed in types
Annotations

Constructors

CupertinoDynamicColor({String? debugLabel, required Color color, required Color darkColor, required Color highContrastColor, required Color darkHighContrastColor, required Color elevatedColor, required Color darkElevatedColor, required Color highContrastElevatedColor, required Color darkHighContrastElevatedColor})
Creates an adaptive Color that changes its effective color based on the BuildContext given. The default effective color is color.
const
CupertinoDynamicColor.withBrightness({String? debugLabel, required Color color, required Color darkColor})
Creates an adaptive Color that changes its effective color based on the given BuildContext's brightness (from MediaQueryData.platformBrightness or CupertinoThemeData.brightness). The default effective color is color.
const
CupertinoDynamicColor.withBrightnessAndContrast({String? debugLabel, required Color color, required Color darkColor, required Color highContrastColor, required Color darkHighContrastColor})
Creates an adaptive Color that changes its effective color based on the given BuildContext's brightness (from MediaQueryData.platformBrightness or CupertinoThemeData.brightness) and accessibility contrast setting (MediaQueryData.highContrast). The default effective color is color.
const

Properties

alpha int
The alpha channel of this color in an 8 bit value.
no setterinherited
blue int
The blue channel of this color in an 8 bit value.
no setterinherited
color Color
The color to use when the BuildContext implies a combination of light mode, normal contrast, and base interface elevation.
final
darkColor Color
The color to use when the BuildContext implies a combination of dark mode, normal contrast, and base interface elevation.
final
darkElevatedColor Color
The color to use when the BuildContext implies a combination of dark mode, normal contrast, and elevated interface elevation.
final
darkHighContrastColor Color
The color to use when the BuildContext implies a combination of dark mode, high contrast, and base interface elevation.
final
darkHighContrastElevatedColor Color
The color to use when the BuildContext implies a combination of dark mode, high contrast, and elevated interface elevation.
final
elevatedColor Color
The color to use when the BuildContext implies a combination of light mode, normal contrast, and elevated interface elevation.
final
green int
The green channel of this color in an 8 bit value.
no setterinherited
hashCode int
The hash code for this object.
no setteroverride
highContrastColor Color
The color to use when the BuildContext implies a combination of light mode, high contrast, and base interface elevation.
final
highContrastElevatedColor Color
The color to use when the BuildContext implies a combination of light mode, high contrast, and elevated interface elevation.
final
opacity double
The alpha channel of this color as a double.
no setterinherited
red int
The red channel of this color in an 8 bit value.
no setterinherited
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
value int
A 32 bit value representing this color.
no setteroverride

Methods

computeLuminance() double
Returns a brightness value between 0 for darkest and 1 for lightest.
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
resolveFrom(BuildContext context) CupertinoDynamicColor
Resolves this CupertinoDynamicColor using the provided BuildContext.
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.
override
toStringShort() String
A brief description of this object, usually just the runtimeType and the hashCode.
inherited
withAlpha(int a) Color
Returns a new color that matches this color with the alpha channel replaced with a (which ranges from 0 to 255).
inherited
withBlue(int b) Color
Returns a new color that matches this color with the blue channel replaced with b (which ranges from 0 to 255).
inherited
withGreen(int g) Color
Returns a new color that matches this color with the green channel replaced with g (which ranges from 0 to 255).
inherited
withOpacity(double opacity) Color
Returns a new color that matches this color with the alpha channel replaced with the given opacity (which ranges from 0.0 to 1.0).
inherited
withRed(int r) Color
Returns a new color that matches this color with the red channel replaced with r (which ranges from 0 to 255).
inherited

Operators

operator ==(Object other) bool
The equality operator.
override

Static Methods

maybeResolve(Color? resolvable, BuildContext context) Color?
Resolves the given Color by calling resolveFrom.
resolve(Color resolvable, BuildContext context) Color
Resolves the given Color by calling resolveFrom.