Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a screen reader mode option and implement on character creation screens #72344

Merged
merged 15 commits into from
Mar 15, 2024

Conversation

ZeroInternalReflection
Copy link
Contributor

@ZeroInternalReflection ZeroInternalReflection commented Mar 12, 2024

Summary

Interface "Add a screen reader mode option and implement on character creation screens"

Purpose of change

Screen readers are officially supported in Cataclysm, but even when the recommendations from the documentation have been followed, certain UI screens are extremely difficult to navigate when using a screen reader. Making the learning curve even steeper is the fact that the character creation screens are among the hardest to use.
Goes a fair way to fixing #65577

Describe the solution

  1. Expand the documentation for how screen readers behave. Given that they will a) try to detect new text, and b) are not necessarily capable of identifying the borders used in our UI screens, there are many circumstances where setting the terminal cursor position is not sufficient.
  2. Add an option under accessibility settings to identify that the player is using a screen reader
  3. Modify the display of the character creation screens (everything except the Description pane, which would be a fair bit more complicated) to optimize display for screen readers when SCREEN_READER_MODE is active.

Recommendations are detailed in the updated documentation/the TESTING section below, but generally speaking:

  1. If information is only conveyed via text colour, add an explicit text note
  2. Move information from headers/lists to the big pane of text
  3. Try to avoid displaying/changing text that would disrupt getting to the information the player needs
  4. If text hasn't changed, but you want to make sure the screen reader reads it anyway, inserting a space before the text tricks the screen reader into thinking its new (Watch some of the trait names in the testing section below).

Describe alternatives you've considered

The first priority with this was ensuring that all necessary information is conveyed to players using screen readers.
After that, it's a matter of minimizing how annoying it is to get that information while also minimizing the amount of additional code.
Maintaining a completely separate draw stack for SCREEN_READER_MODE is unfeasible, so I made no attempt to resize/move windows.
Also, I wanted to avoid having screen reader-specific controls, so, I did not, for instance, add the ability to tab between the list of options and the details of the selected option.
I've tried to keep the changes to ~2 if statements per UI screen with notes about why this text needs to be moved/hidden in SCREEN_READER_MODE.

Also, at some point these screens will need to be converted to ImGui. The general logic for optimizing for a screen reader should remain the same.

Testing

In theory, this PR only results in changes when SCREEN_READER_MODE is active. I spent a bit of time navigating with it off, and did not spot any changes.

Points screen
Before:
https://github.com/CleverRaven/Cataclysm-DDA/assets/89038572/1851cb71-2579-458f-8a22-b8be73581e4a
Issues include:

  • There is no indication as to what option is currently active
  • The list of options is interwoven with the description of the currently-selected option
  • Text common between the options doesn't get read when scrolling

After:
https://github.com/CleverRaven/Cataclysm-DDA/assets/89038572/597aa677-cf17-4c54-8fdb-4cc5276096aa
Remaining issues include:

  • Upon confirming a selection, the screen reader doesn't automatically note that the option is now active

Scenario screen
Before:
https://gist.github.com/assets/89038572/6f78052d-6765-4b3b-8b1a-0579b0a3ea42
Issues include:

  • There is no indication as to what scenario is currently active
  • The list of options is interwoven with the description of the currently-selected option
  • Text common between the options doesn't get read when scrolling

After:
https://gist.github.com/assets/89038572/3a03a33d-3479-4f72-9b3f-a335074026fc
Remaining issues include:

  • The "player difficulty" summary in the header will read out first if confirming a selection changes things
  • There's a whole lot of keybinding hint repetition before you get to the meat of the scenario changes

Profession screen
Before:
https://gist.github.com/assets/89038572/c800748d-fada-43bb-9050-558e30eb2a32
Issues include:

  • There is no indication as to what profession is currently active
  • The list of options is interwoven with the description of the currently-selected option
  • Text common between the options doesn't get read when scrolling

After:
https://gist.github.com/assets/89038572/2218b99f-cf16-4ab7-8979-fece672b9053

Background screen
Before:
https://gist.github.com/assets/89038572/0b652dec-e08b-4837-b65d-58e1a8430e20
Issues include:

  • There is no indication as to what backgrounds are currently active
  • The list of options is interwoven with the description of the currently-selected option
  • Text common between the options doesn't get read when scrolling

