review, doc, minor refactor, #726

js/ComboBoxButton.js

@@ -60,6 +60,8 @@ class ComboBoxButton extends RectangularPushButton {
       lineWidth: 1,
       soundPlayer: SoundPlayer.NO_SOUND, // disable default sound generation
 
+      // {string} - The pattern for the voicingNameResponse, with "{{value}}" provided to be filled in with
+      // ComboBoxItem.a11yLabel.
       comboBoxVoicingNameResponsePattern: SunConstants.VALUE_NAMED_PLACEHOLDER,
 
       // PushButtonModel options
@@ -147,13 +149,13 @@ class ComboBoxButton extends RectangularPushButton {
 
     super( options );
 
-    // @private {boolean} - set to true to block voicing to occur upon this Button's next focus
+    // @private {boolean} - set to true to block voicing to occur upon this button's next focus event.
     this._blockNextVoicingFocusListener = false;
 
     this.voicingFocusListener = () => {
-      if ( !this._blockNextVoicingFocusListener ) {
-        this.defaultFocusListener();
-      }
+
+      // fire the listener only if we are not blocking the focus listener
+      !this._blockNextVoicingFocusListener && this.defaultFocusListener();
       this._blockNextVoicingFocusListener = false;
     };
 
@@ -244,7 +246,7 @@ class ComboBoxButton extends RectangularPushButton {
   }
 
   /**
-   * Call to block voicing from occurring upon this Button's next focus.
+   * Call to block voicing from occurring upon this button's next focus event.
    * @public
    */
   blockNextVoicingFocusListener() {

js/ComboBoxListBox.js

@@ -42,7 +42,7 @@ class ComboBoxListBox extends Panel {
       yMargin: 8,
       backgroundPickable: true,
 
-      // Options that apply to every item Node created in the list
+      // Options that apply to every ComboBoxItemNode created in the list
       comboBoxListItemNodeOptions: {},
 
       // pdom
@@ -307,6 +307,8 @@ class ComboBoxListBox extends Panel {
   }
 
   /**
+   * voice the response from selecting a new item Node. The response will differ depending on if the selection
+   * changed the Property.
    * @private
    * @param {*} newValue
    * @param {*} oldValue

js/ComboBoxListItemNode.js

@@ -49,7 +49,7 @@ class ComboBoxListItemNode extends Voicing( Node, 0 ) {
       positionInPDOM: true,
 
       // voicing
-      voicingFocusListener: null,
+      voicingFocusListener: () => this.comboBoxListItemNodeVoicingFocusListener(),
       comboBoxVoicingNameResponsePattern: SunConstants.VALUE_NAMED_PLACEHOLDER,
 
       // phet-io
@@ -70,10 +70,10 @@ class ComboBoxListItemNode extends Voicing( Node, 0 ) {
     // pdom: get innerContent from the item
     assert && assert( options.innerContent === undefined, 'ComboBoxListItemNode sets innerContent' );
     options.innerContent = item.a11yLabel;
+    options.voicingObjectResponse = item.a11yLabel;
     options.voicingNameResponse = StringUtils.fillIn( options.comboBoxVoicingNameResponsePattern, {
       value: item.a11yLabel
     } );
-    options.voicingObjectResponse = item.a11yLabel;
 
     // Highlight that is shown when the pointer is over this item. This is not the a11y focus rectangle.
     const highlightRectangle = new Rectangle( 0, 0, highlightWidth, highlightHeight, {
@@ -109,19 +109,10 @@ class ComboBoxListItemNode extends Voicing( Node, 0 ) {
 
     super( options );
 
-    // @private
+    // @private {boolean} - when true, the next voicing focus listener will supply the hint response in addition to
+    // the object response. It will then set this back to false.
     this._supplyHintResponseOnNextFocus = false;
 
-    // Handle Voicing on focus in a more custom way
-    this.addInputListener( {
-      focus: () => {
-        this.voicingSpeakObjectResponse( {
-          hintResponse: this._supplyHintResponseOnNextFocus ? this.voicingHintResponse : null
-        } );
-        this._supplyHintResponseOnNextFocus = false;
-      }
-    } );
-
     // @public (read-only)
     this.item = item;
 
@@ -138,12 +129,23 @@ class ComboBoxListItemNode extends Voicing( Node, 0 ) {
   }
 
   /**
-   * This will only provide the hint for the very next voicing on focus.
+   * Ask for the voicing hint response upon next focus, but only for the very next focus event.
    * @public
    */
   supplyHintResponseOnNextFocus() {
     this._supplyHintResponseOnNextFocus = true;
   }
+
+  /**
+   * A custom focus listener for this type, with conditional support for providing hint responses.
+   * @private
+   */
+  comboBoxListItemNodeVoicingFocusListener() {
+    this.voicingSpeakObjectResponse( {
+      hintResponse: this._supplyHintResponseOnNextFocus ? this.voicingHintResponse : null
+    } );
+    this._supplyHintResponseOnNextFocus = false;
+  }
 }
 
 sun.register( 'ComboBoxListItemNode', ComboBoxListItemNode );