Commit b392acef authored by Carl Schwan's avatar Carl Schwan 🚴
Browse files

Pandoc convert rst to md

parent 536f9f2b
# Minimal makefile for Sphinx documentation
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
\ No newline at end of file
Accessibility Checklist
This is a list of common things you should check for to have great
:doc:`accessibility <index>` for your application or widgets.
Keyboard Navigation
- Efficient keyboard access is provided for all application features.
- All windows have a logical keyboard navigation order.
- The correct tab order is used for controls whose enabled state is
dependent on checkboxes, radio buttons or toggle buttons.
- Keyboard access to application-specific functions does not override
existing system accessibility features.
- The application provides more than one method to perform keyboard tasks
whenever possible.
- There are alternative keyboard shortcuts wherever possible.
- Frequently-accessed keyboard shortcuts should be physically easy to access
and not require awkwardly bending the wrist or fingers.
- The application does not require repetitive, simultaneous keypresses.
- The application provides keyboard equivalents for all mouse functions.
- The application provides keyboard equivalents for all mouse-based functions,
including selecting, moving, and resizing items.
- The application does not use any general navigation functions to
trigger operations.
- All keyboard-invoked menus, windows, and tooltips appear near the object
they relate to.
The following keyboard operations should be tested. Don't use the mouse in any
part of this test.
- Using only keyboard commands, move the focus through all menu bars in the
- Confirm that:
- Context-sensitive menus display correctly.
- Any functions listed on the toolbar can be triggered using the keyboard.
- Every control in the client area of the application can be focused and
- Text and objects within the client area can be selected.
- Any keyboard enhancements or shortcuts are working as designed.
Mouse Interaction
- No operations depend on input from the right or middle mouse buttons.
- All mouse operations can be cancelled before they are complete.
- Visual feedback is provided throughout drag and drop operations
- The mouse pointer is never moved by the application, or its
movement restricted to part of the screen by the application.
Graphical Elements
- There are no hard-coded graphical attributes such as line, border or
shadow thickness.
- All multi-color graphical elements can be shown in monochrome only,
where possible.
- All interactive GUI elements are easily distinguishable from static GUI
- An option to hide non-essential graphics is provided.
See :doc:`units </layout/units>` for more information on how to use KDE's base
units to avoid hardcoded size values.
Test the application using a screen reader and confirm that:
- Labels and text are being read correctly, including menus and toolbars.
- Object information is read correctly.
Fonts and Text
- No font styles or sizes are hard-coded.
- An option to turn off graphical backdrops behind text is provided.
- All labels have names that make sense when taken out of context.
- No label names are used more than once in the same window.
- Label positioning is consistent throughout the application.
- All static text labels that identify other controls end in a colon (:).
- Static text labels that identify other controls immediately precede
those controls in the tab order.
- An alternative to WYSIWYG is provided. For example, the ability to
specify different screen and printer fonts in a text editor.
See :doc:`typography </style/typography>` for more information on how to
avoid hardcoded font sizes and :doc:`labels </style/writing/labels>` for more
details about labels.
- Change the font in the application and confirm that the settings are
- Test the application by changing colors and confirm that all settings are
- If magnification is available, test the font, color, and size using the
magnification option.
Color and Contrast
- Application colors are not hard-coded, but either use colors from
current desktop theme or an application setting.
- Color is only used as an enhancement, and not as the only means to
convey information or actions.
- The application supports all available
:doc:`high contrast themes </style/color/high>` and settings.
- The software is not dependent on any particular
:doc:`high contrast themes </style/color/high>` or settings.
See :doc:`the HIG's page about color </style/color/index>` for more information.
- Print screenshots to a black and white printer and confirm that all
information is visible.
- Test applications using only black and white high-contrast settings and
confirm that all information is conveyed correctly.
- Test that the application provides at least three combinations of color
schemes and that high-contrast schemes are available (e.g. white on black or
yellow on blue).
- Turn on high-contrast settings in the System Settings and confirm that
the application respects these settings.
- Test various themes to ensure that the software is working for all the
available settings.
- The application provides the ability to scale or magnify the work area.
- The application's functionality is not affected by changing the
magnification or scale settings.
- Sound is not used as the only means of conveying any items of
- The user can configure the frequency and volume of all sounds and
warning beeps.
There should be an option in the application to show audio alerts visually.
Test that the audio is working correctly by enabling sound in the System
Settings and then perform the following actions:
- Perform an action that should generate an audio alert and confirm that the
application is working as designed.
- Verify that the application works correctly when increasing or decreasing
the volume.
- Confirm that warning messages and alerts can be heard correctly in a noisy
work environment.
- There are no flashing or blinking elements with a frequency greater than
2Hz or lower than 55Hz.
- Any flashing or blinking is confined to small areas of the screen.
- If animation is used, an option is available to turn it off before it is
first shown.
Verify that an option is available to stop animation and that it is working as
Turn the animation off. Confirm that all information is still conveyed
Keyboard Focus
- When a window is opened, focus starts at the most commonly-used control.
- Current input focus position is clearly displayed at all times.
- Input focus is shown in exactly one window or view at all times.
- Appropriate audio or visual feedback is provided when the user attempts
to navigate past either end of a group of related objects.
- The default audio or visual warning signal is played when the user
presses an inappropriate key.
- There is sufficient audio information for the visual focus that the user
can figure out what to do next.
- Set the focus to the actual control. Don't just highlight an area.
- When using assistive technologies, such as a screen reader or braille
device, the current program indicates the position and content of the visual
focus indicator.
- Verify when moving among objects that the visual focus indicator is
easy to identify.
- Keyboard navigation through the software and menus should be clearly visible
when the focus moves.
- Confirm that the screen reader is tracking the visual focus indicator as you
navigate using a keyboard.
- Run a screen magnification program (if available) and verify that the
magnifier can track the visual focus indicator as you navigate using the
keyboard and mouse.
- There are no hard-coded time-outs or time-based features in the
- The display or hiding of important information is not triggered solely
by movement of the mouse pointer.
- Test all messages to confirm that the user is notified before a message
times out and is given the option to indicate that more time is needed.
- Make sure an option has been included to adjust the response time and
confirm that it is working as designed.
- All documentation is in an accessible format, with textual alternate
descriptions provided for all figures and diagrams.
- The documentation includes a section that covers all the application's
accessibility features.
Test ASCII text documentation with a screen reader to confirm that it is clear
and precise and can be read by assistive technologies.
Test HTML applications using a web browser and screen reader to confirm that the
documentation is accessible to assistive technologies.
Note: There are web accessibility guidelines available at
Confirm the following information is included in the documentation:
- State if the application does not support the standard keyboard access used
by the OS.
- Identify if there are unique keyboard commands.
- Identify any unique accessibility features.
- If an action is documented for the mouse, make sure there is an alternative
for using the keyboard.
.. note::
The content of this page is based on
.. toctree::
:maxdepth: 1
Accessibility is the design of products, devices, services, or environments
for people with disabilities. The concept of accessible design and
practice of accessible development ensures both "direct access" (i.e.
unassisted) and "indirect access" meaning compatibility with a person's
assistive technology.
*Source*: `<>`_
But good accessibility benefits all users. A working keyboard navigation and
well choosen colors and fonts setting not only help people with low vision,
blindness, deafness, cognitive or motor impairments or
situational disabilities, like a broken hand, but also improve the workflow and
usability for all users.
Fonts and Colors
Many users have some deficiencies when it comes to seeing. This does not always
mean that they are blind. For some people it's enough when
:doc:`fonts </style/typography>` are clear and the
:doc:`color scheme </style/color/index>` can be adjusted. This is something
every application should do in any case, so here is the list:
- Follow the user interface guidelines! This will get you quite far.
- Check that color scheme changes apply |br|
Try switching to a :doc:`dark color scheme </style/color/dark>` and see that
your application is still usable
- Test changing the :doc:`font size </style/typography>`
- Switch to different fonts and see that they apply
- Increase the font size and make sure that the application layout still
When you have problems seeing, the mouse is quite hard to use. The keyboard is a
lot more reliable. Therefore it is important that applications can be used with
the keyboard. For some users, using a mouse is difficult because of motor skill
issues. Making applications keyboard accessible benefits everyone, since it
allows us to use shortcuts to use the applications more efficiently.
- Try to operate your application with the TAB key
- Make sure that the tab order is correct
- Start your application and do a common task without using the mouse
Note where you had trouble and think about possible improvements in the
UI or keyboard shortcuts that are missing
Screen Reader
There is a lot you can help with to make applications accessible to screen
reader users. We refer to screen readers and other assistive technology often as
.. TODO::
Setup Screen Readers with KDE
Gives detailed setup instructions for screen readers.
This section gives a quick intro what to look for when testing an application
with a screen reader.
Once you have an application running with the screen reader: Make sure Orca says
something intelligible for all elements. When it reads a GUI element it should
say the label and type, eg: "File, Menu" or "OK, Button". When you have a button
that does not have a label, maybe because it shows a picture only, add
accessibility hints. Try navigating the more troublesome elements - comboboxes
and lists and such.
Fixing missing information
For many things there are usually easy fixes involving no advanced programming
skills but just fixing some details.
For this tutorial we assume that you are dealing with a QWidget that is seen by
the AT but does for example give not enough information.
There are two important properties that every QWidget has: an "Accessible Name"
and an "Accessible Description". The name is short, for example the label on a
button. It should always be short. The description on the other hand is the more
verbose "this button does foo and then bar". Qt will try hard to return
something for the name. In case of a button, usually the text on the button is
returned. But if your button has text that only makes sense when seeing the
arrangement of buttons, or only has an image as label, then you need to help the AT
read the button. If you don't, it will only say the type of the widget, "Button"
which is not very helpful information.
Fixing Accessible Name and Description
Fire up Qt designer if the app uses .ui files. You'll find the properties and
can type the name/description right in. After saving the file, rebuild and
install the application. You are done, submit a patch to fix the ui file.
If the widget is created in the code, you just need to find where it's initialized.
Once you find it (usually where it's created), add some code to it:
.. code-block:: c++
button->setAccessibleDescription(i18n("Opens a file dialog to select a new
Send your patch.
Sometimes you also want to override the label for a different reason. One of my
test apps was the calculator example from Qt. It has a memory recall button
labelled "MR". Orca will insist on this being the "Mister" button, unless told
Complex Widgets
For some widgets the above is not enough. You will have to create
QAccessibleInterfaces for widgets that you create yourself. For example Kate has
an interface for its text editing area. Sometimes you need to inherit
QAccessibleTextInterface or QAccessibleValueInterface in order to make the
widgets properly accessible. Refer to the Qt documentation how to do this.
Currently there is no support for accessibility in QGraphicsView.
Qt Quick (QML)
For Qt 5, refer to the
`documentation <>`_ on how to create
accessible QML applications. The concepts are generally the same as for QWidget
based applications.
An emblem displays unusual or non-default status information about an icon
or image. For example, an emblem could indicate that a folder is shared, that a
disk is unmounted, or that an app has unread notifications.
.. figure:: /img/emblem-public-on-folder.png
An emblem indicating that a folder is shared on the network
.. figure:: /img/emblem-notification-kmail.png
An emblem indicating that a mail program has 15 unread emails
- Emblems are used to badge icons, images, or other visually discrete elements
in a file manager, system tray, task manager, dock, image view, etc. Emblems
should not be applied to textual content.
- Use emblems to display that an icon or image has some unusual status
associated with it, or that there are unread notifications. Don't use
emblems to display an element's normal, common, or typical status. For
example, an emblem could indicate that a folder is read-only or is a symlink,
or that a disk is unmounted or encrypted. An emblem should not be used to
indicate that a folder is read-write or that a disk is mounted.
- Emblems that indicate status should be placed in the bottom-right corner. If
additional status emblems are needed, they should be placed in other corners
in a clockwise order.
- Emblems that indicate unread notifications should be located in the
top-right corner.
- Use the minimum number of emblems and don't overwhelm the icon itself.
Three is usually too many.
An emblem that indicates unread notifications should take the form of a
light-colored number inside a blue circle. The circle can become "pill-shaped"
if the number is very large.
.. figure:: /img/emblem-notification-small.png
Notification emblem
.. figure:: /img/emblem-notification-large.png
Notification emblem with a large number
For symbolic icon emblems, see :doc:`/style/icons/monochrome/emblem`.
User Assistance
.. toctree::
:maxdepth: 1
User assistance
User Assistance guidance considers interface elements that inform users of the application’s activity and status, as well as elements dedicated to user education. This includes online help, error alerts, and status alerts.
* :doc:`emblem`
* :doc:`inline`
* :doc:`message`
* :doc:`progress`
* :doc:`statusbar`
* :doc:`tooltip`
* :doc:`aboutview`
Inline Message
.. container:: intend
|desktopicon| |mobileicon|
A inline message is a small panel that informs users of a non-critical problem
or special condition. It is embedded in the content and should not overlap
content or controls. The panel has four visual style options which can be used
for neutral messages, success conditions, warnings, and errors. It can also be
given buttons.
.. figure:: /img/Message5.png
:alt: Different levels of inline messages.
:scale: 80%
The four different levels of inline messages.
.. figure:: /img/Message-example.png
An inline message is used for feeback after an upload has been completed.
- Use inline messages in cases of non-critical problems that user can
- Use :iconred:`negative feedback` (aka error) as a secondary indicator of
failure, e.g. if a transaction was not completed successfully.
- Show the information on a warning level in case of relevant
information that does not concern the current workflow, e.g. No
Internet connection available.
- Use :noblefir:`positive feedback` to notify about user-initiated processes,
e.g. to indicate completion of background tasks.
- Use :plasmablue:`opportunistic interaction` (aka notification) to acknowledge
the user about options that he or she might be interested in, e.g.
"Remember password?"
- Display the information immediately.
- When users dismiss the inline message, don't display any other UI or start
any other side effect.
- Don't add controls to the inline message other than action buttons
for opportunistic interaction.
- Consider to show a :doc:`notification </platform/notification>` if
information does not concern the current workflow.
Is this the right control? / Behavior
Negative Feedback
The inline message should be used as a secondary indicator of failure:
the first indicator is for instance that the action the user expected to
happen did not happen.
Example: User fills a form, clicks "Submit".
- Expected feedback: form closes