Skip to content
Merged
Show file tree
Hide file tree
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
3 changes: 3 additions & 0 deletions docs/engineering/a11y-safety.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@
- 鍵盤焦點:強烈靜態視覺回饋 (反轉、字體加粗)。
- 按壓狀態:獨立於焦點的第三層級。深色模式使用飽和暖色 (琥珀色 `255,200,120`),亮度差 **ΔL*≥13**。
- **Tritanopia 調整亮度公式**:$L_{tritan} = (R_{lin} \times 0.2126 + G_{lin} \times 0.7152) / 0.9278$。
- **Dwell 與 Latest 交接**:共用眼動儀回饋按鈕使用 "FeedbackButton";回饋結束先還原 Color.Empty,再清除該按鈕的原生背景動畫快取,讓背景、文字與提示框於同一幀還原。不得為此切換 VisualStylesMode、重建 HWND 或改變版面。
- 視窗未啟用時仍須保持懸停文字與背景成對,不以略過自訂回饋後交回原生懸停取代;這不應啟用視窗或移動焦點。
- Dwell 更新在 UI 寫入前再次檢查動畫識別碼,避免過期更新重啟已結束的視覺。測試須涵蓋三種主題、啟用/未啟用視窗、預設/一般按鈕的整段過渡取樣,不能只檢查最後一幀。
- **預設動作引導**:當焦點在輸入框時,`AcceptButton` 必須顯示與焦點框一致的情境感知邊框色;強視覺反轉情境使用 **Cyan / MediumBlue**,中性情境使用 **LightBlue / MediumBlue**。
- 輸入框與預設動作提示須共用情境選色,並在輸入框底色/焦點變更時重繪。Latest 的強調色按鈕不得使提示對比下降;可在提示邊框緊鄰處繪製對比襯底,保留按鈕本體與原生主題外觀,不得改變尺寸、Margin 或 Padding。
- 測試須量測實際渲染的邊框與相鄰背景,不得只比對顏色名稱;同時覆蓋反轉及中性情境、三種主題與進度條主填色的對比。文件中對比數值為四捨五入顯示,不取代未取整的最低門檻。
Expand Down
8 changes: 8 additions & 0 deletions src/InputBox/Core/Controls/FeedbackButton.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
namespace InputBox.Core.Controls;

