Create a keyboard help dialog for this sim

[jessegreenberg]

Since this sim has keyboard navigation, it will need a keyboard help dialog before deployment. @emily-phet @terracoda @arouinfar can you please coordinate or prioritize this issue?

[arouinfar]

@terracoda @jessegreenberg @emily-phet there doesn't appear to be much content for this one, so I took a stab at it. Please let me know if you have any suggestions, and then I'll mock up the dialog.

Mass Controls Move mass [arrow keys] (Since motion is 1D could do [left] [right] instead) Change mass [up] [down] (Alternatively: Increase or decrease mass [up] [down])

General Navigation Move to next item [tab] Move to previous item [shift] + [tab] Exit a dialog [esc]

[jessegreenberg]

Thanks @arouinfar! The only think I can think of is that the masses have all the controls of HSlider (so home/end move to min/max, page up/page down/ move in larger increments). At the moment shift does nothing special for moving masses in this sim.

[arouinfar]

Thanks @jessegreenberg! I tested the shift modifier, and saw it wasn't working, so I wrongly assumed the masses weren't sliders.

[arouinfar]

Based on today's discussion, I've tweaked the dialog content a bit.

Mass Controls Move mass [left] [right] Move in larger steps [pg up] [pg down] Jump to left [home] Jump to right [end] Increase mass [up] Decrease mass [down]

General Navigation Move to next item [tab] Move to previous item [shift] + [tab] Exit a dialog [esc]

A few thoughts:

• Grouping the slider and spinner controls under the same "Mass Controls" heading looks compact, but perhaps it will be less clear to the users. (Will users attempt to increase/decrease the mass while focused on the mass itself?)
• I prefer using [left] [right] for "move book" rather than [arrow keys] because the motion is 1D and [up] [down] changes the spinner value.
• Max/min doesn't map well onto this context (no visible slider) so I chose to use left/right for home/end, though I'm certainly open to other suggestions!

@terracoda @emily-phet @jessegreenberg any thoughts?

[jessegreenberg]

Grouping the slider and spinner controls under the same "Mass Controls" heading looks compact, but perhaps it will be less clear to the users. (Will users attempt to increase/decrease the mass while focused on the mass itself?)

I agree this could be confusing.

I prefer using [left] [right] for "move book" rather than [arrow keys] because the motion is 1D and [up] [down] changes the spinner value.

I agree.

Max/min doesn't map well onto this context (no visible slider) so I chose to use left/right for home/end, though I'm certainly open to other suggestions!

Not sure what is best since max/min are so dynamic! But that also seems more accurate since they are jumping to max/min allowable range from the sim state.

[terracoda]

@arouinfar, awesome stab at this tricky two-thumbed slider.

Question: The Pusher/Puller figures represent force, correct? Sorry for asking, but I still haven't played with this sim enough to fully grasp what it all means.

If so, I think, we need the heading "Mass Controls" to include something about "Force". I'm not sure of the best wording yet. I am trying to think about what might lead to exploration and sense making.

Just brainstorming a couple more potentially useful verbs:

• move
• adjust
• increase/decrease
• push/pull

Also regarding force and mass?

• force, OR
• applied force
• mass, OR
• mass amount

Brainstorming:

• Adjust applied force [left] [right]
• Adjust (or move) force [left] [right]
• Adjust mass [up][down]
• Increase/Decrease mass [up][down]
• Increase/Decrease mass amount [up][down]

Mass Pusher-Puller Force Controls Force Controls Mass Pusher-Puller Controls

• Adjust/Push/Pull/Move force [left] [right]
• Adjust/Push/Pull/Move force in larger steps [pg up] [pg down]
• Jump/Adjust/Move force to possible max [home]
• Jump/Adjust/Move to force to possible min [end], OR
• Jump/Adjust/Move to possible max force [home]
• Jump/Adjust/Move to possible min force [end]

Mass Amount (or Size??) Controls

• Adjust mass [up][down], OR
• Increase/Decrease mass [up][down], OR
• Increase mass [up]
• Decrease mass [down]

General Navigation Move to next item [tab] Move to previous item [shift] + [tab] Exit a dialog [esc]

[emily-phet]

@terracoda @arouinfar

I think it makes sense to me to keep the heading simple for moving the mass. Let's stick with "Move Mass". Ultimately that's what the user is trying to do. I thought through some of @terracoda suggestions, but I think simpler is best here. I looked at the teacher tips doc, and the interaction in the play area is referred to as "drag the masses apart or together". I think the little people are only there to balance the forces on the masses so that it makes sense why they are static once released. Essentially, the forces change in the sim because the location of the masses change - so moving the masses is the primary focus.

I agree that adjusting the mass should have its own heading. I think having moving and adjusting mass together makes it sound like oyu should be able to do them together.

So - how about this:

