Form description for screen readers

How to integrate with platform screen readers?

Understanding screen readers

Screen readers are special system applications that transform the application's graphical user interface into speech. The behavior may change between screen reader implementations, but, basically, each widget is named and described by speech. On some workstation operating systems, special keyboard shortcuts are available to trigger the complete enumeration of all the components of a window, or to describe only the component having the current focus.

Providing form item descriptions to screen readers

Screen readers use special bindings to get the information that they need (name, full description, hierarchy, triggered actions, and so on) about each graphical component of the entire graphical user interface. It is up to the programmer to provide these bindings to the screen reader, but most of the work is already done by the front-end.

Programmers can provide two things for each widget to provide speech information to screen readers:

  • an accessible name, using the TEXT form attribute if available, otherwise with the COMMENT form attribute.
  • an accessible description, with the COMMENT form attribute.

This can be tedious, but it absolutely must be done carefully, keeping in mind that the text will be spoken. As such, customer's name is preferable to cust_name_str.

Spaces and punctuation are allowed.

Most of the form items are supported: All kind of form field, static labels, static images, and action-based items (such as buttons); some containers (GROUP and FOLDER) work out of the box as soon as their TEXT attributes are set.


In an action defaults file (mydefaults.4ad)

  <ActionDefault name="new" text="New..." image="new.svg" 
     comment="Create a new database" 
   acceleratorName="Control-N" />
  <ActionDefault name="open" text="Open..." image="open.svg"
     comment="Open an existing database" 
   acceleratorName="Control-O" />
  <ActionDefault name="save" text="Save" image="save.svg" 
     comment="Save the current database" 
   acceleratorName="Control-S" />

In field definitions on a form specification file (myform.per)

  EDIT login_name = formonly.login_name, NOT NULL,
    COMMENT="Login name of the current user";
  EDIT password = formonly.password, NOT NULL, INVISIBLE, VERIFY,
    COMMENT="Password of the current user";
  EDIT first_name = formonly.first_name, NOT NULL, 
    COMMENT="First name of the current user";
  EDIT last_name = formonly.last_name, NOT NULL, 
    COMMENT="Last name of the current user";
  DATEEDIT birthdate = formonly.birthdate, FORMAT="mm/dd/yyyy",
    COMMENT="Date of birth of the current user";
  EDIT email =, 
    COMMENT="E-mail of the current user";

In this form specification file, the COMMENT attribute is used for both the accessible name and the accessible description.