Skip to content

Commit

Permalink
Additional accessibility support (#412)
Browse files Browse the repository at this point in the history 
* Expose getter for currently focused widget.

* Remove a level of indirection, exposing the widget event on the top level.

* Align widget descriptions more closely with common screen reader conventions.

Note that this work isn't complete--I'll correct more cases as I add more widgets and become familiar with their structures.

* Add support for click and double-click events.

* Add `ValueChanged` events, with initial support for text.

* Add support for reporting cursor selection changes.

* Track enabled/disabled status.

* Move `prev_text` off of the widget struct.

* Get rid of `has_widget_info` and push events directly where it makes sense.

* Fix typo.

* s/text_value/current_text_value/

* Use a `RangeInclusive` for text selection.

* Invert parameters.

* Various fixes.

* Only dispatch `SelectionChanged` if the selection actually changes.
* Fix missing focus events.

* If values for `current_text` and `prev_text` are unchanged, filter out the previous value.

* No need to pass in `&mut prev_text` everywhere

* Appease Clippy.

* Mask password fields in generated events.

Co-authored-by: Emil Ernerfeldt <[email protected]>
  • Loading branch information
@ndarilek @emilk
ndarilek and emilk authored Jun 12, 2021
1 parent 2b4d3fa commit 508f6d9
Show file tree
Hide file tree
Showing 4 changed files with 154 additions and 35 deletions.
117 changes: 89 additions & 28 deletions egui/src/data/output.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,11 @@ impl Output {
// only describe last event:
if let Some(event) = self.events.iter().rev().next() {
match event {
OutputEvent::WidgetEvent(WidgetEvent::Focus, widget_info) => {
OutputEvent::Clicked(widget_info)
| OutputEvent::DoubleClicked(widget_info)
| OutputEvent::FocusGained(widget_info)
| OutputEvent::TextSelectionChanged(widget_info)
| OutputEvent::ValueChanged(widget_info) => {
return widget_info.description();
}
}
Expand Down Expand Up @@ -206,67 +210,87 @@ impl Default for CursorIcon {
/// In particular, these events may be useful for accessability, i.e. for screen readers.
#[derive(Clone, PartialEq)]
pub enum OutputEvent {
// A widget was clicked.
Clicked(WidgetInfo),
// A widget was double-clicked.
DoubleClicked(WidgetInfo),
/// A widget gained keyboard focus (by tab key).
WidgetEvent(WidgetEvent, WidgetInfo),
FocusGained(WidgetInfo),
// Text selection was updated.
TextSelectionChanged(WidgetInfo),
// A widget's value changed.
ValueChanged(WidgetInfo),
}

impl std::fmt::Debug for OutputEvent {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::WidgetEvent(we, wi) => write!(f, "{:?}: {:?}", we, wi),
Self::Clicked(wi) => write!(f, "Clicked({:?})", wi),
Self::DoubleClicked(wi) => write!(f, "DoubleClicked({:?})", wi),
Self::FocusGained(wi) => write!(f, "FocusGained({:?})", wi),
Self::TextSelectionChanged(wi) => write!(f, "TextSelectionChanged({:?})", wi),
Self::ValueChanged(wi) => write!(f, "ValueChanged({:?})", wi),
}
}
}

#[derive(Clone, Copy, Debug, PartialEq)]
pub enum WidgetEvent {
/// Keyboard focused moved onto the widget.
Focus,
// /// Started hovering a new widget.
// Hover, // TODO: cursor hovered events
}

/// Describes a widget such as a [`crate::Button`] or a [`crate::TextEdit`].
#[derive(Clone, PartialEq)]
pub struct WidgetInfo {
/// The type of widget this is.
pub typ: WidgetType,
// Whether the widget is enabled.
pub enabled: bool,
/// The text on labels, buttons, checkboxes etc.
pub label: Option<String>,
/// The contents of some editable text (for `TextEdit` fields).
pub edit_text: Option<String>,
pub current_text_value: Option<String>,
// The previous text value.
pub prev_text_value: Option<String>,
/// The current value of checkboxes and radio buttons.
pub selected: Option<bool>,
/// The current value of sliders etc.
pub value: Option<f64>,
// Selected range of characters in [`Self::current_text_value`].
pub text_selection: Option<std::ops::RangeInclusive<usize>>,
}

impl std::fmt::Debug for WidgetInfo {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let Self {
typ,
enabled,
label,
edit_text,
current_text_value: text_value,
prev_text_value,
selected,
value,
text_selection,
} = self;

let mut s = f.debug_struct("WidgetInfo");

s.field("typ", typ);
s.field("enabled", enabled);

if let Some(label) = label {
s.field("label", label);
}
if let Some(edit_text) = edit_text {
s.field("edit_text", edit_text);
if let Some(text_value) = text_value {
s.field("text_value", text_value);
}
if let Some(prev_text_value) = prev_text_value {
s.field("prev_text_value", prev_text_value);
}
if let Some(selected) = selected {
s.field("selected", selected);
}
if let Some(value) = value {
s.field("value", value);
}
if let Some(text_selection) = text_selection {
s.field("text_selection", text_selection);
}

s.finish()
}
Expand All @@ -276,10 +300,13 @@ impl WidgetInfo {
pub fn new(typ: WidgetType) -> Self {
Self {
typ,
enabled: true,
label: None,
edit_text: None,
current_text_value: None,
prev_text_value: None,
selected: None,
value: None,
text_selection: None,
}
}

Expand Down Expand Up @@ -319,9 +346,29 @@ impl WidgetInfo {
}

#[allow(clippy::needless_pass_by_value)]
pub fn text_edit(edit_text: impl ToString) -> Self {
pub fn text_edit(prev_text_value: impl ToString, text_value: impl ToString) -> Self {
let text_value = text_value.to_string();
let prev_text_value = prev_text_value.to_string();
let prev_text_value = if text_value == prev_text_value {
None
} else {
Some(prev_text_value)
};
Self {
current_text_value: Some(text_value),
prev_text_value,
..Self::new(WidgetType::TextEdit)
}
}

#[allow(clippy::needless_pass_by_value)]
pub fn text_selection_changed(
text_selection: std::ops::RangeInclusive<usize>,
current_text_value: impl ToString,
) -> Self {
Self {
edit_text: Some(edit_text.to_string()),
text_selection: Some(text_selection),
current_text_value: Some(current_text_value.to_string()),
..Self::new(WidgetType::TextEdit)
}
}
Expand All @@ -330,14 +377,17 @@ impl WidgetInfo {
pub fn description(&self) -> String {
let Self {
typ,
enabled,
label,
edit_text,
current_text_value: text_value,
prev_text_value: _,
selected,
value,
text_selection: _,
} = self;

// TODO: localization
let widget_name = match typ {
let widget_type = match typ {
WidgetType::Hyperlink => "link",
WidgetType::TextEdit => "text edit",
WidgetType::Button => "button",
Expand All @@ -353,32 +403,43 @@ impl WidgetInfo {
WidgetType::Label | WidgetType::Other => "",
};

let mut description = widget_name.to_owned();
let mut description = widget_type.to_owned();

if let Some(selected) = selected {
if *typ == WidgetType::Checkbox {
description += " ";
description += if *selected { "checked" } else { "unchecked" };
let state = if *selected { "checked" } else { "unchecked" };
description = format!("{} {}", state, description);
} else {
description += if *selected { "selected" } else { "" };
};
}

if let Some(label) = label {
description += " ";
description += label;
description = format!("{}: {}", label, description);
}

if let Some(edit_text) = edit_text {
description += " ";
description += edit_text;
if typ == &WidgetType::TextEdit {
let text;
if let Some(text_value) = text_value {
if text_value.is_empty() {
text = "blank".into();
} else {
text = text_value.to_string();
}
} else {
text = "blank".into();
}
description = format!("{}: {}", text, description);
}

if let Some(value) = value {
description += " ";
description += &value.to_string();
}

if !enabled {
description += ": disabled";
}
description.trim().to_owned()
}
}
5 changes: 5 additions & 0 deletions egui/src/memory.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -315,6 +315,11 @@ impl Memory {
self.interaction.focus.id == Some(id)
}

/// Which widget has keyboard focus?
pub fn focus(&self) -> Option<Id> {
self.interaction.focus.id
}

pub(crate) fn lock_focus(&mut self, id: Id, lock_focus: bool) {
if self.had_focus_last_frame(id) && self.has_focus(id) {
self.interaction.focus.is_focus_locked = lock_focus;
Expand Down
17 changes: 13 additions & 4 deletions egui/src/response.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -428,10 +428,19 @@ impl Response {
///
/// Call after interacting and potential calls to [`Self::mark_changed`].
pub fn widget_info(&self, make_info: impl Fn() -> crate::WidgetInfo) {
if self.gained_focus() {
use crate::output::{OutputEvent, WidgetEvent};
let widget_info = make_info();
let event = OutputEvent::WidgetEvent(WidgetEvent::Focus, widget_info);
use crate::output::OutputEvent;
let event = if self.clicked() {
Some(OutputEvent::Clicked(make_info()))
} else if self.double_clicked() {
Some(OutputEvent::DoubleClicked(make_info()))
} else if self.gained_focus() {
Some(OutputEvent::FocusGained(make_info()))
} else if self.changed {
Some(OutputEvent::ValueChanged(make_info()))
} else {
None
};
if let Some(event) = event {
self.ctx.output().events.push(event);
}
}
Expand Down
50 changes: 47 additions & 3 deletions egui/src/widgets/text_edit.rs
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
use crate::{util::undoer::Undoer, *};
use crate::{output::OutputEvent, util::undoer::Undoer, *};
use epaint::{text::cursor::*, *};
use std::ops::Range;

Expand Down Expand Up @@ -393,6 +393,7 @@ impl<'t, S: TextBuffer> TextEdit<'t, S> {
lock_focus,
} = self;

let prev_text = text.clone();
let text_style = text_style
.or(ui.style().override_text_style)
.unwrap_or_else(|| ui.style().body_text_style);
Expand Down Expand Up @@ -496,6 +497,8 @@ impl<'t, S: TextBuffer> TextEdit<'t, S> {
ui.output().cursor_icon = CursorIcon::Text;
}

let mut text_cursor = None;
let prev_text_cursor = state.cursorp;
if ui.memory().has_focus(id) && enabled {
ui.memory().lock_focus(id, lock_focus);

Expand Down Expand Up @@ -554,7 +557,6 @@ impl<'t, S: TextBuffer> TextEdit<'t, S> {
&& text_to_insert != "\r"
{
let mut ccursor = delete_selected(text, &cursorp);

insert_text(&mut ccursor, text, text_to_insert);
Some(CCursorPair::one(ccursor))
} else {
Expand Down Expand Up @@ -667,6 +669,7 @@ impl<'t, S: TextBuffer> TextEdit<'t, S> {
}
}
state.cursorp = Some(cursorp);
text_cursor = Some(cursorp);

state
.undoer
Expand Down Expand Up @@ -709,7 +712,48 @@ impl<'t, S: TextBuffer> TextEdit<'t, S> {

ui.memory().id_data.insert(id, state);

response.widget_info(|| WidgetInfo::text_edit(&*text));
let selection_changed = if let (Some(text_cursor), Some(prev_text_cursor)) =
(text_cursor, prev_text_cursor)
{
text_cursor.primary.ccursor.index != prev_text_cursor.primary.ccursor.index
|| text_cursor.secondary.ccursor.index != prev_text_cursor.secondary.ccursor.index
} else {
false
};

let masked = if self.password {
let prev_text_len = prev_text.to_string().len();
let text_len = text.to_string().len();
Some(("*".repeat(prev_text_len), "*".repeat(text_len)))
} else {
None
};

if response.changed {
if let Some((prev_text, text)) = masked {
response.widget_info(|| WidgetInfo::text_edit(&prev_text, &text));
} else {
response.widget_info(|| WidgetInfo::text_edit(&prev_text, &text));
}
} else if selection_changed {
let text_cursor = text_cursor.unwrap();
let char_range =
text_cursor.primary.ccursor.index..=text_cursor.secondary.ccursor.index;
let info = if let Some((_, text)) = masked {
WidgetInfo::text_selection_changed(char_range, text)
} else {
WidgetInfo::text_selection_changed(char_range, &*text)
};
response
.ctx
.output()
.events
.push(OutputEvent::TextSelectionChanged(info));
} else if let Some((prev_text, text)) = masked {
response.widget_info(|| WidgetInfo::text_edit(&prev_text, &text));
} else {
response.widget_info(|| WidgetInfo::text_edit(&prev_text, &text));
}
response
}
}
Expand Down

0 comments on commit 508f6d9

Please sign in to comment.