Move Mass Move mass [left] [right] Move in larger steps [pg up] [pg down] Jump to left [home] Jump to right [end]

Change Mass (see note below) Increase mass [up] Decrease mass [down]

General Navigation Move to next item [tab] Move to previous item [shift] + [tab] Exit a dialog [esc]

Note: (tried "adjust" but it seems weird to be able to move and adjust, move and change sounds better to me)

[terracoda]

I like your suggestions @emily-phet. I think "Move Mass" and "Change Mass" work well together.

[arouinfar]

Looks great @emily-phet! I think "adjust mass" could imply that the mass's position is being adjusted, but "change mass" doesn't carry the same baggage.

@DianaTavares can you mock up a dialog with this content?

Move Mass Move mass [left] [right] Move in larger steps [pg up] [pg down] Jump to left [home] Jump to right [end]

Change Mass Increase mass [up] Decrease mass [down]

General Navigation Move to next item [tab] Move to previous item [shift] + [tab] Exit a dialog [esc]

[DianaTavares]

here is!

[terracoda]

@DianaTavares, nice job! Just one change in wording...

Please change "Adjust in large steps" to "Move in large steps"

[terracoda]

@DianaTavares, @arouinfar, and @emily-phet, I just tested the sim and all the slider interactions work, which means [up] moves masses to the right and [down] moves masses to the left.

Also for the number spinners, [left] decreases the value, and [right] increases the value. [Pg Up] and [Pg Down] also move the spinners in larger steps.

Should these interactions also be reflected? And if so given the orientation of moving the masses/pullers left and right is quite significant, I am wondering if we should group the arrow keys a bit differently than in previous dialogs, i.e., pairing "[left] or [up]" and "[right] or [down]".

Or perhaps these interactions are intentionally removed for pedagogical reasons, even though they are still functionally operational?

For example:

Move Mass Move mass left [left] or [up] Move mass right [right] or [down] Move in larger steps [pg up] [pg down] Jump to left [home] Jump to right [end]

Change Mass Increase mass [up] or [right] Decrease mass [down] or [left] Change mass in larger steps [pg up] [pg down] Jump to maximum mass [home] Jump to minimum mass [end]

General Navigation Move to next item [tab] Move to previous item [shift] + [tab] Exit a dialog [esc]

[terracoda]

Please re-assign to me when you need the text-based HTML version. It's ready to go once we finalize the actual items that will be spelled out.

[arouinfar]

"Adjust in large steps" to "Move in large steps"

Good catch @terracoda!

I just tested the sim and all the slider interactions work, which means [up] moves masses to the right and [down] moves masses to the left. Also for the number spinners, [left] decreases the value, and [right] increases the value.

I purposefully left out up/down for moving masses and left/right for the number pickers, since these elements have strong direction associations -- the masses move horizontally, and the number pickers have an up/down arrow. I think the dialog is more succinct and easier to interpret without these additional arrows, but I'd be curious to see what @emily-phet and @jessegreenberg have to say.

[Pg Up] and [Pg Down] also move the spinners in larger steps.

I had missed this one! I like your suggestion to add [Pg Up] and [Pg Down] to the dialog.

[terracoda]

@emily-phet, do you think we should leave the less intuitive directional interactions out for pedagogical reasons?

I realize we are not trying to teach students about all keyboard navigation possibilities.

[emily-phet]

@terracoda @arouinfar @DianaTavares In this simulation, when moving the masses, I think we want to emphasize the left/right nature of the interaction. The masses are getting closer or farther away along a horizontal plane. For this reason, I think we don't need to indicate in the keyboard help that 'up/down' also change their positions. If users find that and need/like that interaction, that's fine, but I don't think we should highlight it.

For changing the mass values, it doesn't really matter if people have a left/right mapping or up/down mapping. so for these I don't see any reason not to provide both options.

Is there any opposition to having the change mass keyboard help section include up/down/left/right while not doing the same for the move mass sliders?

[terracoda]

@emily-phet, as long as users can still use the Up arrow key and the Down arrow to move the masses left and right, I don't see any harm in choosing to focus the interaction horizontally in the Keyboard Shortcuts.

That said, it would be an interesting question to ask non-visual students, if the actual arrows they use to move left and right affect their mental model of the interaction.

Going with the simplified version, the non-visual representation of the shortcuts would be something like this:

Move Spheres Move sphere left and right with the Left and Right Arrow keys. Move in larger steps with Page Up and Page Down keys. Jump to left with Home key. Jump to right with End key.

Change Mass Increase mass with Up or Right Arrow key. Decrease mass with Down or Left Arrow key. Change mass in larger steps with Page Up and Page Down keys. Jump to maximum mass with Home key. Jump to minimum mass with End key.

General Navigation Move to next item with Tab key. Move to previous item with Shift plus Tab key. Exit a dialog with Escape key.