/// <summary>保留原生 Latest 外觀,並提供自訂回饋結束時的原生色彩快取重設。</summary>
public class FeedbackButton : Button
{
/// <summary>透過 WinForms 既有主題刷新路徑終止舊色動畫,不改變樣式、HWND 或版面。</summary>
internal void ResetNativeColorTransition() => base.OnSystemColorsChanged(EventArgs.Empty);
}
2 changes: 1 addition & 1 deletion src/InputBox/Core/Controls/GamepadCalibrationDialog.cs
Original file line number Diff line number Diff line change
Expand Up @@ -383,7 +383,7 @@ private Button CreateEyeTrackerButton(string text, string accessibleName, string
Font boldFont = MainForm.GetSharedA11yFont(DeviceDpi, FontStyle.Bold, font.FontFamily);
Size boldTextSize = TextRenderer.MeasureText(text, boldFont);

Button btn = new()
Button btn = new FeedbackButton()
{
Text = text,
AccessibleName = accessibleName,
Expand Down
2 changes: 1 addition & 1 deletion src/InputBox/Core/Controls/GamepadMessageBox.cs
Original file line number Diff line number Diff line change
Expand Up @@ -421,7 +421,7 @@ private Button CreateEyeTrackerButton(string label)

string description = StripMnemonic(label) ?? label;

Button btn = new()
Button btn = new FeedbackButton()
{
Text = label,
AccessibleName = description,
Expand Down
2 changes: 1 addition & 1 deletion src/InputBox/Core/Controls/HelpDialog.cs
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ public HelpDialog()
// profile 用來讓關閉按鈕與說明表的顯示文字跟著目前控制器模式同步。
GamepadFaceButtonProfile profile = GamepadFaceButtonProfile.GetActiveProfile();

_btnClose = new Button()
_btnClose = new FeedbackButton()
{
Text = profile.FormatCancelButtonText(Strings.Help_Btn_Close),
AutoSize = true,
Expand Down
2 changes: 1 addition & 1 deletion src/InputBox/Core/Controls/NumericInputDialog.cs
Original file line number Diff line number Diff line change
Expand Up @@ -906,7 +906,7 @@ private Button CreateEyeTrackerButton(
int baseMinWidth = Math.Max((int)(120 * scale), boldTextSize.Width + (int)(32 * scale)),
baseMinHeight = Math.Max((int)(60 * scale), boldTextSize.Height + (int)(24 * scale));

Button btn = new()
Button btn = new FeedbackButton()
{
Text = text,
AccessibleName = text,
Expand Down
4 changes: 2 additions & 2 deletions src/InputBox/Core/Controls/PhraseEditDialog.cs
Original file line number Diff line number Diff line change
Expand Up @@ -334,7 +334,7 @@ public PhraseEditDialog(string name, string content, Font? a11yFont)
// profile 用於同步片語編輯對話框中的確認/取消按鈕提示與目前控制器配置。
GamepadFaceButtonProfile profile = GamepadFaceButtonProfile.GetActiveProfile();

_btnCancel = new Button()
_btnCancel = new FeedbackButton()
{
Text = profile.FormatCancelButtonText(Strings.Phrase_Btn_Cancel),
AutoSize = true,
Expand All @@ -350,7 +350,7 @@ public PhraseEditDialog(string name, string content, Font? a11yFont)
};
_btnCancel.FlatAppearance.BorderSize = 0;

_btnOk = new Button()
_btnOk = new FeedbackButton()
{
Text = profile.FormatConfirmButtonText(Strings.Phrase_Btn_Confirm),
AutoSize = true,
Expand Down
2 changes: 1 addition & 1 deletion src/InputBox/Core/Controls/PhraseManagerDialog.Layout.cs
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ private static Button CreateActionButton(
string a11yDesc,
char mnemonic)
{
Button btn = new()
Button btn = new FeedbackButton()
{
Text = ControlExtensions.GetMnemonicText(text, mnemonic),
AutoSize = true,
Expand Down
2 changes: 1 addition & 1 deletion src/InputBox/Core/Controls/PhraseManagerDialog.cs
Original file line number Diff line number Diff line change
Expand Up @@ -356,7 +356,7 @@ public PhraseManagerDialog(PhraseService phraseService)
_tlpMain.Controls.Add(_flpButtons, 1, 0);

// 底部關閉按鈕。
_btnClose = new Button()
_btnClose = new FeedbackButton()
{
Text = profile.FormatCancelButtonText(Strings.Phrase_Btn_Close),
AutoSize = true,
Expand Down
42 changes: 35 additions & 7 deletions src/InputBox/Core/Extensions/ButtonEyeTrackerExtensions.cs
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
using InputBox.Core.Configuration;
using InputBox.Core.Controls;
using InputBox.Resources;
using System.Diagnostics;
using System.Drawing.Drawing2D;
Expand Down Expand Up @@ -44,6 +45,9 @@ private sealed class ButtonVisualState
/// </summary>
public long AnimId;

/// <summary>重設原生色彩快取期間避免系統色事件重入。</summary>
public bool IsResettingNativeColors { get; set; }

/// <summary>
/// 基礎無障礙描述,供不同互動狀態下的 AccessibleDescription 組合使用
/// </summary>
Expand Down Expand Up @@ -168,7 +172,8 @@ private static void HandleButtonKeyUp(object? sender, KeyEventArgs eventArgs)
/// </summary>
private static void HandleButtonSystemColorsChanged(object? sender, EventArgs eventArgs)
{
if (sender is Button { IsDisposed: false } button)
if (sender is Button { IsDisposed: false } button &&
_buttonStates.TryGetValue(button, out ButtonVisualState? state) && !state.IsResettingNativeColors)
{
StopFeedback(button);
}
Expand Down Expand Up @@ -296,11 +301,6 @@ private static void HandleButtonMouseEnter(object? sender, EventArgs eventArgs)
{
if (sender is Button btn)
{
if (Form.ActiveForm != btn.FindForm())
{
return;
}

if (_buttonStates.TryGetValue(btn, out ButtonVisualState? state))
{
state.IsHovered = true;
Expand Down Expand Up @@ -493,7 +493,13 @@ private static void StartAnimationFeedback(Button btn)
btn.RunDwellAnimationAsync(
id: currentId,
animationIdGetter: () => Interlocked.Read(ref st.AnimId),
progressSetter: p => st.DwellProgress = p,
progressSetter: p =>
{
if (Interlocked.Read(ref st.AnimId) == currentId)
{
st.DwellProgress = p;
}
},
durationMs: 1000,
ct: st.FormCt
).SafeFireAndForget();
Expand Down Expand Up @@ -542,9 +548,31 @@ private static void StopFeedback(Button btn)
btn.AccessibleDescription = st.BaseDescription;

btn.Padding = st.OriginalPadding;
ResetNativeColors(btn, st);
btn.Invalidate();
}

/// <summary>
/// 使用自家按鈕的框架主題刷新路徑清除原生動畫快取;不改主題、尺寸或焦點。
/// Color.Empty 已先還原,因此下一幀直接以 Latest 的目前原生配色繪製。
/// </summary>
private static void ResetNativeColors(Button button, ButtonVisualState state)
{
if (button is not FeedbackButton feedbackButton || button.IsDisposed || state.IsResettingNativeColors)
{
return;
}

state.IsResettingNativeColors = true;
try
{
feedbackButton.ResetNativeColorTransition();
}
finally
{
state.IsResettingNativeColors = false;
}
}
/// <summary>
/// 為現有文字按鈕繪製一致的互動配色,不受 Net11 預設動作強調色覆蓋。
/// </summary>
Expand Down
2 changes: 1 addition & 1 deletion src/InputBox/MainForm.Designer.cs

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

133 changes: 132 additions & 1 deletion tests/InputBox.Tests/ButtonFeedbackRenderingTests.cs
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
using InputBox.Core.Extensions;
using InputBox.Core.Interop;
using System.Reflection;
using System.Runtime.ExceptionServices;
using Xunit;
Expand Down Expand Up @@ -412,6 +413,134 @@ private static double LinearComponent(byte component)
double value = component / 255.0;
return value <= 0.04045 ? value / 12.92 : Math.Pow((value + 0.055) / 1.055, 2.4);
}
/// <summary>逐幀檢查 Dwell 進出與未啟用視窗的配色,不能只等原生動畫完成再驗證。</summary>
[Theory(Skip = "Requires explicit UI test opt-in.",
SkipUnless = nameof(UiSmokeTestRequirements.IsEnabled), SkipType = typeof(UiSmokeTestRequirements))]
[InlineData(true, true)]
[InlineData(true, false)]
[InlineData(false, true)]
[InlineData(false, false)]
public void Render_DwellHandoff_PreservesEveryFrame(bool isDefault, bool active)
{
RunSta(() =>
{
using var form = new Form { ClientSize = new Size(300, 200), TopMost = true };
using var input = new TextBox { Top = 150 };
using var button = new FeedbackButton
{
Text = "Button text", Bounds = new Rectangle(10, 30, 240, 90),
FlatStyle = FlatStyle.Flat, VisualStylesMode = VisualStylesMode.Latest
};
using var lifetime = new CancellationTokenSource();
form.Controls.AddRange([input, button]);
button.AttachEyeTrackerFeedback("Button", button.Font, null, lifetime.Token);
if (isDefault)
{
form.AcceptButton = button;
}
Exception? frameFailure = null;
form.Shown += (_, _) =>
{
try
{
form.Activate();
input.Focus();
using var other = new Form { Location = new Point(850, 500), Size = new Size(100, 80) };
if (!active)
{
other.Show();
other.Activate();
}
Form target = active ? form : other;
_ = User32.ShowWindow(target.Handle, User32.ShowWindowCommand.Restore);
_ = User32.SetForegroundWindow(target.Handle);
target.Activate();
Settle(500);
if (active)
{
Assert.Same(form, Form.ActiveForm);
}
else
{
Assert.NotSame(form, Form.ActiveForm);
}
using var expected = new Bitmap(button.Width, button.Height);
button.DrawToBitmap(expected, button.ClientRectangle);
Color neutralBack = expected.GetPixel(25, 20);
Color neutralBorder = expected.GetPixel(2, 20);
Size size = button.Size;
Padding padding = button.Padding;
nint handle = button.Handle;
button.EnterHover();
for (int i = 0; i < 25; i++)
{
Settle(16);
using var hover = new Bitmap(button.Width, button.Height);
button.DrawToBitmap(hover, button.ClientRectangle);
Assert.Equal(button.BackColor.ToArgb(), hover.GetPixel(25, 20).ToArgb());
Assert.True(Contrast(hover.GetPixel(25, 20), button.ForeColor) >= 4.5);
int ink = 0;
for (int y = 25; y < 65; y++)
{
for (int x = 35; x < 205; x++)
{
if (hover.GetPixel(x, y).ToArgb() == button.ForeColor.ToArgb())
{
ink++;
}
}
}
Assert.True(ink > 10, "懸停文字未以配對前景色繪製。");
Assert.True(Contrast(hover.GetPixel(2, 20), hover.GetPixel(0, 20)) >= 3);
}
button.ExitHover();
for (int i = 0; i < 40; i++)
{
Application.DoEvents();
using var frame = new Bitmap(button.Width, button.Height);
button.DrawToBitmap(frame, button.ClientRectangle);
Assert.True(neutralBack.ToArgb() == frame.GetPixel(25, 20).ToArgb(), $"frame={i}; expected={neutralBack}; actual={frame.GetPixel(25, 20)}; back={button.BackColor}; fore={button.ForeColor}; active={form.ActiveControl?.GetType().Name}; default={button.NativeDefault}");
Assert.Equal(neutralBorder.ToArgb(), frame.GetPixel(2, 20).ToArgb());
CheckNeutralRendering(button, isDefault);
if (isDefault)
{
Assert.True(Contrast(frame.GetPixel(2, 20), frame.GetPixel(0, 20)) >= 3);
}
Assert.Equal(size, button.Size);
Assert.Equal(padding, button.Padding);
Assert.Equal(handle, button.Handle);
Assert.False(button.Focused);
Settle(16);
}
lifetime.Cancel();
other.Close();
}
catch (Exception ex)
{
frameFailure = ex;
}
finally
{
form.Close();
}
};
Application.Run(form);
if (frameFailure != null)
{
ExceptionDispatchInfo.Capture(frameFailure).Throw();
}
});

static void Settle(int milliseconds)
{
long start = Environment.TickCount64;
do
{
Application.DoEvents();
Thread.Sleep(1);
} while (Environment.TickCount64 - start < milliseconds);
}
}
/// <summary>
/// 以 WCAG 相對亮度檢查實際文字與背景的對比,不以色彩名稱推測可讀性。
/// </summary>
Expand Down Expand Up @@ -458,9 +587,10 @@ private static void RunSta(Action action)
/// <summary>
/// 僅在測試控制項本身觸發事件,不向任何其他視窗模擬輸入。
/// </summary>
private sealed class FeedbackButton : Button
private sealed class FeedbackButton : InputBox.Core.Controls.FeedbackButton
{
public VisualStylesMode ResolvedMode => EffectiveVisualStylesMode;
public bool NativeDefault => IsDefault;
public void Hover()
{
// 僅驗證繪製:不依賴 Windows 是否允許測試主機搶到前景。
Expand All @@ -482,6 +612,7 @@ public void SetProgress(float progress)
public void ReleaseSpace() => OnKeyUp(new KeyEventArgs(Keys.Space));
public void RefreshSystemColors() => OnSystemColorsChanged(EventArgs.Empty);
public void Press() => OnMouseDown(new MouseEventArgs(MouseButtons.Left, 1, 0, 0, 0));
public void EnterHover() => OnMouseEnter(EventArgs.Empty);
public void ExitHover() => OnMouseLeave(EventArgs.Empty);
}
}
Loading
Loading