addWithPaintTransform method Null safety

bool addWithPaintTransform(
  1. {required Matrix4? transform,
  2. required Offset position,
  3. required BoxHitTest hitTest}
)

Transforms position to the local coordinate system of a child for hit-testing the child.

The actual hit testing of the child needs to be implemented in the provided hitTest callback, which is invoked with the transformed position as argument.

The provided paint transform (which describes the transform from the child to the parent in 3D) is processed by PointerEvent.removePerspectiveTransform to remove the perspective component and inverted before it is used to transform position from the coordinate system of the parent to the system of the child.

If transform is null it will be treated as the identity transform and position is provided to the hitTest callback as-is. If transform cannot be inverted, the hitTest callback is not invoked and false is returned. Otherwise, the return value of the hitTest callback is returned.

The position argument may be null, which will be forwarded to the hitTest callback as-is. Using null as the position can be useful if the child speaks a different hit test protocol than the parent and the position is not required to do the actual hit testing in that protocol.

The function returns the return value of the hitTest callback.

link
This method is used in RenderBox.hitTestChildren when the child and parent don't share the same origin. 
abstract class RenderFoo extends RenderBox {
  final Matrix4 _effectiveTransform = Matrix4.rotationZ(50);

  @override
  void applyPaintTransform(RenderBox child, Matrix4 transform) {
    transform.multiply(_effectiveTransform);
  }

  @override
  bool hitTestChildren(BoxHitTestResult result, { required Offset position }) {
    return result.addWithPaintTransform(
      transform: _effectiveTransform,
      position: position,
      hitTest: (BoxHitTestResult result, Offset position) {
        return super.hitTestChildren(result, position: position);
      },
    );
  }
}

See also:

  • addWithPaintOffset, which can be used for transforms that are just simple matrix translations by an Offset.
  • addWithRawTransform, which takes a transform matrix that is directly used to transform the position without any pre-processing.

Implementation

bool addWithPaintTransform({
  required Matrix4? transform,
  required Offset position,
  required BoxHitTest hitTest,
}) {
  assert(position != null);
  assert(hitTest != null);
  if (transform != null) {
    transform = Matrix4.tryInvert(PointerEvent.removePerspectiveTransform(transform));
    if (transform == null) {
      // Objects are not visible on screen and cannot be hit-tested.
      return false;
    }
  }
  return addWithRawTransform(
    transform: transform,
    position: position,
    hitTest: hitTest,
  );
}