From 625a837f9563b32363c4776de7443e3fe472dc28 Mon Sep 17 00:00:00 2001 From: Chris Malley Date: Thu, 28 Oct 2021 10:37:16 -0600 Subject: [PATCH] reorder steps, https://github.com/phetsims/phet-info/issues/168 --- doc/alternative-input-quick-start-guide.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/alternative-input-quick-start-guide.md b/doc/alternative-input-quick-start-guide.md index 12b95261..e421158c 100644 --- a/doc/alternative-input-quick-start-guide.md +++ b/doc/alternative-input-quick-start-guide.md @@ -12,11 +12,13 @@ Follow these steps to add support for alternative input to a simulation. 2. Run `grunt update` to generate `{{REPO}}_a11y_view.html` and modify `{{REPO}}_en.html`. -3. For non-`LayoutBox` parent Nodes, explicitly set `this.pdomOrder` at the end of constructor. Do not rely on scenery’s +3. For `LayoutBox` Nodes do nothing. There is a good match between layout order and traversal order; they are typically the same. + +4. For non-`LayoutBox` parent Nodes, explicitly set `this.pdomOrder` at the end of constructor. Do not rely on scenery’s 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 `ScreenView`, `this.pdomOrder` cannot be set directly. There are two approaches you can use to specify traversal order at the ScreenView level. Check with your sim designer to see which approach is appropriate. +5. For `ScreenView`, `this.pdomOrder` cannot be set directly. There are two approaches you can use to specify traversal order at the ScreenView level. Check with your sim designer to see which approach is appropriate. (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: @@ -40,12 +42,10 @@ screenViewRootNode.pdomOrder = [...]; // decouple traversal order from rendering 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 +6. If you need to augment `this.pdomOrder` in a subclass, read about the numerous pitfalls in https://github.com/phetsims/scenery/issues/1308. -8. `DragListener` does NOT handle keyboard input. For Nodes where you’ve added a `DragListener`, you’ll need to add a +7. `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: @@ -68,7 +68,7 @@ tagName: 'div', focusable: true ``` -7. `PressListener` DOES handle keyboard input. For Nodes where you've added a `PressListener`, add these options to your +8. `PressListener` DOES handle keyboard input. For Nodes where you've added a `PressListener`, add these options to your Node: ```js @@ -76,7 +76,7 @@ focusable: true tagName: 'button' ``` -8. There may be common-code UI components for which alternative input has not been implemented. And there may be PhET +9. There may be common-code UI components for which alternative input has not been implemented. And there may be PhET design patterns for which alternative-input behavior has not been designed. Identify lack of alternative-input support, and create GitHub issues.