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

Clean up formatting and tweak wording in UI documentation #72462

Merged
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Clean up formatting and tweak wording in UI documentation
ZeroInternalReflection committed Mar 17, 2024
commit 6886f0465ec8c6e0d4e1ca28f4119aa7368a315c
85 changes: 56 additions & 29 deletions doc/USER_INTERFACE_AND_ACCESSIBILITY.md
Original file line number Diff line number Diff line change
@@ -48,35 +48,43 @@ There are people who use screen readers to play Cataclysm DDA. There are severa
things to keep in mind when checking the user interface for compatibility with
screen readers. These include:

1. Screen reader mode:
1. Screen reader mode:<br>

An option ("SCREEN_READER_MODE") has been added where the user can indicate that
they are using a screen reader. If a change to the UI to optimize for screen
readers would be undesirable for other users, consider checking against
"SCREEN_READER_MODE", and including the change when true.

2. Text color:
2. Text color:<br>

Text color is not announced by screen readers. If key information is only
communicated to the player through text color, that information will not be
available to players using screen readers. For example, a simple
uilist where some options have been disabled:

```
----------------------------------------------------------------------------
|Execute which action? |
|--------------------------------------------------------------------------|
|<color_c_green>1</color> <color_c_light_gray>Cut up an item</color> |
|<color_c_green>f</color> <color_c_light_gray>Start a fire quickly</color> |
|<color_c_dark_gray>h Use holster</color> |
----------------------------------------------------------------------------

```
A screen reader user will only know that "Use holster" is unavailable when they
attempt to use it. When presenting information, consider hiding inaccessible
options and adding text to confirm information conveyed by text color. As an
example, the display of food spoilage status:

```
<color_c_light_blue>Acorns (fresh)</color>
```
```
<color_c_yellow>Acorns (old)</color>
```

3. Cursor placement:<br>

3. Cursor placement
In general, screen readers will start reading where the program has set the terminal
cursor. Thus, the cursor should be set to the beginning of the most important
section of the UI.
@@ -93,43 +101,56 @@ For debugging purposes, you can set the `DEBUG_CURSES_CURSOR` compile flag to
always show the cursor in the terminal (currently only works with the curses
build).

4. Window layout
4. Window layout:<br>

While setting the terminal cursor position is sufficient to set things up for
screen readers in many cases, there are caveats to this. Screen readers will also
attempt to detect text changes. If that text change is after the terminal cursor,
the screen reader may skip over text. As an example (terminal position noted
by X):

```
XEye color: amber

```
changing into

```
XEye color: blue

```
The screen reader will only read the word "blue", even though the cursor is
set to start reading at "Eye".
set to start reading at "Eye". A simple way to force the screen reader to announce
key information is to add a space at the cursor position if the first letter of the
displayed string has not changed. In this case,
```
XEye color: amber
```
would change into
```
X Eye color: blue
```

Another complication is if the screen reader detects text changes above the
terminal cursor. As an example:

```
Lifestyle: underpowered
XStrength: 8

```
changing into

```
Lifestyle: weak
XStrength: 9

The screen reader will start reading at "weak".
```
The screen reader will start reading at "weak" even though that's above the
terminal cursor.

Behaviour like this means that screen readers struggle with certain common UI
layouts. Examples of how to implement SCREEN_READER_MODE in various UI layouts
can be found in src/newcharacter.cpp.
layouts. Some examples are listed below. Examples of how to implement theses
changes can be found in `src/newcharacter.cpp`.

Note: In all following examples, the terminal cursor is marked "X".

4a. List with additional information at the top or bottom:

```
-----------------------------------------------------
|Choose type of butchery: |
|---------------------------------------------------|
@@ -139,12 +160,14 @@ XB Quick butchery 6 minutes |
|This technique is used when you are in a hurry, but|
|still want to harvest something from the corpse. |
-----------------------------------------------------
Figure 4ai - List with details at the bottom, current configuration
```
`Figure 4ai - List with details at the bottom, current configuration`

If the cursor is set at "Quick butchery", then the screen reader will read all of the
other options before getting to the description of what "Quick butchery" entails. The
preferred layout in SCREEN_READER_MODE is the following:

```
-----------------------------------------------------
|Choose type of butchery: |
|---------------------------------------------------|
@@ -154,18 +177,18 @@ preferred layout in SCREEN_READER_MODE is the following:
XB Quick butchery 6 minutes |
|This technique is used when you are in a hurry, but|
-----------------------------------------------------
Figure 4aii - List with details at the bottom, recommended "SCREEN_READER_MODE"
```
`Figure 4aii - List with details at the bottom, recommended "SCREEN_READER_MODE"`

That is:
1. Add the currently-selected list entry to the detail pane at the bottom, and
2. Disable display of the list of options.
The screen reader user can then scroll through the list of available options, only
hearing about the details of the currently-selected option.

Hiding the list of options is necessary even when the cursor is set to point X.
In addition to following the terminal cursor, screen readers will try to detect when
text changes, and can be misled by scrolling text. As an example:

