[Breaking Change] Propose to make MouseRegion default opaque, and require custom layers to implement a new method

[Tong Mu]

If you don't use MouseRegion (formerly Listener.onPointer{Enter,Exit,Hover}), and you don't have custom layer classes, you can stop reading now.

Overview

1. MouseRegion will have a new parameter, bool opaque. Its current behavior will be available as opaque: false, but we propose to make its default value to be opaque: true.

2. Subclasses of Layer will be required to implement a new method findAnnotations, and should no longer override find and findAll.

Justification

The new parameter MouseRegion.opaque is added to fix a bug. Consider a button that is stacked on top of another with some overlap, and the mouse pointer is within the overlapping area. Currently both buttons will display hover highlight at the same time, which might be considered unintended. This behavior will still be available as opaque: false. However, if the top button has opaque: true, then it will absorb the pointer during a successful hit, so that the bottom button will not be considered being hovered unless the mouse pointer is out of the top button. 

The following GIFs demonstrates the effect of opaque: false (left) and opaque: true (right).

We assume opaque: false to be a relatively minor usage, therefore we propose to change the default behavior to be opaque: true.

The current signatures of Layer.find and Layer.findAll do not provide sufficient information to implement this behavior. Therefore we propose to add a new method findAnnotations, which is designed to contain a unified logic of what used to be in Layer.find and Layer.findAll. Additionally, it returns a boolean that controls whether the layer's parent should continue the remaining children. The base class Layer now provide a default implementation of find and findAll, both of which simply call findAnnotations with different arguments and return the result, while findAnnotations is left abstract in order to encourage subclasses to implement it.

Migration

For each usage of MouseRegion, you should decide which behavior is desired. To keep the current behavior, add opaque: false. If the current behavior is considered a bug, no change is needed.

All custom layers will no longer be compilable due to lack of implementation of findAnnotations. To fix it, layers should no longer override either find or findAll, instead please override findAnnotations to make it handle both cases, then carefully choose a return value. You can checkout the documentation and the PR to see how existing layer classes are migrated. The discussion issue contains a few examples of common patterns. You're also welcome to comment in the discussion issue if you need help.

List of change and discussion

A proposed list of change can be found at #37896. The discussion issue might provide more detailed guide and latest update.

If you have any concerns or otherwise feel that this change should not be made, please comment on the PR or the discussion issue.