Design of Keyboard Shortcuts dialog

[terracoda]

Is there already an open issue about the KB Shortcuts dialog? Wording changes are needed for the current dialog.

[terracoda]

I would not repeat "Keyboard Shortcuts" as a subheading.

I think these handy additions should go first since the Launch shortcut is more important than dragging the Tape Measure around.

I would say "Tools" or "Objects" instead of "Items", but I am not sure what has been used in other sims.

I generally avoid displaying text such as "Press the launch button". Rather just define the action and have the buttons. The accessible text is a bit more like a sentence.

Subheading: From Anywhere in Sim

• Launch Projectile [Option] + [L]
• Compare Field Data [Option] + [1]-[6]

Have you considered allowing the number keys when focus is on the radio button group? It would be nice to have a single-key shortcut for that if it is not otherwise prohibitive?

[terracoda]

Number keys could work on all the radio button groups as a jump key, even. I think it might be a suggested standard for radio groups larger than 5 items. I would have to check though.

[samreid]

I'm also about to add a slider help section as part of #235

[samreid]

I would not repeat "Keyboard Shortcuts" as a subheading.

Addressed in the commit

I think these handy additions should go first since the Launch shortcut is more important than dragging the Tape Measure around.

Addressed in the commit

I would say "Tools" or "Objects" instead of "Items", but I am not sure what has been used in other sims.

We are using MoveDraggableItemsKeyboardHelpSection which is hard-coded to use "items" and used in several other simulations.

Subheading: From Anywhere in Sim

Addressed in the commit.

I generally avoid displaying text such as "Press the launch button". Rather just define the action and have the buttons. The accessible text is a bit more like a sentence.

Pressing the hotkey doesn't always "launch a projectile". It has a behavior that depends on the modality of the simulation. For instance, in certain circumstances, it can cause projectile to stop launching. @matthew-blackman and I thought the most general way to describe it is to say "Press the launch button".

Have you considered allowing the number keys when focus is on the radio button group? It would be nice to have a single-key shortcut for that if it is not otherwise prohibitive?

Addressed in the commit, for the field radio button group only, since it has a clear correspondence between numbers and indices (unlike, say, the sample size radio buttons).

Number keys could work on all the radio button groups as a jump key, even. I think it might be a suggested standard for radio groups larger than 5 items. I would have to check though.

I did not add that for the other radio button groups. For instance the sample size radio buttons are: 2, 5, 15, 40 and it could be odd for the "1" key to select "2" and the "2" key to select "5" or anything like that. Should we add anything for the other radio button groups? The Mystery Launcher group already has (non-global) number keys, since it has a numeric index interpretation.

I wasn't sure where to put the slider help controls, @terracoda can you please advise? Anything else for this issue?

[terracoda]

Quoting @samreid

I wasn't sure where to put the slider help controls, @terracoda can you please advise? Anything else for this issue?

There should be a discussion if everything you think should be in the dialog, is in the dialog.

The dialog is screen-specific, and I have only been looking at screen 1 (sorry).

[terracoda]

Keyboard Shortcuts is looking better. Regarding the section:

From Anywhere in Sim
Launch Projectile [Option] + [L]
Compare Field Data [Option] + [1]-[6]

How about:

Launch or stop projectiles [Option] + [L]
Compare fields [Option] + [1]-[6]

The numbered radio button groups work nicely now. I am checking the ARIA Practices Radio Group pattern to see if this should be generalized.

[matthew-blackman]

The keyboard help dialog is looking great! For the hotkeys, I like

Launch or stop projectiles [Option] + [L]

It also works for the Sampling screen, so we can use the same text across the sim. For switching Fields, I'd prefer a more general description, since the student may or may not have data on a field to compare to. Let's try the following:

Go to field [Option] + [1]-[6]

This seems general enough to apply to fields that have or don't have data, and also emphasizes that the Fields are different physical locations, with independent data and experimental setup.

[terracoda]

Well, you are not moving your focus to there, so I feel that's not quite right?

How do you like "Show field"?

[matthew-blackman]

'Show field' works for me. By 'Go to field' I meant more that the user is physically transported to that field to see the configuration and data, not that the keyboard is re-focusing. For keyboard focus, do we use 'Go to' or 'Move to'? I don't feel strongly one way or the other, but 'Go to' seemed more immersive than 'Show'.

In the commit, @samreid and I updated the hotkey label to 'Show field 1-6'. How does that look @terracoda, and how do you feel about my comment above?

[terracoda]

We have used "Jump to {field}" for certain interactions.

But usually with focus in mind.

I am not sure what you mean by "more immersive", so maybe we could chat quickly about that.

In the case of the actual radio button shortcut you are are moving focus. In the case of the global shortcut, you are not moving your focus, but rather showing/revealing different information.

[terracoda]

The point of showing the field is to view the data, and the histogram also changes which means one can leave their focus on the "Play Histogram Data" button and easily compare sounds between data sets - very nice!

I think "Show field data" is better than "Show field". I originally had "Compare field data".