Updated content April 10 after Keyboard dialog meeting.

[DianaTavares]

[terracoda]

@DianaTavares, nice. Looks good to me.

[arouinfar]

Looks good to me too @DianaTavares!

[phet-steele]

This sim has entered RC without this content. @emily-phet @DianaTavares what's the reason this isn't ready to be put it the sim?

[emily-phet]

@phet-steele Looks to me like this was finalized. @mbarlow12 Can you implement this?

[mbarlow12]

@emily-phet Will do.

[jessegreenberg]

@mbarlow12 feel free to use ResistanceInAWireKeyboardHelpContent.js as an example.

This dialog requires alignment of the "Move Mass" and "Change Mass" icons, which is not currently supported by HelpContent.js. They could be aligned with inspection but in the long term it would be nice to think of a way to do that more generally. Let me know if you have questions.

[arouinfar]

Slack Discussion in #accessibility channel:

@jessegreenberg

In https://github.com/phetsims/gravity-force-lab-basics/issues/29#issuecomment-364990455, we are using sim specific terminology for the KeyboardHelpDialog, even for the NumberSpinner. For things like NumberSpinners, RadioButtons, Sliders, can we get away with using a general set of help instructions so we don't have to redesign that content every time? Particularly the "Change Mass" section - those keys describe how to use a NumberPicker, but all descriptions include "mass", and some keys were left out for the purposes of this sim. Totally fine if that is necessary but it would be more scalable if we had one set of instructions that we can use for all NumberPickers

@arouinfar

@jessegreenberg I think there are always going to be special cases. The masses/charges in ISLC sims are sliders, but they don’t look like sliders. I can’t think of a situation where a NumberPicker won’t look like a NumberPicker, but I think that’s a harder UI element to describe to users. Users are likely to know what a slider is, but I’m not sure that the same can be said for NumberPicker.

@jessegreenberg

What if it were labelled with a heading like "Mass Controls" then followed by controls common to NumberPicker? Kind of like the photon emitter in MAL?

@arouinfar

Oh, I see. That could work! So the common NumberPicker controls would be something like: Increase value [up] [right] Decrease value [down] [left] Change value in larger steps [pg up][pg down] Jump to minimum value [home] Jump to maximum value [end]

@jessegreenberg

Yes, that is correct

@arouinfar

I don’t see any problem with that, so long as the headings would remain customizable.

@jessegreenberg has added this to the agenda for discussion at the next keyboard nav meeting.

[terracoda]

@jessegreenberg and @arouinfar, I do agree that a consistent approach is ideal. We do not yet have a lot of information on how these standard instructions are used or how much they are needed yet.

For any given PhET Sim, there could be a pedagogical reason for changing the wording as was decided for the Move Mass and Change Mass above. It is possible that leaving the word "mass" off in the "Change Mass" section is fine. It was left there for emphasis.

[jessegreenberg]

@mbarlow12 I ended up needing a way to align groups of help content in https://github.com/phetsims/balloons-and-static-electricity/issues/320 so I added a helper function HelpContent.alignHelpContentIcons that can hopefully also be used here.

[mbarlow12]

I added a helper method on HelpContent to creat pg up and down icons. @jessegreenberg it also may be useful to review some of what I did tomorrow (Tues) or Wed.

[jessegreenberg]

Thanks @mbarlow12, changes look good, thanks for the helper function in HelpContent. Only two thoughts:

• [x] Could you please fill in the type documentation for constructRow?
• [x] I find ICON_OPTIONS name to be a little confusing since it isn't a set of options like DEFAULT_LABEL_OPTIONS. Could we name it something like ICON_CREATOR (or something)?

[jessegreenberg]

Now somewhat related to #49.

[mbarlow12]

@jessegreenberg @emily-phet is there any further review necessary before closing this issue?

[terracoda]

@emily-phet and @arouinfar, once we finalize the design for the static descriptions, we should re-look at the keyboard dialog to make sure language used in the sim is still aligned with language used in the dialog. For example, headings might need to be tweaked to:

• Move Mass's Position
• Change Mass's Size/Magnitude

[emily-phet]

@mbarlow12 As @terracoda mentioned above, we'll want to double check that the wording from the static descriptions, and the wording in the keyboard help dialog match. The static descriptions are getting close, so it shouldn't be too much longer. Probably next week?

[arouinfar]

As predicted by @emily-phet and @terracoda, we will need to make some adjustments to the wording in the keyboard dialog.

• [x] Move Mass -> Moves Spheres (heading)
• [x] Move mass -> Move sphere (item)

Assigning to @mbarlow12 to update these strings.

[mbarlow12]

@emily-phet @arouinfar the strings are updated. I'm tempted to leave this issue open in case we have future changes of this sort. Otherwise, feel free to close.

[arouinfar]

Looks great @mbarlow12! I think we can go ahead and close this one. 😄