After:
https://gist.github.com/assets/89038572/66b8969f-6a98-4b2e-be25-2e9ab24d6da7

Stats screen
Before:
https://gist.github.com/assets/89038572/8fe5e04d-33aa-4e48-a0d1-04238d692521
Issues include:

  • The list of stats is interwoven with the description of the currently-selected stat
  • You can only infer which stat is currently selected

After:
https://gist.github.com/assets/89038572/a12c93a4-0bbd-4465-87c1-e5d81655243f

Traits screen
Before:
https://gist.github.com/assets/89038572/c03c7bc3-0983-439f-b411-93070435f3d3
Issues include:

  • When the list of traits scrolls, it starts reading the list rather than the description
  • There's no indication what traits are currently active or unavailable

After:
https://gist.github.com/assets/89038572/582c1d74-0d60-4b68-83ff-b4246cfc1a18
Remaining issues include:

  • If activating a trait causes the 'difficulty' summary to change, it reads that first. Then it reads the scrollbars.

Skills screen
Before:
https://gist.github.com/assets/89038572/811fe236-5fd3-454c-98f1-d98563b24e16
Issues include:

  • You have to wait for it to reach the skill in the list before learning what your current skill level is
  • The list of options is interwoven with the description of the currently-selected option
  • Text common between the skills doesn't get read when scrolling

After:
https://gist.github.com/assets/89038572/b367554e-10de-4068-a427-9f645d5b7016
Remaining issues include:

  • Text common between the skills doesn't get read when scrolling
  • The "player difficulty" summary in the header will read out first if confirming a selection changes things
  • The list of crafting recipes takes a very long time to read

Additional context

These changes were made working with Orca (v45.2), as that's the most readily-available screen reader for use with Cataclysm on Linux. I believe the changes and the examples included in the documentation will also be beneficial to anyone using a different screen reader, but I am unable to test that.

If I understand my settings correctly, the voice used in the test recordings is the default voice from the festival package of voices.

I'm not sure if doc/USER_INTERFACE_AND_ACCESSIBILITY was the best location for my various diagrams and examples about how Orca reads the game UIs, but I wanted to get those down somewhere.

Thanks to @DoctorBoomstick for assistance in navigating Orca and some playtesting.

@github-actions github-actions bot added <Documentation> Design documents, internal info, guides and help. [C++] Changes (can be) made in C++. Previously named `Code` [Markdown] Markdown issues and PRs Character / World Generation Issues and enhancements concerning stages of creating a character or a world <Bugfix> This is a fix for a bug (or closes open issue) Info / User Interface Game - player communication, menus, etc. json-styled JSON lint passed, label assigned by github actions astyled astyled PR, label is assigned by github actions labels Mar 12, 2024
@NetSysFire NetSysFire added the Accessibility Issues regarding accessibility label Mar 12, 2024
@github-actions github-actions bot added the BasicBuildPassed This PR builds correctly, label assigned by github actions label Mar 13, 2024
@Maleclypse
Copy link
Member

Bunch of clang error's mentioning screen reader so they are probably related to this PR.

@ZeroInternalReflection
Copy link
Contributor Author

Bunch of clang error's mentioning screen reader so they are probably related to this PR.

Yep:
https://github.com/CleverRaven/Cataclysm-DDA/actions/runs/8255512561/job/22582150042?pr=72344#step:9:885

They all look fairly straightforward though. I should have an update tomorrow.

@Maleclypse Maleclypse merged commit 763597a into CleverRaven:master Mar 15, 2024
19 of 26 checks passed
SurFlurer added a commit to SurFlurer/Cataclysm-DDA that referenced this pull request Mar 19, 2024
…ion/ScreenReaderMode"

This reverts commit 763597a, reversing
changes made to 5926cf0.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Accessibility Issues regarding accessibility astyled astyled PR, label is assigned by github actions BasicBuildPassed This PR builds correctly, label assigned by github actions <Bugfix> This is a fix for a bug (or closes open issue) [C++] Changes (can be) made in C++. Previously named `Code` Character / World Generation Issues and enhancements concerning stages of creating a character or a world <Documentation> Design documents, internal info, guides and help. Info / User Interface Game - player communication, menus, etc. json-styled JSON lint passed, label assigned by github actions [Markdown] Markdown issues and PRs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants