File name: joptionp.htm

These discussion notes refer to the source file, Dial.java, which should be available from the Trace Center web site under the Java Accessibility Project and Java Application Accessibility Examples at Trace:

http://trace.wisc.edu/world/java/java.htm

What I attempted to do in this example, was to create a dialog box using three different approaches. The first approach was to use the JOptionPane.showInputDialog(...) method. The second approach was to use the JOptionPane call directly as described in the SUN API notes (e.g., JOptionPane pane = new JOptionPane(...)). The third and final approach was to create a dialog box from scratch, using only JDialog. After each dialog box was created, I then attempted to compare and contrast each approach by looking at the available accessibility information using the Accessibility Utility tool called "Explorer" (note: I use a modified version of Explorer, called ExplorerPlus which has been enhanced with "some" speech output capability)

When this java application (e.g., Dial.java) is run, it creates a top level window with a menu that has four choices, with each menu item choice selecting a different dialog box creation approach as noted above. While there are four menu choices, this example and these notes are really only concerned with the following three dialog box menu item choices:

JOptionPane Example #1 - approach #1
JOptionPane Example #2 - approach #2
JDialog Example - approach #3

(The fourth menu item, or style of dialog box, named "Large Text Example" is not discussed here.)

1. Notes from first approach using JOptionPane.showInputDialog(...):

From the SUN API Notes:
" ......... JOptionPane makes it easy to pop up a standard dialog box that prompts users for a value or informs them of something. While the class may appear complex because of the large number of methods, almost all uses of this class are one-line calls to one of the static showXxxDialog methods shown below:

showConfirmDialog Asks a confirming question, like yes/no/cancel.
showInputDialog Prompt for some input.
etc. etc. etc. ........."

Our concern is, that since these one-line or "convenience" methods exist, developers will use them to create dialog boxes, which unfortunately are not very friendly to the Accessibility API. Also, the dialog box created with JOptionPane.showInputDialog(...) seems to have other "access" issues, like keyboard navigation problems:

- Focus inside of JTextField

a. ENTER/RETURN key works by default on JTextField but the ESCAPE key is ignored

- Focus outside of JTextField

a. if a button has focus, you can select it with ENTER/RETURN or SPACEBAR
b. if either button has focus, the ESCAPE key is ignored

- TAB and Shift+TAB work for Focus navigation

- missing "global" action from ESCAPE key like standard Windows Dialog Box

Using approach #1 does manage:

a. layout of the components in the Dialog Box (when resized also)
b. screen location of the Dialog Box upon creation
c. manages the ENTER/RETURN key by default (not sure if OK button is selected, however)

Using approach #1

a. doesn't allow much *if any* added information via the Accessibility API

Some sample code is shown below, for a complete source code listing, please reference the source file.

String result = JOptionPane.showInputDialog(Dial.this, "Please enter your name: ");

2. Notes from second approach using JOptionPane API directly:

For the second approach, I was able to attach the JLabel to the JTextField by creating an "Object[]" array for the first parameter in the JOptionPane constructor call, but unfortunately I couldn't figure out how to place them in a JPanel, making it difficult to find the Accessible Parent. Again, this may present a problem for the screen reader assistive technology. I was also unable to add a mnemonic to the JLabel, which for a keyboard only user, might be an important means to provide efficient access to the various areas of the dialog box. (Note: There may be a way to do this, this was just my first attempt at using the API directly.)

Also, the dialog box created with JOptionPane(...) API directly seems to have other "access" issues, like keyboard navigation problems:

- Focus inside the JTextField

a. JTextField ignores ENTER/RETURN and ESCAPE keys without any added listeners

- Focus outside of JTextField

a. if a button has focus, you can select it with ENTER/RETURN or SPACEBAR
b. if either button has focus, the ESCAPE key is ignored

- focus "defaults" (e.g., starts) on the OK Button, rather than the JTextField as in example #1 above (again probably because I created/used the Object[])

- TAB and Shift+TAB work for Focus navigation

Using approach #2 does manage:

