Accessibility: Lazarus tracker targets + audio/speech toggle hotkeys

.gitignore

@@ -17,6 +17,7 @@ comparer-config.toml
 
 #ignore cmake cache
 /build-*/
+/build/releases/
 .vscode/tasks.json
 
 # Extra files in the source distribution (see make_src_dist.py)

CMake/Dependencies.cmake

@@ -51,6 +51,8 @@ add_subdirectory(3rdParty/sol2)
 if(SCREEN_READER_INTEGRATION)
   if(WIN32)
     add_subdirectory(3rdParty/tolk)
+  elseif(ANDROID)
+    # Android uses native accessibility API, no external dependency needed
   else()
     find_package(Speechd REQUIRED)
   endif()

README.md

@@ -20,16 +20,14 @@ Keybinds are configurable, but these are the defaults most players will use:
 
 ## Navigation / tracking
 
-- `T` - cycle tracker target (items / chests / doors / shrines / objects / breakables / monsters).
-- `N` - tracker directions to the nearest target (speaks target name + directions).
-- `Shift`+`N` - cycle to the next target in the current tracker category (speaks name only; duplicates get ordinal numbers).
-- `Ctrl`+`N` - clear the tracker target.
+- `Ctrl`+`PageUp` / `Ctrl`+`PageDown` - previous / next tracker category.
+- `PageUp` / `PageDown` - select previous / next target in the current category (speaks name; duplicates get ordinal numbers).
+- `Home` - tracker directions to the selected target (speaks target name + directions).
+- `Ctrl`+`Home` - clear the selected tracker target.
+- `Shift`+`Home` - auto-walk to the selected target (press again to cancel).
 - `H` - speak nearest unexplored space.
-- `E` - speak nearest exit (hold `Shift` for quest entrances).
-- `,` - speak nearest stairs up.
-- `.` - speak nearest stairs down.
 - `L` - speak current dungeon + floor.
-- `Z` - speak player health percentage.
+- `Z` - speak player health percentage (hold `Shift` for mana).
 - `X` - speak experience remaining to next level.
 
 ## Keyboard controls
@@ -41,10 +39,7 @@ Keybinds are configurable, but these are the defaults most players will use:
 
 ## Town NPCs
 
-- `F4` - list town NPCs.
-- `PageUp` / `PageDown` - select previous / next town NPC.
-- `End` - speak selected town NPC.
-- `Home` - walk to selected town NPC (town only).
+Town NPCs are available via the tracker category list.
 
 # How to Install
 

Source/CMakeLists.txt

@@ -41,6 +41,7 @@ set(libdevilutionx_SRCS
   control/control_infobox.cpp
   control/control_panel.cpp
 
+  controls/accessibility_keys.cpp
   controls/axis_direction.cpp
   controls/controller_motion.cpp
   controls/controller.cpp
@@ -51,6 +52,7 @@ set(libdevilutionx_SRCS
   controls/menu_controls.cpp
   controls/modifier_hints.cpp
   controls/plrctrls.cpp
+  controls/tracker.cpp
 
   DiabloUI/button.cpp
   DiabloUI/credits.cpp
@@ -160,13 +162,16 @@ set(libdevilutionx_SRCS
   tables/textdat.cpp
   tables/townerdat.cpp
 
+  utils/accessibility_announcements.cpp
   utils/display.cpp
-  utils/language.cpp
-  utils/proximity_audio.cpp
-  utils/sdl_bilinear_scale.cpp
-  utils/sdl_thread.cpp
-  utils/surface_to_clx.cpp
-  utils/timer.cpp)
+  utils/language.cpp
+  utils/navigation_speech.cpp
+  utils/proximity_audio.cpp
+  utils/sdl_bilinear_scale.cpp
+  utils/sdl_thread.cpp
+  utils/surface_to_clx.cpp
+  utils/timer.cpp
+  utils/walk_path_speech.cpp)
 
 # These files are responsible for most of the runtime in Debug mode.
 # Apply some optimizations to them even in Debug mode to get reasonable performance.
@@ -739,31 +744,31 @@ target_link_dependencies(libdevilutionx_utf8 PRIVATE
   SheenBidi::SheenBidi
 )
 
-if(NOSOUND)
-  add_devilutionx_object_library(libdevilutionx_sound
-    effects_stubs.cpp
-    engine/sound_pool_stubs.cpp
-    engine/sound_stubs.cpp
-  )
-  target_link_dependencies(libdevilutionx_sound PUBLIC
-    DevilutionX::SDL
-    fmt::fmt
+if(NOSOUND)
+  add_devilutionx_object_library(libdevilutionx_sound
+    effects_stubs.cpp
+    engine/sound_pool_stubs.cpp
+    engine/sound_stubs.cpp
+  )
+  target_link_dependencies(libdevilutionx_sound PUBLIC
+    DevilutionX::SDL
+    fmt::fmt
     magic_enum::magic_enum
     tl
     unordered_dense::unordered_dense
     libdevilutionx_options
     libdevilutionx_random
     libdevilutionx_sdl2_to_1_2_backports
   )
-else()
-  add_devilutionx_object_library(libdevilutionx_sound
-    effects.cpp
-    engine/sound_pool.cpp
-    engine/sound.cpp
-    utils/soundsample.cpp
-  )
-  if(USE_SDL3)
-    target_link_dependencies(libdevilutionx_sound PUBLIC
+else()
+  add_devilutionx_object_library(libdevilutionx_sound
+    effects.cpp
+    engine/sound_pool.cpp
+    engine/sound.cpp
+    utils/soundsample.cpp
+  )
+  if(USE_SDL3)
+    target_link_dependencies(libdevilutionx_sound PUBLIC
       SDL3_mixer::SDL3_mixer
     )
   else()
@@ -996,6 +1001,8 @@ if(SCREEN_READER_INTEGRATION)
   if(WIN32)
     target_compile_definitions(libdevilutionx PRIVATE Tolk)
     target_link_libraries(libdevilutionx PUBLIC Tolk)
+  elseif(ANDROID)
+    # Android uses native accessibility API, no external library needed
   else()
     target_include_directories(libdevilutionx PUBLIC ${Speechd_INCLUDE_DIRS})
     target_link_libraries(libdevilutionx PUBLIC speechd)

Source/DiabloUI/diabloui.cpp

@@ -109,14 +109,16 @@ void (*gfnFullscreen)();
 bool (*gfnListYesNo)();
 std::vector<UiItemBase *> gUiItems;
 UiList *gUiList = nullptr;
-bool UiItemsWraps;
-
-std::optional<TextInputState> UiTextInputState;
-bool allowEmptyTextInput = false;
-
-constexpr Uint32 ListDoubleClickTimeMs = 500;
-std::size_t lastListClickIndex = static_cast<std::size_t>(-1);
-Uint32 lastListClickTicks = 0;
+bool UiItemsWraps;
+
+std::optional<TextInputState> UiTextInputState;
+bool allowEmptyTextInput = false;
+
+std::optional<std::string> UiSpokenTextOverride;
+
+constexpr Uint32 ListDoubleClickTimeMs = 500;
+std::size_t lastListClickIndex = static_cast<std::size_t>(-1);
+Uint32 lastListClickTicks = 0;
 
 struct ScrollBarState {
 	bool upArrowPressed;
@@ -155,14 +157,20 @@ std::string FormatSpokenText(const StringOrView &format, const std::vector<DrawS
 	return formatted;
 }
 
-void SpeakListItem(std::size_t index, bool force = false)
-{
-	if (gUiList == nullptr || index > SelectedItemMax)
-		return;
-
-	const UiListItem *pItem = gUiList->GetItem(index);
-	if (pItem == nullptr)
-		return;
+void SpeakListItem(std::size_t index, bool force = false)
+{
+	if (gUiList == nullptr || index > SelectedItemMax)
+		return;
+
+	if (UiSpokenTextOverride) {
+		SpeakText(*UiSpokenTextOverride, force);
+		UiSpokenTextOverride = std::nullopt;
+		return;
+	}
+
+	const UiListItem *pItem = gUiList->GetItem(index);
+	if (pItem == nullptr)
+		return;
 
 	std::string text = FormatSpokenText(pItem->m_text, pItem->args);
 
@@ -180,10 +188,10 @@ void SpeakListItem(std::size_t index, bool force = false)
 
 	if (!text.empty())
 		SpeakText(text, force);
-}
-
-void AdjustListOffset(std::size_t itemIndex)
-{
+}
+
+void AdjustListOffset(std::size_t itemIndex)
+{
 	if (itemIndex >= listOffset + ListViewportSize)
 		listOffset = itemIndex - (ListViewportSize - 1);
 	if (itemIndex < listOffset)
@@ -232,13 +240,18 @@ void UiUpdateFadePalette()
 	SystemPaletteUpdated();
 	if (IsHardwareCursor()) ReinitializeHardwareCursor();
 }
-
-} // namespace
-
-bool IsTextInputActive()
-{
-	return UiTextInputState.has_value();
-}
+
+} // namespace
+
+void UiSetSpokenTextOverride(std::string text)
+{
+	UiSpokenTextOverride = std::move(text);
+}
+
+bool IsTextInputActive()
+{
+	return UiTextInputState.has_value();
+}
 
 void UiInitList(void (*fnFocus)(size_t value), void (*fnSelect)(size_t value), void (*fnEsc)(), const std::vector<std::unique_ptr<UiItemBase>> &items, bool itemsWraps, void (*fnFullscreen)(), bool (*fnYesNo)(), size_t selectedItem /*= 0*/)
 {
@@ -365,19 +378,19 @@ void UiFocus(std::size_t itemIndex, bool checkUp, bool ignoreItemsWraps = false)
 		}
 		pItem = gUiList->GetItem(itemIndex);
 	}
-	SpeakListItem(itemIndex);
-
-	if (HasAnyOf(pItem->uiFlags, UiFlags::NeedsNextElement))
-		AdjustListOffset(itemIndex + 1);
-	AdjustListOffset(itemIndex);
-
-	SelectedItem = itemIndex;
-
-	UiPlayMoveSound();
-
-	if (gfnListFocus != nullptr)
-		gfnListFocus(itemIndex);
-}
+	if (HasAnyOf(pItem->uiFlags, UiFlags::NeedsNextElement))
+		AdjustListOffset(itemIndex + 1);
+	AdjustListOffset(itemIndex);
+
+	SelectedItem = itemIndex;
+
+	UiPlayMoveSound();
+
+	if (gfnListFocus != nullptr)
+		gfnListFocus(itemIndex);
+
+	SpeakListItem(itemIndex);
+}
 
 void UiFocusUp()
 {

Source/DiabloUI/diabloui.h

@@ -1,13 +1,15 @@
-#pragma once
-
-#include <array>
-#include <cstddef>
-#include <cstdint>
-#include <optional>
-
-#ifdef USE_SDL3
-#include <SDL3/SDL_events.h>
-#include <SDL3/SDL_surface.h>
+#pragma once
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <string_view>
+
+#ifdef USE_SDL3
+#include <SDL3/SDL_events.h>
+#include <SDL3/SDL_surface.h>
 #else
 #include <SDL.h>
 #endif
@@ -109,13 +111,16 @@ bool UiLoadBlackBackground();
 void LoadBackgroundArt(const char *pszFile, int frames = 1);
 void UiAddBackground(std::vector<std::unique_ptr<UiItemBase>> *vecDialog);
 void UiAddLogo(std::vector<std::unique_ptr<UiItemBase>> *vecDialog, int y = GetUIRectangle().position.y);
-void UiFocusNavigationSelect();
-void UiFocusNavigationEsc();
-void UiFocusNavigationYesNo();
-
-void UiInitList(void (*fnFocus)(size_t value), void (*fnSelect)(size_t value), void (*fnEsc)(), const std::vector<std::unique_ptr<UiItemBase>> &items, bool wraps = false, void (*fnFullscreen)() = nullptr, bool (*fnYesNo)() = nullptr, size_t selectedItem = 0);
-void UiRenderListItems();
-void UiInitList_clear();
+void UiFocusNavigationSelect();
+void UiFocusNavigationEsc();
+void UiFocusNavigationYesNo();
+
+/** Overrides what the screen reader will speak for the next focused list item. */
+void UiSetSpokenTextOverride(std::string text);
+
+void UiInitList(void (*fnFocus)(size_t value), void (*fnSelect)(size_t value), void (*fnEsc)(), const std::vector<std::unique_ptr<UiItemBase>> &items, bool wraps = false, void (*fnFullscreen)() = nullptr, bool (*fnYesNo)() = nullptr, size_t selectedItem = 0);
+void UiRenderListItems();
+void UiInitList_clear();
 
 void UiClearScreen();
 void UiPollAndRender(std::optional<tl::function_ref<bool(SDL_Event &)>> eventHandler = std::nullopt);