Hiding the list of options is necessary because if the list scrolls, the screen reader
will detect that and attempt to read the list from the top. As an example:
```
-----------------------------------------------------
|Choose type of butchery: |
|---------------------------------------------------|
@@ -175,13 +198,15 @@ Yb Full butchery 39 minutes |
XThis technique is used to properly butcher a corpse|
|and requires a rope & a tree or a butchering rack, |
-----------------------------------------------------
Figure 4aiii - List with details at the bottom with scrolling issues
```
`Figure 4aiii - List with details at the bottom with scrolling issues`

When the list scrolls, the text at the top changes, and the screen reader will
'helpfully' start reading at point Y rather than the current cursor position X.
start reading at point Y and go through the entire list rather than the current
cursor position X.

4b. List with additional information at the side:

```
_______________________________
|List | Details relating to|
XItem 1 | item 1. Lorem |
@@ -190,24 +215,26 @@ XItem 1 | item 1. Lorem |
|Item 4 | |
|Item 5 | |
-------------------------------
Figure 4bi - List with details at the side, current configuration
```
`Figure 4bi - List with details at the side, current configuration`

In this common layout, the screen reader is unable to differentiate between the two
panes, and ends up reading the list interwoven with the details of the currently-selected
item. This is true whether the terminal cursor is set to the current item or to the top
left of the details pane.

The recommended layout in SCREEN_READER_MODE is the following:

_______________________________
```
-------------------------------
| | XItem 1 |
| | Details relating to|
| | item 1. Lorem |
| | ipsum |
| | |
| | |
-------------------------------
Figure 4bii - List with details at the side, recommended "SCREEN_READER_MODE"
```
`Figure 4bii - List with details at the side, recommended "SCREEN_READER_MODE"`

That is:
1. Add the currently-selected list entry to the detail pane at the side, and

Unchanged files with check annotations Beta

" Acid: <color_c_yellow>9.00</color>\n"
" Fire: <color_c_yellow>1.00</color>\n"
" Environmental: <color_c_yellow>20</color>\n"
);

Check failure on line 1302 in tests/iteminfo_test.cpp

GitHub Actions / Clang 12, Ubuntu, Tiles, ASan

"--
}
SECTION( "check that material resistances are properly overriden" ) {
" Acid: <color_c_yellow>9.00</color>\n"
" Fire: <color_c_yellow>2.00</color>\n"
" Environmental: <color_c_yellow>10</color>\n"
);

Check failure on line 1326 in tests/iteminfo_test.cpp

GitHub Actions / Clang 12, Ubuntu, Tiles, ASan

"--
}
SECTION( "complex protection from physical and environmental damage" ) {
" Cut: <color_c_red>1.00</color>, <color_c_yellow>12.00</color>, <color_c_green>23.00</color>\n"
" Ballistic: <color_c_red>1.00</color>, <color_c_yellow>8.50</color>, <color_c_green>16.00</color>\n"
" Pierce: <color_c_red>0.80</color>, <color_c_yellow>9.60</color>, <color_c_green>18.40</color>\n"
);

Check failure on line 1348 in tests/iteminfo_test.cpp

GitHub Actions / Clang 12, Ubuntu, Tiles, ASan

"--
}
SECTION( "pet armor with good physical and environmental protection" ) {
" Acid: <color_c_yellow>5.00</color>\n"
" Fire: <color_c_yellow>3.00</color>\n"
" Environmental: <color_c_yellow>10</color>\n"
);

Check failure on line 1368 in tests/iteminfo_test.cpp

GitHub Actions / Clang 12, Ubuntu, Tiles, ASan

"--
}
}
" Fire: <color_c_yellow>1.50</color>\n"
" Environmental: <color_c_yellow>6</color>\n";
CHECK( a_str == info_str );

Check failure on line 3003 in tests/iteminfo_test.cpp

GitHub Actions / Clang 12, Ubuntu, Tiles, ASan

"--
CHECK( a_copy_str == info_str );

Check failure on line 3004 in tests/iteminfo_test.cpp

GitHub Actions / Clang 12, Ubuntu, Tiles, ASan

"--
CHECK( a_copy_w_armor_str == info_str );

Check failure on line 3005 in tests/iteminfo_test.cpp

GitHub Actions / Clang 12, Ubuntu, Tiles, ASan

"--
const std::string info_prop_str =
"--\n"
" Fire: <color_c_yellow>1.75</color>\n"
" Environmental: <color_c_yellow>7</color>\n";
CHECK( a_copy_prop_str == info_prop_str );

Check failure on line 3021 in tests/iteminfo_test.cpp

GitHub Actions / Clang 12, Ubuntu, Tiles, ASan

"--
CHECK( a_copy_w_armor_prop_str == info_prop_str );

Check failure on line 3022 in tests/iteminfo_test.cpp

GitHub Actions / Clang 12, Ubuntu, Tiles, ASan

"--
const std::string info_rel_str =
"--\n"
" Fire: <color_c_yellow>2.00</color>\n"
" Environmental: <color_c_yellow>8</color>\n";
CHECK( a_copy_rel_str == info_rel_str );

Check failure on line 3038 in tests/iteminfo_test.cpp

GitHub Actions / Clang 12, Ubuntu, Tiles, ASan

"--
CHECK( a_copy_w_armor_rel_str == info_rel_str );
}