Module zng::access

Accessibility service, events and properties.

The accessibility API helps external tools to query the state of a widget and issue programmatic commands to it. This API is mainly used by accessibility assistants like NVDA to narrate and operate the current screen, but usage is not limited to accessibility, the access provided to widgets also enables external automation tools and internal operations such as programmatically clicking a button.

Metadata

Metadata is collected on demand during info build, there is a small performance impact to this so the access builder is only available after accessibility was requested at least once for the window.

use zng::prelude_wgt::*;

match_node_leaf(|op| match op {
    UiNodeOp::Info { info } => {
        if let Some(mut a) = info.access() {
            // accessibility requested for this window
            a.set_label("label");
        }
    }
    _ => {}
})

You can also enables access info programmatically using WINDOW.enable_access(), if the view-process did not request accessibility the window still skips sending the access tree, so the performance impact is minimal.

use zng::prelude::*;

WINDOW.enable_access();

Window! {
    child = Button! { id = "btn-1"; child = Text!("Button 1") };

    widget::on_info_init = hn!(|_| {
        let btn_info = WINDOW.info().get("btn-1").unwrap().access().unwrap();
        let txt_info = btn_info.info().children().next().unwrap().access().unwrap();
     
        assert_eq!(None, btn_info.label());
        assert!(btn_info.labelled_by_child());
        assert_eq!(Some(Txt::from("Button 1")), txt_info.label());
    });
}

When accessibility info is build you it can be accessed using WidgetInfo::access. Note that this is a low level access info, provided as it was set by the widgets, in the example above the label value is only found on the text widget, accessibility tools will use the text label for the button.

Properties

Properties of this module only define metadata that indicate that the widget implements a certain UI pattern, by setting a property you must make sure that the widget actually implements said pattern, for this reason most of the accessibility definitions are provided by the widget implementations.

In the example below a TextInput! widget instance changes its role to AccessRole::SearchBox, the default role is set by the widget itself to AccessRole::TextInput, this usage of the widget has a more specific role so it can be changed, in this case it is up to the app developer to actually implement the search.

use zng::prelude::*;
use zng::access::{access_role, AccessRole};

let search_txt = var(Txt::from(""));
TextInput! {
    access_role = AccessRole::SearchBox;
    placeholder_txt = "search";
    txt = search_txt;
}

Service & Events

The ACCESS service provides methods that control widgets by notifying accessibility events. Access events are handled by widgets even when accessibility is disabled.

In the example below the button shows and hides the tooltip of a different widget using ACCESS.show_tooltip and ACCESS.hide_tooltip.

use zng::prelude::*;

let mut show_tooltip = false;
Window! {
    child_align = Align::CENTER;
    child = Stack!(top_to_bottom, 50, ui_vec![
        Button! {
            on_click = hn!(|_| {
                use zng::access::ACCESS;

                show_tooltip = !show_tooltip;
                if show_tooltip {
                    ACCESS.show_tooltip(WINDOW.id(), "tooltip-anchor");
                } else {
                    ACCESS.hide_tooltip(WINDOW.id(), "tooltip-anchor");
                }
            });
            child = Text!("Toggle Tooltip");
        },
        Text! {
            id = "tooltip-anchor";
            txt = "tooltip anchor";
            tooltip = Tip!(Text!("Tooltip"));
        }
    ])
}

Full API

See zng_app::access and zng_wgt_access for the full API.

Structs

• ACCESS
  Accessibility service.
• AccessClickArgs
  Arguments for the ACCESS_CLICK_EVENT.
• AccessExpanderArgs
  Arguments for the ACCESS_EXPANDER_EVENT.
• AccessIncrementArgs
  Arguments for the ACCESS_INCREMENT_EVENT.
• AccessInitedArgs
  Arguments for the ACCESS_INITED_EVENT.
• AccessNumberArgs
  Arguments for the ACCESS_NUMBER_EVENT.
• AccessScrollArgs
  Arguments for the ACCESS_SCROLL_EVENT.
• AccessSelectionArgs
  Arguments for the ACCESS_SELECTION_EVENT.
• AccessTextArgs
  Arguments for the ACCESS_TEXT_EVENT.
• AccessToolTipArgs
  Arguments for the ACCESS_TOOLTIP_EVENT.
• AutoComplete
  Defines how inputting text could trigger display of one or more predictions of the user’s intended value.
• Invalid
  Defines the kind of invalid data error of a widget.

Enums

• AccessCmdName
  Accessibility command without associated data.
• AccessRole
  Accessibility role of a node in the accessibility tree.
• CurrentKind
  Kind of current item a widget represents.
• LiveIndicator
  Defines how a live update is communicated to the user.
• Orientation
  Widget orientation.
• Popup
  Popup type.
• ScrollCmd
  Accessibility scroll command.
• SortDirection
  Sort direction.

Statics

• ACCESS_CLICK_EVENT
  Run the primary or context click action.
