From 9f7d67842f34c1723c1b494382de0a46168c0811 Mon Sep 17 00:00:00 2001 From: Chris Malley Date: Thu, 28 Oct 2021 10:18:29 -0600 Subject: [PATCH] how to handle ScreenView pdomOrder, https://github.com/phetsims/phet-info/issues/168 --- doc/alternative-input-quick-start-guide.md | 31 +++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/doc/alternative-input-quick-start-guide.md b/doc/alternative-input-quick-start-guide.md index 8312c05d..90f8dc42 100644 --- a/doc/alternative-input-quick-start-guide.md +++ b/doc/alternative-input-quick-start-guide.md @@ -16,12 +16,37 @@ Follow these steps to add support for alternative input to a simulation. default ordering, which corresponds to the order that children are added. It’s better to decouple rendering order and traversal order by explicitly setting `this.pdomOrder`. Note that most of the work here is in `ScreenView` subclasses. -4. For `LayoutBox` Nodes do nothing. There is a good match between layout order and traversal order; they are typically the same. +4. For `ScreenView`, `this.pdomOrder` cannot be set directly. There are two approaches you can use. Check with your +sim designer to see which approach is appropriate. -5. If you need to augment `this.pdomOrder` in a subclass, read about the numerous pitfalls + (a) Assign Nodes to either the "Play Area" or "Control Area". Do not add Nodes directly to the ScreenView. Instead, +use this pattern in your ScreenView constructor: + +```js +this.pdomPlayAreaNode.children = [ ... ]; +this.pdomPlayAreaNode.pdomOrder = [ ... ]; +this.pdomControlAreaNode.children = [ ... ]; +this.pdomPControlAreaNode.pdomOrder = [ ... ]; +``` + + (b) In many cases, "Play Area" and "Control Area" can be ignored for the purposes of alternative input. If +that is appropriate for your sim, then do not add Nodes directly to the ScreenView. Instead, use this pattern +in your ScreenView constructor: + +```js +const screenViewRootNode = new Node( { + children: [...] +}); +screenViewRootNode.pdomOrder = [...]; +this.addChild( screenViewRootNode ); +``` + +6. For `LayoutBox` Nodes do nothing. There is a good match between layout order and traversal order; they are typically the same. + +7. If you need to augment `this.pdomOrder` in a subclass, read about the numerous pitfalls in https://github.com/phetsims/scenery/issues/1308. -6. `DragListener` does NOT handle keyboard input. For Nodes where you’ve added a `DragListener`, you’ll need to add a +8. `DragListener` does NOT handle keyboard input. For Nodes where you’ve added a `DragListener`, you’ll need to add a corresponding `KeyboardDragListener`. The options for the `DragListener` and `KeyboardDragListener` will typically be similar, but beware that API differences exist. Your `KeyboardDragListener` should look something like this: