NetBeans Accessibility FAQ
Authors: Dusan Pavlica
and Chris LeDantec
last updated:13/08/2002
Related Documents:
Section 508 Compliance
Q: How do we check for 508 Compliance?
A: For assessing the compliance of an application written in Java - run the Accessibility
Helper as a first pass to make sure that there are no unresolved accessibility issues. You
should also refer to the NetBeans Accessibility Guideline.
Q: Who checks to see if we are 508 compliant?
A: The Federal Acquisition Regulation does not specify how 508 requirements should be
wieghed against other requirements. For the time being Section 508 compliance is self
governed.
Q: What are the future plans for Section 508? Are there new versions in the works?
A: There are no major changes planned just "course corrections." Which will be
made through another NPRM [Notice of Proposed Rulemaking] and final rule.
Q: Will there be a certification process for 508 compliance?
A: In short, no but these are Procurement issues that the Federal Acquisitions folks must
wrestle with.
Q: We often have multiple keyboard ways to invoke a function (CTRL-P for Print, also
File=>Print). Is there any requirement for the "best" way, e.g., most direct?
A: Any keyboard access is sufficient for compliance.
Q: Won't there need to be a testing group, similar to what Sun has for
internationalization?
A: We expect people to be able to do their own assessments.
A11y Testing Tools
Q: Having trouble with the accessibility helper?
A: Version 0.2 is more stable with NetBeans than 0.4. Many people are using 0.2 until a
more stable version comes available.
Here are some tips for getting 0.4 to work (from Jeri Lockhart):
Setup:
1. Close the IDE's output window before starting and exit the IDE so that it remembers
to keep the output window closed the next start it starts.
2. Install Helper as per documentation. Verify install by running against a GUI class,
like Notepad in the Swing samples.
3. Add jaccesshelper.jar to the IDE's lib/ext folder.
4. In the test-set check the radio button for "executable or script" and a
corresponding command. ((I use D:\antbuild\f4j_all\f4jbuild\firststart\bin\runide.exe and
"Flag for Java > arguments" is -J- )
5. Execute the Test Set
I was able to get a report for all windows that were opened, including modal >
custom property editors. The limitation being that the output window is closed.
Q: The Accessibility Helper keeps crashing, what should I do?
A: Version 0.2 is more stable with NetBeans than 0.4. Many people are using 0.2 until a
more stable version comes available.
Q: I am using Accessibility Helper 02, but Tab traversal doesn't work or loops for a
long time. What can I do to fix this?
A: The automatic Tab traversal test can cause problems. You can try to focus another
window with the mouse and then return to the window being tested. To completely avoid this
problem exclude the Tab traversal test from the the Test Set. After excluding the Tab
traversal test please remember to manual test this aspect of the UI. It is recommended to
manual test Tab traversal in addition to any automated tests as the automated tests do not
report any problems with traversal order. For more information on Tab traversal order see
the JLF.
Q: Is it possible to test modal window by Accessibility Helper version 02?
A: To test a modal window start the test before opening the window. In some cases you can
use the keyboard to switch to the Accessibility Helper and start the test (Alt+t and
Alt+e) after opening the modal window.
Q: Why doesn't the Accessibility Helper report include one of the tested windows?
A: This is good news! If the Accessibility Helper doesn't find any problems with the
window then it will not be included in the final report.
Q: Is it possible to automate testing with the Accessibility Helper?
A: Currently, the Accessibility Helper does not support automated testing. This is a
desired feature but no formal plans for future version of the Accessibility Helper have
been put together.
Q: Where do I find the tool called Ferret?
A: This tool is included in Java
Accessibility Utilities 1.3. We use Ferret for quick recognition of Accessibility
Names, Accessibility Descriptions, and setLabelFor while fixing accessibility bugs
obtained from Accessibility Helper. It is necessary to copy jaccess-examples.jar into
JDK_HOME/jre/lib/ext folder and modify accessibility.properties file in JDK_HOME/jre/lib
directory. A working accessibility.properties file, along with Windows .bat files is
included in the a11yprop.zip.
Unzip this file into the JDK_HOME/jre/lib directory and start the tool you want from the
corresponding .bat file.
Q: What are the testing tools currently being used on NetBeans?
A: We are using the Java
Accessibility Helper, Java Access
Bridge, and Java
Accessibility Utilities. All of these resources can be found on Sun's Accessibility download page.
NetBeans Specific Questions
Q: What do I need to implement to make a dialog accessible?
A: Use getAccessibleContext().getAccessibleName() and getAccessibleContext().getAccessibleDescription().
Example:
After initComponents() call initAccessibility()
like this:
initComponents ();
initAccessibility(); // After initComponents() initAccessibility() can be
called
.
.
private void initAccessibility() {
ResourceBundle bundle = java.util.ResourceBundle.getBundle("path for Bundle");
AccessibleContext context = anyComponent.getAccessibleContext();
context.setAccessibleName(bundle.getString("ACSN_stringOfName"));
context.setAccessibleDescription(bundle.getString("ACSD_stringOfDescription"));
context = myNextComponent.getAccessibleContext();
...
}
Q: Conventions for bundle properties.
A: Use the prefix ACS_ for Accessibility, ACSN_ for AccessibleName,and
ACSD_ for AccessibleDescription.
Q: Do I need to specify AccessibleDescription if the item has
a tooltip?
A: If a tool tip is not appropriate or if its contents are insufficient for
a user with a disability, the value of the AccessibleDescription
property should be set.
Q: How can I set AccessibleName and AccessibleDescription in the FormEditor?
A: At this time there is built in mechanism to set the AccessibleName and
AccessibleDescription in the Form Editor. These items are available in the
property sheet for the form or component.
Q: Should ALL buttons have tooltips associated with them so that the accessible
description will be set to the tooltip? Or, OK and Cancel buttons should have accessible
descriptions, and all other buttons have tooltips? ?
A: Buttons that are self-evident (OK, Cancel, Add, Remove) don't need to set AccessibleDescription
or tooltips. Setting AccessibleDescription for buttons is considered
relatively low priority. If a tooltip would be helpful for all users, then one should be
added. Setting the AccessibleDescription in lieu of a tooltip may be
desirable in some cases. For instance, if the meaning of a button is obvious given visual
context, no tooltip may be needed. However, the addition of AccessibleDescription
may be helpful for blind users who do not have the visual context.
Q: Must we specify mnemonics for property sheet tabs?
A: Not possible. JDK 1.3 does not allow it. JDK 1.4 does, however.
Q: What buttons require mnemonics?
A: All command button require mnemonics. The exception is the default button
which is mapped to Enter/Return and the Cancel button which is mapped to Escape.
Neither of these buttons require keyboard focus to operate, however the Cancel
button behavior is not built into the JFC and needs to be implemented. Please
see the Java Look and Feel Guidelines for more information on mnemonics,
keyboard
activation, and command
buttons.
Q: Do items in the context menu require mnemoncis?
A: No they do not and please do not assign mnemonics to context menus. We discourage
using mnemonics in the context menus because there is a swing problem that does
not shift focus between items with the same mnemonic in a menu.The context menu
is generated dynamically in NetBeans so there is no way to guarantee that all
items will have unique mnemonics. Keyboard access via Shift+F10 (to open) and
the arrow keys is sufficient for making the context menus accessible.
Q: Can I use a Bundle string in the Form Editor to set the mnemonic for
a JLabel?
A: Yes, the property editor for the mnemonic property contains this feature.
Q: Do window/dialog titles require setting the AccessibleDescription?
(must be fixed in the NetBeans core)
A: Yes, and this is considered a high priority problem and should be fixed. The
developer needs to add the code: dialog.getAccessibleContext().setAccessibleDescription(
"description of the window");
The string should be window-specific help. If the dialog is very simple, the
description can be as simple as "This dialog allows you to select a font."
If it's a complex dialog, the description should give more details, such as
"This dialog allows you to choose a list of directories. You can enter
directory names one at a time, or you can use the locate option to perform a
search for directories.
Q: I have a lot of text in one text area, and I only want part of it to
be used as an AccessibleDescription. How do I do this?
A: This will happen in very rare cases. Duplicate the text for the accessible
description in the bundle file, and use the ACSC_ prefix for that bundle. If
you do this, be sure that the remaining text is accessible to screen readers
-- be making it focusable or the accessible description for some other component.
Q: How do I set the AccessibleDescription for dialogs in NetBeans?
A: There are several ways to do this, below is a description of how the system
works using NotifyDescriptor, DialogDescriptor and WizardDescriptor.
java.lang.Object
|
+--org.openide.NotifyDescriptor
|
+--org.openide.DialogDescriptor
|
+--org.openide.WizardDescriptor
1. Using NotifyDescriptor:
a) NotifyDescriptor.Message:
Dialog AccessibleDescription will be composed from the message string and
message type of message.
b) NotifyDescriptor.InputLine:
Dialog accessibleDescription will be created from the parameters (text, optionType,
messageType)
c) NotifyDescriptor.Confirmation:
Dialog accessibleDescription will be created from the parameters (text, optionType,
messageType)
d) If the dialog contains a Component (and not a message), then follow recommendation
2.
2. DialogDescriptor:
DialogDescriptor is created with (Component innerPane, String title). The innerPane
AccessibleDescription is used for dialog accessibleDescription. You could set
the accessibleDescription of the dialog directly, but we recommend using the
description from the innerPane.
3. WizardDescriptor:
An array of innerPanes are passed to the WizardDescriptor. Each innerPane should
have accessibleDescription related to content of innerPane. The AccessibleDescription
for a Wizard Dialog is set automatically in the following manner: step number,
step title, step description. Step description is a string obtained from the
innerPane and delegated to WizardDescriptor. This string is set by the developer.
Use the step description as the AccessibleDescription of the innerPane. Any
other text describing the dialog's content should be concatenated with the step
description and set as the accessibleDescription for innerPane.
4. CustomPropertyEditor: Follow the same recommendation for DialogDescriptor;
the acccessibilityDescription for the property editor, which displays CustomPropertyEditor,
is taken from the CustomPropertyEditor accessibleDescription. If you use standard property editor
(String, File, DataObjet, ...) and want to provide own accessible desciption then set String value
"desciption" to property's FeatureDescriptor
(call FeatureDescriptor.setValue("description", "My description")).
String value obtained from FeatureDescriptor.getValue("description")
is used by property editors framework for setting accessible desciption of CustomPropertyEditor dialog.
Q: How do I set the AccessibleDescription for Workspaces and Frames in NetBeans?
A: Use "description" element in window system xml layout files. More info how to use winsys layout files find in
Workspace Layout document.
Appropriate DTDs with elements descriptions are at workspace-properties1_0.dtd
and mode-properties1_0.dtd.
Q: Do labels that are not associated with a specific control need a labelFor method
(i.e. to associate it with the panel)?
A: This can be ignored. An example is a label used as a title for a wizard panel -
"Set Target Location [1 of 4]"
Q: We have many of nonfocusable text areas. What is your suggestion about the best
way to implementing accessibility in these cases?
A: If you want an Accessibility Tool (AT) to read text in your dialog you must either put
that text in the focus cycle. An alternative it to add the text to the dialog description.
In the case of simple Information or Warning dialogs set the default button's AccessibleDescription
to the dialog text. For more detailed guideline on how to deal with this problem please
refer to Dealing with Unfocusable Components - By Design.
Q: I need to use a jTextArea to describe a group of components as recommended
in Dealing with Unfocusable Components - By Design.
Should the look and feel of this text be changed to indicate its function as
a label?
A: Yes. When using a jTextArea to label a group of components set the text area
to look like a label. You can set everything using the form editor with the
following result:
jTextArea.setWrapStyleWord(true);
jTextArea1.setLineWrap(true);
jTextArea.setEnabled(false);
jTextArea.setEditable(false);
jTextArea.setOpaque(false);
jTextArea.setFont(javax.swing.UIManager.getFont("Label.font")); //set this
manually in the Code Generation Tab -> Post-Init Code
jTextArea.setDisabledTextColor((java.awt.Color)javax.swing.UIManager.getDefaults().get("Label.foreground"));
jTextArea.setBackground((java.awt.Color)javax.swing.UIManager.getDefaults().get("Label.background"));
//alternately if done manually: jTextArea.setBackground(UIManager.getColor("Label.background"));
//alternately if done manually: jTextArea.setDisabledTextColor(UIManager.getColor("Label.foreground"));
Q: Can we continue to have actions that are only available from a node's context
menu?
A: Since Shift+F10 opens the context menu, and arrow keys navigate the context menu, it is
not required to put all actions on the main menus. Please note that there are some issues
with using Shirt+F10.
Q: Where can I find additional information about Key navigation, Tab order and other
UI related issues?
A: The NetBeans User Interface
Style Guidelines provides one quick reference for UI issues. For more depth or topics
not covered there please refer to the Java Look and Feel Guidelines.
Q: Is there a record of dialogs being worked on?
A: A list of dialog screen shots by module is kept on ui.netbeans.org. After fixing any
a11y problems please send the accessibility report and an updated screen shot to the nbui@netbeans.org mailing list so the list can be
updated.
Q: What should I do with the report generated by the Accessibility Helper?
A: Submit the original accessibility report to nb-accessibility@eng.sun.com when the bug
has been fixed.
- If there are Accessibility Helper errors use red text "FINE" to denote this
and use Ferret to double check the problem spot.
- If a bug is fixed write "FIXED"
- Put additional comments at the end of report (for example: TAB order - OK, mnemonics -
OK)
- If a bug reported by the Accessibility Helper is related to a bug in a different module
add the comment "RELATED TO modulename" or "modulename ISSUE".
Q: Is there a special way to submit accessibility bugs?
A: We have established the keyword A11Y in Issuezilla, please use this when
submitting new bugs to help us keep track of where the issues are.
Q: How do I work make sure accessibility mnemonics and internationalization
requirements play well together?
A: There is official statement from NetBeans team to use single bundle entry with ampersand-prefixed mnemonic.
It is the preferred and recommended way of setting mnemonics. The approach of 2-keys mnemonics
is considered to be obsolete and should be avoided.
Currently both styles can be found in the existing
NB codebase and the umbrella issue #86438
collects issues with 2-keys mnemonics code.
Adam Sotona has created the converter that helps developers to convert
2-keys mnemonics to single key (text containing ampersand before the character that should be used as mnemonic).
The converter homepage is http://wiki.netbeans.org/wiki/view/MnemonicConverter.
Here is the example with steps that should be done to convert 2-key mnemonics to the ampersand-prefixed mnemonic.
First of all let's assume that in resource bundle we have 2-keys mnemonics code like this:
CTL_RemoveSource=Remove Source(s)
CTL_RemoveSource_Mnem=R
It should be replaced by:
CTL_RemoveSource=&Remove Source(s)
And the proper change must be done in java code so that the original code like:
removeParamButton.setMnemonic(Util.getChar("CTL_RemoveSource_Mnem"));
removeParamButton.setText(bundle.getString("CTL_RemoveSource"));
should be replaced by:
org.openide.awt.Mnemonics.setLocalizedText(removeParamButton, bundle.getString("CTL_RemoveSource")); // NOI18N
For additional issues or comments please contact
Dusan Pavlica and Chris
LeDantec
