debugFillProperties method

Add additional properties associated with the node.

Use the most specific DiagnosticsProperty existing subclass to describe each property instead of the DiagnosticsProperty base class. There are only a small number of DiagnosticsProperty subclasses each covering a common use case. Consider what values a property is relevant for users debugging as users debugging large trees are overloaded with information. Common named parameters in DiagnosticsNode subclasses help filter when and how properties are displayed.

defaultValue, showName, showSeparator, and level keep string representations of diagnostics terse and hide properties when they are not very useful.

• Use defaultValue any time the default value of a property is uninteresting. For example, specify a default value of null any time a property being null does not indicate an error.
• Avoid specifying the level parameter unless the result you want cannot be achieved by using the defaultValue parameter or using the ObjectFlagProperty class to conditionally display the property as a flag.
• Specify showName and showSeparator in rare cases where the string output would look clumsy if they were not set.

  DiagnosticsProperty<Object>('child(3, 4)', null, ifNull: 'is null', showSeparator: false).toString()
  

  Shows using showSeparator to get output child(3, 4) is null which is more polished than child(3, 4): is null.

  DiagnosticsProperty<IconData>('icon', icon, ifNull: '<empty>', showName: false)).toString()
  

  Shows using showName to omit the property name as in this context the property name does not add useful information.

ifNull, ifEmpty, unit, and tooltip make property descriptions clearer. The examples in the code sample below illustrate good uses of all of these parameters.

DiagnosticsProperty subclasses for primitive types

• StringProperty, which supports automatically enclosing a String value in quotes.
• DoubleProperty, which supports specifying a unit of measurement for a double value.
• PercentProperty, which clamps a double to between 0 and 1 and formats it as a percentage.
• IntProperty, which supports specifying a unit of measurement for an int value.
• FlagProperty, which formats a bool value as one or more flags. Depending on the use case it is better to format a bool as DiagnosticsProperty<bool> instead of using FlagProperty as the output is more verbose but unambiguous.

Other important DiagnosticsProperty variants

• EnumProperty, which provides terse descriptions of enum values working around limitations of the toString implementation for Dart enum types.
• IterableProperty, which handles iterable values with display customizable depending on the DiagnosticsTreeStyle used.
• ObjectFlagProperty, which provides terse descriptions of whether a property value is present or not. For example, whether an onClick callback is specified or an animation is in progress.

If none of these subclasses apply, use the DiagnosticsProperty constructor or in rare cases create your own DiagnosticsProperty subclass as in the case for TransformProperty which handles Matrix4 that represent transforms. Generally any property value with a good toString method implementation works fine using DiagnosticsProperty directly.

Used by toDiagnosticsNode and toString.