Unless, you feel otherwise, I feel the word "data" is important, and repeating "1-6" in the description is not. The field numbers are represented by the numbers on the key-icons.

The accessible text in the dialog will eventually be:

• Launch or stop projectiles with Option key plus L.
• Show field data with Option key plus number keys one through 6.

[matthew-blackman]

I'm fine with removing the 1-6, but 'Show field data' doesn't make sense to me. When the sim is first opened, there is no data on any of the fields. To collect it, the user needs to first go to an empty field, set up their experiment and then collect data.

Going to a field is more than accessing or comparing its data (if it has any). Each field is an independent lab environment which can be configured separately, and may or may not have data on it. That is why I prefer 'Go to field', as the user is going to that location to do something, whether it is set up an experiment, run an experiment or compare pre-collected data.

[terracoda]

I see. Thanks for the explanation.
I was having trouble with "Go to field" because you don't physically go there with focus, but if you use the Launcher short cut you will add data to that field.

If you think "Go to field" is best, I am open to trying that.

@samreid asked about the slider on screen 2.

I suggest customizing the language - at least the heading.

[samreid]

We are using the "Slider Controls" section defined in common code here: https://github.com/phetsims/scenery-phet/blob/main/js/keyboard/help/SliderControlsKeyboardHelpSection.ts

It does not have a customizable title.

[terracoda]

@matthew-blackman, said:

Going to a field is more than accessing or comparing its data (if it has any). Each field is an independent lab environment which can be configured separately, and may or may not have data on it. That is why I prefer 'Go to field', as the user is going to that location to do something, whether it is set up an experiment, run an experiment or compare pre-collected data.

The field is more than the data. It's a scene or an lab environment! That makes sense.

After some reflection I am still a little uneasy about "Go" because for me, "Go" sounds like you are actively moving your keyboard focus which is not the case here.

We have very few visible words, and not that many words with Interactive Description and Voicing features, so for the described experience a word can really speak to what the interaction is about. A word can trigger ideas about the interaction.

What do you think of these action words:

• Check field [Option/ALT] + [1] - [6], or
• Set field [Option/ALT] + [1] - [6], or
• Switch field [Option/ALT] + [1] - [6]

Do any if these capture the "lab idea" appropriately in your mind?

[terracoda]

@samreid and @matthew-blackman, regarding the slider defaults, yes, you are using the defaults. The defaults don't seem to speak to what is visually displayed.

The word "wide" seems like max and the word "narrow" seems like min, so I am wondering if a different pair of words could be used in the visual representation to better fit with min on the left and max on the right of the slider.

The slider's name is "Angle Stabilizer".

• Jump to minimum (the start of the slider) is labeled: "wide", meaning minimum stability, or least stable.
• Jump to maximum (the end of the slider) is labeled: "narrow", maximum stability, or stable or completely stable

This seems to indicate a qualitative scale that starts at a loose setting and tightens as the slider narrows and increases stability. Is there a unit of pressure or tightness in the model? Or is there a unit of width in the model? Is this a meaningful unit, or is the "wide"/"narrow" just about the visual representation?

I am not sure if you should change the visually displayed labels on the ends of the slider or customize the wording in the KB Help dialog to match ideas around "wide"/"narrow" settings.

Starting at line 33 in the TS file, you have options to customize the text in the dialog when it seems appropriate to better scaffold the interaction.

Sorting this out might need a quick meeting.

With no change to the visuals, I would suggest something like this for the KB dialog:

"Stabilize Launcher Angle".

• Jump to least stable
• Jump to stable

OR

• Jump to loose stability
• Jump to max stability

OR

• Jump to loose
• Jump to tight

There are other possibilities, of course, but maybe changing the visual words could mean a better fit with the default slider instructions?

[terracoda]

Again, maybe a quick meeting could sort this out :-)

[arouinfar]

I would say "Tools" or "Objects" instead of "Items", but I am not sure what has been used in other sims.

We are using MoveDraggableItemsKeyboardHelpSection which is hard-coded to use "items" and used in several other simulations.

Sorry to chime in on an already giant issue, but I wanted to add some context to the “Move Draggable Items” title in case it's relevant to the upcoming discussion.

We use “items” and not “objects” because the latter has a specific meaning in optics sims that would create confusion. Also, not everything draggable is a “tool" used for measurement. "Item" was chosen because it is generic enough to fit most situations without creating other issues. However, I think KeyboardHelpSection titles are customizable on a sim-by-sim basis.

[matthew-blackman]

After discussing this with @terracoda, we felt that 'Go to field' worked well within the theme of the sim. It is updated in the commit. Closing and continuing remaining work in #250. Nice work all!

[terracoda]

@arouinfar, I understand why you went with "items" in the Optics sims.

I feel, even though one can adjust the default, there seems to be some hesitancy to do so, even when it might make a lot of sense to do so. I think we need some design documentation around the building out a Keyboard Shortcuts dialog. I'll open a new issue for that :-)

[terracoda]

Instead of opening a new issue, I added a couple of points to the sim design checklist.