• ACCESS_EXPANDER_EVENT
  Expand or collapse the widget content.
• ACCESS_INCREMENT_EVENT
  Increment or decrement the widget value by steps.
• ACCESS_INITED_EVENT
  Accessibility info is now required for the window.
• ACCESS_NUMBER_EVENT
  Replace the number value.
• ACCESS_SCROLL_EVENT
  Run a scroll command.
• ACCESS_SELECTION_EVENT
  Select text.
• ACCESS_TEXT_EVENT
  Replace the text content.
• ACCESS_TOOLTIP_EVENT
  Show or hide the widget’s tooltip.

Functions

• access_commands
  P Append supported access commands.
• access_role
  P Sets the widget kind for accessibility services.
• accessible
  P Defines if the widget and descendants can be present in the accessibility info tree.
• active_descendant
  P Identifies the currently active widget when focus is on a composite widget.
• auto_complete
  P Set how input text triggers display of one or more predictions of the user’s intended value for a ComboBox, SearchBox, or TextInput.
• checked
  P If the widget is checked (Some(true)), unchecked (Some(false)), or if the checked status is indeterminate (None).
• col_count
  P Sets the total number of columns in a Table, Grid, or TreeGrid when not all columns are present in tree.
• col_index
  P Sets the widget’s column index in the parent table or grid.
• col_span
  P Sets the number of columns spanned by the widget in the parent table or grid.
• controls
  P Append widgets whose contents or presence are controlled by this widget to the controlled list.
• current
  P Indicates that the widget represents the current item of a kind.
• described_by
  P Append widgets that describes this widget to the descriptors list.
• details
  P Append widgets that provide additional information related to this widget to the details list.
• error_message
  P Indicates that the widget is an error message for the invalid_wgt.
• expanded
  P Indicate that the widget toggles the visibility of related widgets.
• flows_to
  P Append options for next widget to be read by screen readers.
• invalid
  P Indicates that the widget’s data is invalid with optional kinds of errors.
• item_count
  P Sets the number of items in the current set of list items or tree items when not all items in the set are present in the tree.
• item_index
  P Sets the widget’s number or position in the current set of list items or tree items when not all items are present in the tree.
• label
  P Sets a custom name for the widget in accessibility info.
• labelled_by
  P Append widgets that provide additional information related to this widget.
• labelled_by_child
  P Uses the accessible children as labelled_by.
• level
  P Sets the hierarchical level of the widget within a parent scope.
• live
  P Indicate that the widget can change, how the change can be announced, if atomic the entire widget must be re-read, if busy the screen reader must wait until the change completes.
• modal
  P Sets if the widget is modal when displayed.
• multi_selectable
  P Indicates that the user may select more than one item from the current selectable descendants.
• on_access_click
  P Access requested a click.
• on_access_expander
  P Access requested to expand or collapse the widget content.
• on_access_increment
  P Access requested to increment or decrement the widget value by steps.
• on_access_number
  P Access requested a number input.
• on_access_scroll
  P Access requested a scroll command.
• on_access_selection
  P Access requested a text selection.
• on_access_text
  P Access requested a text input/replace.
• on_access_tooltip
  P Access requested to show or hide the widget’s tooltip.
• on_pre_access_click
  P Preview on_access_click event.
• on_pre_access_expander
  P Preview on_access_expander event.
• on_pre_access_increment
  P Preview on_access_increment event.
• on_pre_access_number
  P Preview on_access_number event.
• on_pre_access_scroll
  P Preview on_access_scroll event.
• on_pre_access_selection
  P Preview on_access_selection event.
• on_pre_access_text
  P Preview on_access_text event.
• on_pre_access_tooltip
  P Preview on_access_tooltip event.
• orientation
  P Indicates whether the widget’s orientation is horizontal, vertical, or unknown/ambiguous.
• owns
  P Append owned widgets that are children of this widget, but are not already children in the info tree.
• placeholder
  P Short hint (a word or short phrase) intended to help the user with data entry when a form control has no value.
• popup
  P Indicates the availability and type of interactive popup widget.
• read_only
  P Indicates that the widget is not editable, but is otherwise operable.
• required
  P Indicates that user input is required on the widget before a form may be submitted.
• row_count
  P Sets the total number of rows in a Table, Grid, or TreeGrid when not all rows are present in the tree.
• row_index
  P Sets the widget’s row index in the parent table or grid.
• row_span
  P Sets the number of rows spanned by the widget in the parent table or grid.
• scroll_horizontal
  P Sets the amount scrolled horizontally if allowed.
• scroll_vertical
  P Sets the amount scrolled vertically if allowed.
• selected
  P Indicates that the widget is selected.
• sort
  P Sets the sort direction for the table or grid items.
• value
  P Set the current value.
• value_max
  P Set the maximum value (inclusive).
• value_min
  P Set the minimum value (inclusive).