path: root/doc/accessible.n

.\" Automatically generated by Pandoc 3.6.4
'\"
'\" Copyright (c) 2025 Kevin Walzer.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
.TH tk accessible n "" Tk "Tk Built-In Commands"
.so man.macros
.BS
.SH NAME
accessible \- Adds screenreader support for core Tk and ttk  widgets.
.SH SYNOPSIS
.nf
\fBtk accessible set_acc_role \fIwindow value\fR
\fBtk accessible set_acc_name \fIwindow value\fR
\fBtk accessible set_acc_description \fIwindow value\fR
\fBtk accessible set_acc_value \fIwindow value\fR
\fBtk accessible set_acc_state \fIwindow value\fR
\fBtk accessible set_acc_action \fIwindow value\fR
\fBtk accessible set_acc_help \fIwindow value\fR
\fBtk accessible get_acc_role \fIwindow \fR
\fBtk accessible get_acc_name \fIwindow\fR
\fBtk accessible get_acc_description \fIwindow\fR
\fBtk accessible get_acc_value \fIwindow \fR
\fBtk accessible get_acc_state \fIwindow\fR
\fBtk accessible get_acc_action \fIwindow \fR
\fBtk accessible get_acc_help \fIwindow\fR
\fBtk accessible add_acc_object \fIwindow\fR
\fBtk accessible emit_selection_change \fIwindow\fR
\fBtk accessible emit_focus_change \fIwindow\fR
\fBtk accessible check_screenreader\fR
.fi
.BE
.SH DESCRIPTION
.PP
The \fBtk accessible\fR command makes core Tk and ttk widgets
accessible to a screen reader.
.BE
.SH INTRODUCTION
.PP
All major computing platforms provide one or more API's to make GUI
applications accessible to visually-impaired users who work using screen
reader tools.
Screen readers provide auditory feedback to users of a GUI application,
and may provide additional or alternative methods to navigating
GUI's apart from standard keyboard navigation.
The \fBtk accessible \fRcommand layers a platform neutral API on top
of platform-specific API's to support accessibility on Linux/Unix,
macOS, and Windows.
.PP
The \fBtk accessible\fR command is intended to provide a basic
accessible-out-of-the-box experience for end users and
requires little additional work by developers.
If a screen reader is in operation, Tcl/Tk applications will be
accessible.
The \fBtk accessible \fRcommand set does allow for additional
customization on the part of developers.
And widgets that are not part of the core Tk widget set can enable
accessibility by using the tk accessible command set to specific the
accessible role, name, description, value, state (if applicable), and
action (if applicable).
.SH OPERATIONS
.PP
The following operations are available for the \fBtk accessible\fR
command:
.TP
\fBtk accessible set_acc_role \fIwindow value\fR
.
Assigns one of the following accessibility roles to a Tk widget: Button,
Canvas, Checkbutton, Combobox, Entry, Label, Listbox, Menu, Notebook,
Progressbar, Scale, Scrollbar, Spinbox, Table, Text, and Tree.
Tk and ttk widgets having similar roles, such as a button and a
ttk::button, will both be assigned the same accessibility role as these
widgets are the same from an accessibility standpoint.
.TP
\fBtk accessible set_acc_name \fIwindow value\fR
.
Short label identifying the widget.
Defaults to the accessibility role.
.TP
\fBtk accessible set_acc_description\fI window value\fR
.
Longer string providing additional detail about the widget.
Depending on the widget, may default to returning the widget's -text
option or some similar detail.
.TP
\fBtk accessible set_acc_value \fIwindow value\fR
.
Sets the widget's accessibility value.
For instance, with a scale widget, will return the current numeric value
of the scale.
.TP
\fBtk accessible set_acc_state \fIwindow value\fR
.
\fI \fRSets the widget's accessibility state, from one of the
standard Tk widget states.
.TP
\fBtk accessible set_acc_action \fIwindow value\fR
.
\fI \fRSets the command associated with the widget, if any.\fI
\fR
.TP
\fBtk accessible set_acc_help \fIwindow value\fR
.
String providing additional information on the widget and its purpose.
For instance, can provide details on specific keyboard navigation for
the widget.
.TP
\fBtk accessible get_acc_role \fIwindow \fR
.
Returns the widget's accessibility role.
.TP
\fBtk accessible get_acc_name \fIwindow\fR
.
Returns the widget's accessibility name.
.TP
\fBtk accessible get_acc_description \fIwindow\fR
.
Returns the widget's accessibility description.
.TP
\fBtk accessible get_acc_value \fIwindow \fR
.
Returns the widget's accessibility value.
.TP
\fBtk accessible get_acc_state \fIwindow\fR
.
Returns the widget's accessibility state.
.TP
\fBtk accessible get_acc_action \fIwindow \fR
.
Returns the widget's accessibility action.
.TP
\fBtk accessible get_acc_help \fIwindow\fR
.
Returns the widget's accessibility help.\fI \fR
.TP
\fBtk accessible add_acc_object \fIwindow\fR
.
Registers the widget with the platform's accessibility API and
enables accessibility for the widget.
.TP
\fBtk accessible emit_selection_change \fIwindow\fR
.
Notifies the system when selection, value or other data associated with
the widget changes.
.TP
\fBtk accessible emit_focus_change \fIwindow\fR
.
Notifies the accessibility system when focus changes.
.TP
\fBtk accessible check_screenreader\fR
.
Checks to see if the system is running a screen reader or other
accessibility process.
.PP
.SH ADDITIONAL NOTES
.PP
Some Tk GUI components, such as frames and panedwindows, are not
included in the accessibility API because they are just containers and
do not handle actions or data.
Also, the canvas is not included in the accessibility API because it is
a purely visual widget; the HTML5 canvas widget is not accessible to web
API's for the same reason.
Developers may choose to provide alternative data to provide information
on the canvas widget, such as labels or help text. Finally,
accessibility only runs in the main Tk interpreter, because of
potential conflicts in child interpreters; also, accessibility is not
supported under XQuartz (the X11 environment on macOS) because of too
many conflicts between the X11 and macOS versions of accessibility. 
.SH KEYWORDS
widget, tk
'\" Local Variables:
'\" mode: nroff
'\" End: