Document usages of interruptSubtreeInput()

[jessegreenberg]

I am assuming these were added for multi-touch cases, but can you please document why these are here? In MeanShareAndBalanceControls, why is it needed for decrement but not increment?

Do we need to add more interruptSubtreeInputs when you remove snacks? What if you are dragging a snacks while they are removed?

For #270

[marlitas]

I added documentation and an interruptSubtreeInput to TablePlateNode. However I want to test on a touch device, because I'm not confident it will interrupt candy bar interaction since the candy bars are not a child of the TablePlateNode. I don't have access right now, but will keep this assigned to me until I can do that.

[marlitas]

I'm going to have to wait until I make it back home to test this on my phone. The hotel wifi isn't cooperating. @jbphet if you have time today would you be able to test some of these multi-touch scenarios?

[jbphet]

I'm definitely seeing some problems in some fairly basic test cases. I'll describe a few. These are multi-touch scenarios, tested on my Dell Win 11 laptop that has a touch screen.

1. Load the sim and go to the "Distribute" screen.
2. Grab the highlighted candy bar from the left stack and drag it to the left side of the notepad with one finger.
3. Increment the number of candy bars on the 1st plate with another finger.
4. Release the dragged candy bar.

This produces a gap in the stack initially when the increment happens. The gap persists once the dragged candy bar is released. It looks like this before the candy bar is released:

This would seem to indicate that we do indeed need an interruptSubtreeInput in the increment case, as @jessegreenberg was asking about above.

The second problem encountered was that an assertion is hit with the following steps:

1. Load the sim and go to the "Distribute" screen.
2. Grab the highlighted candy bar from the left stack with a finger and drag it anywhere in the notepad.
3. Decrement the number of candy bars on the first plate with another finger.
4. Release the dragged candy bar from the first finger.

An assertion is hit that says "the candy bar must be on a plate".

The third problematic scenario is:

1. Load the sim and go to the "Distribute" screen.
2. Grab the sole candy bar on the right plate with one finger and drag it anywhere in the notepad.
3. Decrement the number of people using another finger.

The same assertion occurs, i.e. "the candy bar must be on a plate".

I'll leave it there for now, let me know if more testing is needed.

[jbphet]

@marlitas and I were discussing this issue earlier today, and she pointed out another case where user input should be probably be interrupted. This one is on the Balance Point screen. Here's the sequence to reproduce:

1. Load the sim and go to the "Balance Point" screen
2. Kick a ball using the "Kick" button
3. With on finger, grab the ball and start dragging it
4. With another finger, use the "Number of Balls" control to reduce the count to zero

The ball will disappear but the one on the balance beam won't. Here's a screenshot:

[jbphet]

Potential fixes for all the scenarios above have now been committed. I tested the specific scenarios and variations of them, and regression tested other behaviors, such as dragging of the cup controls on the first screen. Assigning to @marlitas for review.

[marlitas]

The code changes look good, and the additional documentation is very helpful. Thanks @jbphet! We can close :-)