a. layout of the components in the Dialog Box (except those in the Object[])
b. screen location of the Dialog Box upon creation
c. no longer manages the ENTER /RETURN key in the JTextField (since I created the JTextField)

Using approach #2 allows:

a. for "some" Accessibility API information to be added
b. more flexibility in text "input" string (for some reason this doesn't always display properly), dialog box title, etc.

Some sample code is shown below, for a complete source code listing, please reference the source file.

JLabel templab = new JLabel("My Own Text Label Here : ");
JTextField temptxt = new JTextField(10);
templab.setLabelFor(temptxt);
Object[] panel = {templab, temptxt};

JOptionPane pane = new JOptionPane(panel, JOptionPane.QUESTION_MESSAGE, JOptionPane.OK_CANCEL_OPTION );

JDialog jdogtest = pane.createDialog(Dial.this, "My Own Input Title Here ");
jdogtest.show();

3. Notes from the third approach using JDialog ONLY:

Creating a dialog box from scratch was a time consuming and tedious task, which would probably be much easier with someone more knowledgeable with Java and by using a visual editor. However, once the dialog box code is written, it could easily be reused as a template for other dialog boxes. In addition to all the code necessary for component layout, I had to add key listeners for the various components. The one key listener which I was unable to figure out, was the ability to have the "OK" button default, which should be the ENTER/RETURN key, be handled properly. If the JTextField has focus, I was unable to "get" the ENTER/RETURN key to select "OK" as it should by default on a "Windows" dialog box. The ESCAPE key did however, map properly to the "CANCEL" button via the registered key listener, no matter which component has focus.

Using JDialog allows us to provide all kinds of accessibility and usability to the dialog box. We can attach the JLabel to the JTextField, set a mnemonic for the JLabel, add Accessible Descriptions and Names to various components, as well as tooltips. We can also *correct* the default key actions.

The dialog box created with JDialog, once all the following "listeners" were added:

- added KeyListeners to the TextField
- registered keyboard action listener on the JRootPane

behaves like a standard Windows Dialog Box as follows:

- Focus inside the JTextField

a. ESCAPE key works from within the JTextField
b. ENTER/RETURN key doesn't work from within the JTextField

- Focus outside of JTextField

a. if a button has focus, you can select it with ENTER/RETURN or SPACEBAR
b. if OK button has focus, ESCAPE key selects Cancel
c. if Cancel button has focus, ENTER/RETURN key selects OK

- TAB and Shift+TAB work for Focus navigation, probably in order of components as they are added to the JRootPanel ?

Using JDialog approach #3 doesn't manage:

a. layout of the components in the Dialog Box (THIS IS ALOT OF CODE)
b. screen location of the Dialog Box upon creation (easy to do)
c. no longer manages any KEYS in the Dialog Box (requires alot more code, but once you learn it, makes your dialog box easier to customize)

Using JDialog approach #3 allows:

a. maximum use of Accessibility API Information
b. you can use your own input sting, title, layout, etc...

Some sample code is shown below, for a complete source code listing, please reference the source file.

JPanel holdlabel = new JPanel();
JLabel label3 = new JLabel("Please enter your name: ");
label3.setDisplayedMnemonic('P');

JTextField jtxt3 = new JTextField();
label3.setLabelFor(jtxt3);
Icon dukeIcon = new ImageIcon("dukeWave.gif");
JLabel label4 = new JLabel(dukeIcon);
label4.setLabelFor(jtxt3);

label4.getAccessibleContext().setAccessibleDescription ("Duke waving and asking for your name");

label4.getAccessibleContext().setAccessibleName("Icon image of Duke waving ");

JPanel iconPanel = new JPanel();
iconPanel.add(label4);
holdlabel.add(label3);
holdlabel.add(jtxt3);

JPanel holdbut = new JPanel();
holdbut.setLayout(new FlowLayout());

JButton a3 = new JButton ("OK ");
a3.setToolTipText("Select OK after typing your name");

JButton b3 = new JButton ("Cancel");
b3.setToolTipText("Select Cancel to ignore this request");

holdbut.add(a3);
holdbut.add(b3);

Summary: