From 6c696b44e087344ae32950a26ff291e5230a5679 Mon Sep 17 00:00:00 2001 From: maj00r Date: Sun, 15 Nov 2026 18:05:26 +0100 Subject: [PATCH] fix: a screen reader finds its way by landmarks and hears what a click changed Titled panels are named groups, so the reader says which one focus went into. The tab bar and the settings categories are navigation, the page is the main part, the search boxes are search. A quality level, a section put back to its defaults, settings reloaded, the weather put back or its time set to now are spoken, as is the save status. --- StarterNG.Tests/AnnouncerTests.cs | 116 +++++++++++++ StarterNG/Controls/Announcer.cs | 89 ++++++++++ StarterNG/Controls/ScreenReaderNames.cs | 19 +++ StarterNG/MainWindow.axaml | 216 ++++++++++++------------ StarterNG/Views/Depot.axaml | 2 +- StarterNG/Views/Scenarios.axaml.cs | 11 ++ StarterNG/Views/Settings.axaml | 8 +- StarterNG/Views/Settings.axaml.cs | 3 + StarterNG/startercfg/lang/cz.xml | 2 + StarterNG/startercfg/lang/en.xml | 2 + StarterNG/startercfg/lang/hu.xml | 2 + StarterNG/startercfg/lang/pl.xml | 2 + StarterNG/startercfg/lang/ru.xml | 2 + 13 files changed, 363 insertions(+), 111 deletions(-) create mode 100644 StarterNG.Tests/AnnouncerTests.cs create mode 100644 StarterNG/Controls/Announcer.cs diff --git a/StarterNG.Tests/AnnouncerTests.cs b/StarterNG.Tests/AnnouncerTests.cs new file mode 100644 index 0000000..07a9c57 --- /dev/null +++ b/StarterNG.Tests/AnnouncerTests.cs @@ -0,0 +1,116 @@ +using Avalonia.Automation; +using Avalonia.Automation.Peers; +using Avalonia.Controls; +using Avalonia.Controls.Primitives; +using StarterNG.Controls; + +namespace StarterNG.Tests; + +public class AnnouncerTests +{ + private DateTime _now = new(2026, 11, 15, 12, 0, 0, DateTimeKind.Utc); + + private Announcer NewAnnouncer() => new(() => _now); + + [Fact] + public void A_message_is_read_while_fresh_and_then_forgotten() + { + var announcer = NewAnnouncer(); + announcer.Say(" Jakość grafiki: Wysoka "); + Assert.Equal("Jakość grafiki: Wysoka", announcer.Message); + + _now += Announcer.Shown; + Assert.Null(announcer.Message); + } + + [Fact] + public void Nothing_to_say_says_nothing() + { + var announcer = NewAnnouncer(); + announcer.Say("Zapisano ustawienia"); + announcer.Say(" "); + + Assert.Equal("Zapisano ustawienia", announcer.Message); + } + + [Fact] + public void A_control_inside_says_it_through_the_window_announcer() + { + var button = new Button(); + var announcer = NewAnnouncer(); + announcer.Child = new Border { Child = button }; + + Announcer.Say(button, "Godzina: 07:05"); + + Assert.Equal("Godzina: 07:05", announcer.Message); + } + + [Fact] + public void A_control_outside_any_announcer_is_not_heard() + { + Announcer.Say(new Button(), "Godzina: 07:05"); + } + + [Fact] + public void A_marked_text_is_read_when_it_changes() + { + var status = new TextBlock(); + Announcer.SetChanges(status, true); + var plain = new TextBlock(); + var announcer = NewAnnouncer(); + announcer.Child = new StackPanel { Children = { status, plain } }; + + plain.Text = "Ścieżka"; + Assert.Null(announcer.Message); + + status.Text = "Niezapisane zmiany"; + Assert.True(Announcer.GetChanges(status)); + Assert.Equal("Niezapisane zmiany", announcer.Message); + } + + [Fact] + public void A_screen_reader_hears_it_as_a_polite_live_region() + { + var announcer = NewAnnouncer(); + var peer = ControlAutomationPeer.CreatePeerForElement(announcer); + announcer.Say("Przywrócono domyślne"); + + Assert.Equal("Przywrócono domyślne", peer.GetName()); + Assert.Equal(AutomationLiveSetting.Polite, peer.GetLiveSetting()); + Assert.Equal(AutomationControlType.Group, peer.GetAutomationControlType()); + } +} + +public class NamedGroupTests +{ + static NamedGroupTests() => ScreenReaderNames.Install(); + + [Fact] + public void A_panel_with_a_title_is_a_group_named_by_it() + { + var panel = new HeaderedContentControl { Header = "Scenerie" }; + + Assert.Equal("Scenerie", AutomationProperties.GetName(panel)); + Assert.Equal(AutomationControlType.Group, AutomationProperties.GetControlTypeOverride(panel)); + Assert.True(AutomationProperties.GetIsControlElementOverride(panel)); + } + + [Fact] + public void A_panel_whose_title_goes_is_no_longer_a_group() + { + var panel = new HeaderedContentControl { Header = "Skład" }; + panel.Header = null; + + Assert.Null(AutomationProperties.GetName(panel)); + Assert.Null(AutomationProperties.GetControlTypeOverride(panel)); + } + + [Fact] + public void A_tab_keeps_its_own_way_of_speaking() + { + var tab = new TabItem { Header = "Pogoda" }; + + Assert.Null(AutomationProperties.GetName(tab)); + Assert.Equal(AutomationControlType.TabItem, AutomationProperties.GetControlTypeOverride(tab)); + } +} diff --git a/StarterNG/Controls/Announcer.cs b/StarterNG/Controls/Announcer.cs new file mode 100644 index 0000000..b8ce146 --- /dev/null +++ b/StarterNG/Controls/Announcer.cs @@ -0,0 +1,89 @@ +using System; +using Avalonia; +using Avalonia.Automation; +using Avalonia.Automation.Peers; +using Avalonia.Controls; +using Avalonia.VisualTree; + +namespace StarterNG.Controls; + +/// +/// Says what a click changed out of sight, such as a quality level that moved a dozen +/// sliders or a time set to now. It wraps the whole window: a screen reader learns of +/// an element only on its way to the focused one, and this lies on every such way. +/// A text marked is read whenever it changes. +/// +public class Announcer : Decorator +{ + /// How long a message stays its name, so it is not read again later on. + public static readonly TimeSpan Shown = TimeSpan.FromSeconds(3); + + public static readonly AttachedProperty ChangesProperty = + AvaloniaProperty.RegisterAttached("Changes"); + + public static bool GetChanges(TextBlock block) => block.GetValue(ChangesProperty); + + public static void SetChanges(TextBlock block, bool value) => block.SetValue(ChangesProperty, value); + + static Announcer() + { + TextBlock.TextProperty.Changed.AddClassHandler((block, _) => + { + if (GetChanges(block)) + Say(block, block.Text); + }); + } + + private readonly Func _now; + private string? _message; + private DateTime _saidAt; + + public Announcer() : this(() => DateTime.UtcNow) + { + } + + public Announcer(Func now) => _now = now; + + /// The message while it is fresh, then nothing. + public string? Message => _message is not null && _now() - _saidAt < Shown ? _message : null; + + /// Says the text through the announcer of the window is in. + public static void Say(Visual from, string? text) + { + var announcer = from as Announcer ?? from.FindAncestorOfType(); + announcer?.Say(text); + } + + public void Say(string? text) + { + if (string.IsNullOrWhiteSpace(text)) + return; + + string? before = Message; + _message = text.Trim(); + _saidAt = _now(); + // Its name changing is what makes a live region speak. + if (ControlAutomationPeer.CreatePeerForElement(this) is Peer peer) + peer.Told(before, _message); + } + + protected override AutomationPeer OnCreateAutomationPeer() => new Peer(this); + + private sealed class Peer : ControlAutomationPeer + { + public Peer(Announcer owner) : base(owner) + { + } + + private Announcer Announcer => (Announcer)Owner; + + public void Told(string? before, string now) => + RaisePropertyChangedEvent(AutomationElementIdentifiers.NameProperty, before, now); + + protected override string? GetNameCore() => Announcer.Message; + + protected override AutomationLiveSetting GetLiveSettingCore() => AutomationLiveSetting.Polite; + + protected override AutomationControlType GetAutomationControlTypeCore() => AutomationControlType.Group; + } +} diff --git a/StarterNG/Controls/ScreenReaderNames.cs b/StarterNG/Controls/ScreenReaderNames.cs index 1d66994..344a944 100644 --- a/StarterNG/Controls/ScreenReaderNames.cs +++ b/StarterNG/Controls/ScreenReaderNames.cs @@ -5,6 +5,7 @@ using System.Linq; using System.Runtime.CompilerServices; using Avalonia; using Avalonia.Automation; +using Avalonia.Automation.Peers; using Avalonia.Controls; using Avalonia.Controls.Documents; using Avalonia.Controls.Primitives; @@ -31,6 +32,8 @@ public static class ScreenReaderNames ContentControl.ContentProperty.Changed.AddClassHandler((i, _) => Give(i, TextOf(i.Content))); HeaderedItemsControl.HeaderProperty.Changed.AddClassHandler((i, _) => Give(i, TextOf(i.Header))); + HeaderedContentControl.HeaderProperty.Changed.AddClassHandler((c, _) => NameGroup(c)); + ComboBox.PlaceholderTextProperty.Changed.AddClassHandler((c, _) => Give(c, c.PlaceholderText)); TextBox.PlaceholderTextProperty.Changed.AddClassHandler((t, _) => Give(t, t.PlaceholderText)); @@ -82,6 +85,22 @@ public static class ScreenReaderNames public static string? TimeText(TimeSpan? time) => time?.ToString(@"hh\:mm", CultureInfo.InvariantCulture); + /// + /// A panel with a title, such as Scenerie or Skład, made a named group: the reader + /// says where focus went in, where before the panel was not there for it at all. + /// Tabs and expanders, which are panels with a title too, speak for themselves. + /// + private static void NameGroup(HeaderedContentControl panel) + { + if (panel.GetType() != typeof(HeaderedContentControl) && panel is not SettingsSection) + return; + + string? name = TextOf(panel.Header); + Give(panel, name); + AutomationProperties.SetControlTypeOverride(panel, name is null ? null : AutomationControlType.Group); + AutomationProperties.SetIsControlElementOverride(panel, name is null ? null : true); + } + private static void NameButton(Button button) => Give(button, button.Content is string ? null : TextOf(ToolTip.GetTip(button)) ?? TextOf(button.Content)); diff --git a/StarterNG/MainWindow.axaml b/StarterNG/MainWindow.axaml index 51eeea0..36aef47 100644 --- a/StarterNG/MainWindow.axaml +++ b/StarterNG/MainWindow.axaml @@ -8,125 +8,129 @@ xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:views="clr-namespace:StarterNG.Views" xmlns:starterNg="clr-namespace:StarterNG" + xmlns:ctl="clr-namespace:StarterNG.Controls" Title="Starter MaSzyna" Icon="/Assets/starter.ico" Width="1010" Height="768" MinWidth="1010" MinHeight="666" WindowStartupLocation="CenterScreen"> - + + + - - + + - + - - - - - - - + + - - - + - - + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - + + + + + + + + + + diff --git a/StarterNG/Views/Depot.axaml b/StarterNG/Views/Depot.axaml index f808ac9..fb84198 100644 --- a/StarterNG/Views/Depot.axaml +++ b/StarterNG/Views/Depot.axaml @@ -81,7 +81,7 @@ PointerWheelChanged="Combo_OnPointerWheel" SelectionChanged="ClassCombo_OnSelectionChanged" /> - diff --git a/StarterNG/Views/Scenarios.axaml.cs b/StarterNG/Views/Scenarios.axaml.cs index 9514941..fc0afba 100644 --- a/StarterNG/Views/Scenarios.axaml.cs +++ b/StarterNG/Views/Scenarios.axaml.cs @@ -836,6 +836,7 @@ public partial class Scenarios : UserControl { var now = DateTime.Now; weatherTime.SelectedTime = new TimeSpan(now.Hour, now.Minute, 0); + Announcer.Say(this, ScreenReaderNames.PickerText(App.Loc["Time"], ScreenReaderNames.TimeText(weatherTime.SelectedTime))); } private void WeatherRestore_OnClick(object? sender, RoutedEventArgs e) @@ -843,8 +844,18 @@ public partial class Scenarios : UserControl if (_currentScenery is null) return; _currentScenery.Weather.Restore(); ShowWeather(_currentScenery); + Announcer.Say(this, WeatherSummary()); } + /// The weather as a reader hears it once put back: every field and its value. + private string WeatherSummary() => string.Join(", ", + ScreenReaderNames.PickerText(App.Loc["Date"], ScreenReaderNames.DateText(weatherDate.SelectedDate, weatherDate.YearVisible)), + ScreenReaderNames.PickerText(App.Loc["Season"], ScreenReaderNames.TextOf(weatherSeason.SelectedItem)), + ScreenReaderNames.PickerText(App.Loc["Time"], ScreenReaderNames.TimeText(weatherTime.SelectedTime)), + ScreenReaderNames.PickerText(App.Loc["Temperature"], weatherTempLabel.Text), + ScreenReaderNames.PickerText(App.Loc["Visibility"], weatherFogLabel.Text), + ScreenReaderNames.PickerText(App.Loc["Overcast"], ScreenReaderNames.TextOf(weatherOvercast.SelectedItem))); + private static TimeSpan? ParseTime(string? text) { if (string.IsNullOrWhiteSpace(text)) diff --git a/StarterNG/Views/Settings.axaml b/StarterNG/Views/Settings.axaml index d3a8431..15d8578 100644 --- a/StarterNG/Views/Settings.axaml +++ b/StarterNG/Views/Settings.axaml @@ -22,7 +22,7 @@ TextTrimming="LeadingCharacterEllipsis" /> - +