Java Desktop System Release 3 Accessibility Guide

Previous: Chapter 5 Using the Assistive Technologies

Appendix A System Administration

This appendix describes the tasks that a system administrator needs to perform to enable accessible login and to facilitate the use of the assistive technologies that are available in the Java Desktop System.

A.1 Configuring the Desktop for Accessible Login

The Java Desktop System includes an Accessible Login feature. The Accessible Login feature enables users to:

Log in to the desktop even if the user cannot easily use the screen, mouse, or keyboard in the usual way.
Launch assistive technologies at login time by associating a user action with an assistive technology application. The user can perform the user action from the standard keyboard, or from a keyboard, pointing device, or switch device that is attached to the USB or PS/2 mouse port. These user actions are called gestures.
Change the visual appearance of the login dialog before the user logs in, for example, to use a high contrast theme for better visibility.

A.1.1 To Enable Accessible Login

To enable the Accessible Login feature for the Java Desktop System, you must configure the desktop to use the GNOME Display Manager (GDM) as the login manager. GDM is the default login manager on Linux systems but not on Solaris systems, therefore the instructions to enable Accessible Login differ depending on the platform you are using.

A.1.1.1 To Enable and Configure GDM on Solaris Systems

To enable and configure GDM as the login manager on Solaris systems, perform the following steps:

Log in as the root user.
Open the file /etc/X11/gdm/gdm.conf.
Search the file for the following line:

#Greeter=/usr/bin/gdmgreeter

and replace the line with the following line:

Greeter=/usr/bin/gdmlogin

This step enables a standard login greeting rather than a graphical login greeting.
Search the file for the following line:

#AddGtkModules=false

and replace the line with the following:

AddGtkModules=true

This step enables the GtkModules.
Search the file for the following line:

#GtkModulesList=gail:atk-bridge:dwellmouselistener:keymouselistener

and delete the # from the start of the line so that the line reads:

GtkModulesList=gail:atk-bridge:dwellmouselistener:keymouselistener

Note –
The above lines must be displayed as single lines in the gdm.conf file without line breaks. The formatting of this guide may display the lines over two lines.

This step loads all of the GtkModules to enable assistive technologies such as On-Screen Keyboard and Screen Reader and Magnifier. You can edit the line above further to load only the GtkModules that you require to support the user base. For example:
- If you need to use the Screen Reader and Magnifier, include gail and atk-bridge.
- If you need to use a pointing device without buttons or switches, include gail, atk-bridge, anddwellmouselistener.
- If you use pointing devices with switches, alternative physical keyboards, or switch and button devices, include keymouselistener.
- On-Screen Keyboard can operate without gail and atk-bridge but with a reduced feature set.
For optimum accessibility, include gail and atk-bridge.
Save the /etc/X11/gdm/gdm.conf file.
Enter the following command to stop the dtlogin manager:

/usr/dt/bin/dtconfig -d
Enter the following commands to configure GDM as the login manager:

svccfg import /var/svc/manifest/application/gdm2-login.xml

svcadm enable application/gdm2-login

Note –
If you make any changes to the /etc/X11/gdm/gdm.conf file after you enable GDM, you can execute the following command to restart GDM and activate the changes:

gdm-restart
Edit the file /etc/passwd to append the following to the end of the gdm line:

:/etc/X11/gdm/home
Create the /etc/X11/gdm/home directory and assign ownership of the directory to the gdm user.
Restart your system.

A.1.1.2 To Configure GDM on Linux Systems

To configure GDM on Linux systems, perform the following steps:

Log in as the root user.
Open the file /etc/X11/gdm/gdm.conf.
Search the file for the following line:

#AddGtkModules=false

and replace the line with the following:

AddGtkModules=true

This step enables the GtkModules.
Search the file for the following line:

#GtkModulesList=gail:atk-bridge:dwellmouselistener:keymouselistener

and delete the # from the start of the line so that the line reads:

GtkModulesList=gail:atk-bridge:dwellmouselistener:keymouselistener

Note –
The above lines must be displayed as single lines in the gdm.conf file without line breaks. The formatting of this guide may display the lines over two lines.

This step loads all of the GtkModules to enable assistive technologies such as On-Screen Keyboard and Screen Reader and Magnifier. You can edit the line above further to load only the GtkModules that you require to support the user base. For example:
- If you need to use the Screen Reader and Magnifier, include gail and atk-bridge.
- If you need to use a pointing device without buttons or switches, include gail, atk-bridge, and dwellmouselistener.
- If you use pointing devices with switches, alternative physical keyboards, or switch and button devices, include keymouselistener.
- On-Screen Keyboard can operate without gail and atk-bridge but with a reduced feature set.
For optimum accessibility, include gail and atk-bridge.
Save the /etc/X11/gdm/gdm.conf file.

Note –
If you make any changes to the /etc/X11/gdm/gdm.conf file after you enable GDM, you can execute the following command to restart GDM and activate the changes:

gdm-restart
Edit the file /etc/group and append the following to the audio line:

,gdm

This step ensures that speech works with GDM.
Restart your system.

A.1.2 To Start Assistive Technologies at Login

If you load the keymouselistener and dwellmouselistener GtkModules in the GDM configuration file, you can assign user actions to launch specific assistive technologies at login time. These user actions are called gestures. The gesture associations are contained in the following GDM configuration files:

/etc/X11/gdm/modules/AccessKeyMouseEvents
/etc/X11/gdm/modules/AccessDwellMouseEvents

Note –

If you modify these files, you must restart your system before the changes take effect.

The following sections contain examples of the gestures that you can add to the GDM configuration files.

Note –

The gestures must be contained in a single line in the AccessKeyMouseEvents file without line breaks. The formatting of this guide might display the examples in the following sections over two lines.

A.1.2.1 To Start Screen Reader Using a Keyboard Shortcut

Edit the AccessKeyMouseEvents file to associate keyboard shortcuts with assistive technologies. For example, the following line enables you to press-and-hold Ctrl + S for one second to start Screen Reader and Magnifier in speech and Braille mode:

Solaris:

<Control>s 1 1000 10000 /usr/sfw/bin/srcore --login --disable-magnifier --enable-speech --enable-braille

Linux:

<Control>s 1 1000 10000 srcore --login --disable-magnifier --enable-speech --enable-braille

A.1.2.2 To Start Magnifier Using a Keyboard Shortcut

Edit the AccessKeyMouseEvents file to associate keyboard shortcuts with assistive technologies. For example, the following line enables you to press-and-hold Ctrl + M for one second to start Screen Reader and Magnifier in magnifier mode:

Solaris:

<Control>m 1 1000 10000 /usr/sfw/bin/srcore --login --enable-magnifier --disable-speech

Linux:

<Control>m 1 1000 10000 srcore --login --enable-magnifier --disable-speech

A.1.2.3 To Start On-Screen Keyboard Using a Switch or Button Gesture

Edit the AccessKeyMouseEvents file to associate switch, key, or button gestures with assistive technologies. Since the primary input device for many On-Screen Keyboard users is a switch or button, this is a good way to enable users to start On-Screen Keyboard at login time.

If there is a tendency for a user to start an application unintentionally, you can associate the gestures with multiple switch presses or minimum durations. For example, the following line starts On-Screen Keyboard in inverse scanning mode when the user presses the switch that is defined as Switch 2 three times within two seconds, for a minimum of 100 milliseconds for each press:

Solaris:

<Switch2>3 100 2000 /usr/sfw/bin/gok --login --accessmethod=inversescanning --scan-action=switch1 --select-action=switch2

Linux:

<Switch2>3 100 2000 gok --login --accessmethod=inversescanning --scan-action=switch1 --select-action=switch2

Users who use single switches may prefer to start On-Screen Keyboard in automatic scanning mode. The following line starts On-Screen Keyboard in automatic scanning mode when the user presses the switch on an alternative access device for more than four seconds:

Solaris:

<Switch>1 4000 5000 /usr/sfw/bin/gok --login --accessmethod=automaticscanning --scan-action=switch1 --select-action=switch1

Linux:

<Switch>1 4000 5000 gok --login --accessmethod=automaticscanning --scan-action=switch1 --select-action=switch1

For information about the On-Screen Keyboard operating modes, see the online Help for On-Screen Keyboard.

A.1.2.4 To Start On-Screen Keyboard Using a Motion-only Gesture

You can define gestures that involve only the motion of a pointing device such as a mouse, or an alternative pointing device, such as a head pointer or trackball. The syntax of the gesture does not change depending on whether you are using a mouse or an alternative pointing device. Edit the AccessKeyMouseEvents file to associate motion gestures with assistive technologies.

If the dwellmouselistener GtkModule is loaded, alternative pointing devices are temporarily latched to the core pointer. This means that if the user moves the alternative pointing device, the onscreen pointer moves.

For example, the following line starts On-Screen Keyboard in dwell mode when the user moves the onscreen pointer from inside the login dialog through the top edge, back into the dialog through the top edge, out of the dialog through the left edge, back into the dialog through the left edge, and similarly through the bottom and right edges of the dialog in a cross pattern:

Solaris:

TTLLBBRR O 10000 /usr/sfw/bin/gok --login --access-method=dwellselection --input-device=MOUSE[3]

Linux:

TTLLBBRR O 10000 gok --login --access-method=dwellselection --input-device=MOUSE[3]

Note that the --input-device parameter specified in the gesture must match the name of the extended user input device, such as a head pointer or trackball, as specified in /etc/X11/XF86Config.

A.1.3 Additional Requirements for Accessible Login

To enable the Accessible Login feature to use alternative pointing devices and switch devices such as sip-and-puff switches, wheelchair-mounted switches, or trackballs, you might need to modify your X server system configuration to recognize these devices. You can use most devices that emulate mouse buttons with the Accessible Login feature and On-Screen Keyboard, including USB single switches and mouse-like pointing devices.

In the Java Desktop System Release 3 for Solaris, the gdm user has a readable home directory. If this setting is removed on Solaris systems for security reasons, Screen Reader and Magnifier will not function properly during Accessible Login.

Note –

You should not configure an alternative input device to control the primary onscreen pointer. This might result in undesirable behavior or cause situations from which the user of the alternate input device cannot recover without using the primary keyboard or mouse. To prevent this problem, please remove any occurrences of the attributes SendCore or AlwaysCore from any of InputDevice lines in the X Server configuration file.

A.2 Configuring the Java Environment for Accessibility on Solaris Systems

To configure the Java environment on Solaris systems for accessibility, perform the following steps:

Log in as the root user to the base directory of the Java SDK installation.
Enter the following command:

cd jre/lib
Enter the following command:

ln -s /usr/share/jar/accessibility.properties
Enter the following command:

cd ext
Enter the following command:

ln -s /usr/share/jar/gnome-java-bridge.jar

A.3 Enabling XKB on Solaris Systems

If you are using the desktop for the Solaris operating system on a SPARC platform, you must enable XKB on your system before you can use the AccessX preference tool, Screen Reader and Magnifier, or On-Screen Keyboard.

Note –

XKB is not currently supported on Sun Ray^TM systems.

To enable XKB on a non-Sun Ray Solaris system, perform the following steps:

Log in as the root user.
Check if the path and file /etc/dt/config/Xservers exists on your system.
If the /etc/dt/config directory does not exist, enter the following command:
mkdir -p /etc/dt/config
If the Xservers file is not present, enter the following command:
cp /usr/dt/config/Xservers /etc/dt/config/Xservers
Open the Xservers file in a text editor and scroll to the end of the file.
Append the following to the command line at the end of the file:
+kb
Save and close the Xservers file.
Enter the following command at a command line:
pkill -HUP dtlogin
Open the /etc/X11/gdm/gdm.conf file in a text editor.
Scroll towards the end of the file until you see the line [server - standard].
Edit the command line in this section to append the following to the end of the line:

+accessx +kb
Save and close the gdm.conf file.
Log out of your session and log in again.
To verify if XKB is running, execute the following command:

xdpyinfo

then search for XKEYBOARD in the extensions list.

A.4 Enabling Full Screen Magnification

The following sections describe the methods to enable full screen magnification.

A.4.1 To Enable Full Screen Magnification Using Two Video Cards

To enable full screen magnification in Screen Reader and Magnifier using two physical video cards, perform the following steps:

Configure two video cards as :0.0 and :0.1.

Note –
It is not essential that both video cards have the same resolution and bit depth. However, if the resolutions and bit depths of both cards differ greatly, the apparent magnification factor may differ slightly from the nominal magnification factor.
Click Launch, then choose Applications -> Accessibility -> Screen Reader and Magnifier.
Click on Preferences in the Gnopernicus menu window.
Click on Magnifier to open the Magnifier Preferences dialog.
Click on the Add/Modify button to display the Zoomer Options dialog.
In the Display Screen section, type :0.0 in the Source text box.
In the Display Screen section, type :0.1 in the Target text box.
Set the Zoomer Placement values to be [0,0,1023,767].

Note –
These instructions assume a video resolution of 1024x768.
Click Apply and Close to close the Zoomer Options dialog.

The magnified view is displayed on the second display 0.1.

A.4.2 To Enable Full Screen Magnification Using One Video Card on Linux Systems

To enable full screen magnification on Linux systems using one physical video card and one virtual video card, perform the following steps:

Open the file /etc/X11/XF86Config.

Create a new section at the end of the file as follows:

Section "Device"
	Boardname "dummy"
	Driver "dummy"
	Identifier "dummy"
	VendorName "dummy"
EndSection

Copy the Monitor section and paste it at the end of the file.
In the new Monitor section, edit the Identifier line as follows:
```
Identifier "MonitorD"
```
Copy the Screen section and paste it at the end of the file.
In the new Screen section, edit the Device, Identifier, and Monitor lines as follows:
```
Device "dummy"
Identifier "ScreenD"
Monitor "MonitorD"
```
Edit the ServerLayout section to change the Screen line as follows:
```
Screen "Screen[0]" 0 0
```
Insert the following line in the ServerLayout section:
```
Screen "Screen[D]" RightOf "Screen[0]"
```
Save the /etc/X11/XF86Config file.
Restart the X Server.
Start the Screen Reader and Magnifier application.
Click on Startup Mode in the Gnopernicus menu window.
Select the Magnifier option in the Startup Mode dialog.
Click on Preferences in the Gnopernicus menu window.
Click on Magnifier to open the Magnifier Preferences dialog.
Click on the Add/Modify button to display the Zoomer Options dialog.
In the Display Screen section, type :0.1 in the Source text box.
In the Zoomer Placement section, set the value of the Left spin box to 0.
Click Apply.

The Screen Reader and Magnifier user interface is no longer visible.
Log out of your session.
Log in to a new session.
Enter the following command to start Screen Reader and Magnifier in full screen magnification mode:

gnopernicus -display :0.1
When you log out of your session, select the Save current setup option.

A.5 Enabling Braille

To enable your system to support Braille output, you must configure the access rights to the serial port to which the Braille device is connected. The following sections describe the steps that you need to perform depending on your operating system.

A.5.1 To Enable Braille on Solaris Systems

To configure the serial port to which the Braille device is connected on Solaris systems, perform the following steps:

Log in as the root user.
Enter the following command:

chmod 777 /dev/cua/a
Enter the following command:

chmod 777 /dev/cua/b
Change the permissions to 777 on the devices to which the symbolic links /dev/cua/a and /dev/cua/b point.

Note –

If your system uses /dev/cua/a for system log messages, Braille will not work on that serial port. Use /dev/cua/b instead.

A.5.2 To Enable Braille on Linux Systems

To configure the serial port to which the Braille device is connected on Linux systems, perform the following steps:

Log in as the root user.
Enter the following command:

chmod 777 /dev/ttyS0
Enter the following command:

chmod 777 /dev/ttyS1

A.6 Configuring Alternative Pointer Devices

The following sections describe how to configure your system to use a standard physical mouse and another pointer device such as a single switch device or head tracker device, and how to configure On-Screen Keyboard to use the second pointer device.

A.6.1 To Configure Alternative Pointer Devices on Solaris Systems

To configure an alternative pointer device on a Solaris system, perform the following steps:

Note –

This procedure does not work on all Solaris platforms.

Before you connect the alternative pointer device to your system, enter the following command to list the existing devices:

ls -l /dev/usb/hid*
Connect the alternative pointer device to your system.
Enter the following command again to list the new device:

ls -l /dev/usb/hid*
Open the file /usr/openwin/server/etc/OWconfig.
Add the following lines to the OWconfig file:
```
# Sun Mouse module
	class="XINPUT" name="IMOUSE2"
	dev="/dev/usb/hid2" strmod="usbms"
	ddxHandler="ddxSUNWmouse.so.1"
	ddxInitFunc="ddxSUNWmouseProc";
```
where:
- the name option starts with the string IMOUSE but is extended to form a unique string, such as IMOUSE2 or IMOUSE3, depending on the number of existing devices.
- the dev option specifies the device name that you identified in Step 3.

Remove the following lines from the OWconfig file:

# Null Mouse module
	class="XINPUT" name="NMOUSE"
	ddxHandler="ddxSUNWmouse.so.1"
	ddxInitFunc="ddxnullmouseProc";

Save the /usr/openwin/server/etc/OWconfig file.
Restart the X Server.

A.6.2 To Configure Alternative Pointer Devices on Linux Systems

To configure an alternative pointer device on a Linux system, perform the following steps:

Before you connect the alternative pointer device to your system, enter the following command to list the existing devices:

ls -l /dev/usb/hid*
Connect the alternative pointer device to your system.
Enter the following command again to list the new device:

ls -l /dev/usb/hid*
Open the file /etc/X11/XF86Config.
Edit the InputDevice section where the Driver value is set to mouse as follows:
- Change the Option Device line to the following:
```
Option       "Device" "/dev/input/mouse0"
```
- Comment out the Option Protocol line as follows:
```
#Option       "Protocol" "explorerps/2"
```
Note –
If you are not using USB connections for your primary mouse device and other pointer device, you do not need to carry out this step.

Create a new InputDevice section as follows:

Section "InputDevice"
     Driver       "mouse"
     Identifier   "Mouse[3]"
     Option       "Device" "/dev/input/mouse1"
     Option       "Name" "Autodetection"
     Option       "Vendor" "Sysp"
   EndSection

Note –

If you are not using USB connections for your primary mouse device and other pointer device, you do not need to carry out this step.

Edit the ServerLayout section as follows:
- Change the InputDevice "Mouse[1]" line to the following:
```
InputDevice  "Mouse[1]" "CorePointer"
```
- Create a new InputDevice line as follows:
```
InputDevice  "Mouse[3]"
```
- Remove any occurrences of the attributes SendCore or AlwaysCore from any of InputDevice lines.
Note –
Ensure that only the device that you are using as the primary mouse device has the "CorePointer" attribute and ensure that the alternate input devices do not have the SendCore or AlwaysCore attributes.
Save the /etc/X11/XF86Config file.
Restart the X Server.

A.6.3 To Configure On-Screen Keyboard to Use an Alternative Pointer Device

To configure the On-Screen Keyboard application to use an alternative pointer device, perform the following steps.

Start the On-Screen Keyboard application.
Click on GOK in the GOK - main window.
Click on Preferences to open the Preferences dialog.
Click on the Actions tab.
In the Event Source options, select the Other input device option. On-Screen Reader displays the name of the input device that you configured in the text box next to the Other input device option.
Click OK to close the GOK Preferences dialog.

A.7 Configuring Two USB Mouse Devices on Solaris x86 Systems

To configure two mouse devices on a Solaris x86 system, perform the following steps:

Before you connect the second mouse to your system, enter the following command to list the existing devices:

ls -l /dev/usb/hid*
Connect the second mouse to your system.
Enter the following command again to list the new device:

ls -l /dev/usb/hid*
Open the file /etc/X11/xorg.conf.

Edit the ServerLayout section as follows:

Section "ServerLayout"
         Identifier     "X.org Configured"
         Screen      0  "Screen0" 0 0
         InputDevice    "Mouse0" "CorePointer"
         InputDevice    "Mouse1"
         InputDevice    "Keyboard0" "CoreKeyboard"
EndSection

Edit the InputDevice section as follows:

Section "InputDevice"
         Identifier  "Mouse0"
         Driver      "mouse"
         Option      "Protocol" "VUID"
         Option      "Device" "/dev/mouse"
EndSection

Insert a second InputDevice section as follows:

Section "InputDevice"
         Identifier  "Mouse1"
         Driver      "mouse"
         Option      "Protocol" "VUID"
         Option      "StreamsModule" "usbms"
         Option      "Device" "/dev/usb/hidx"
EndSection

where:

/dev/usb/hidx is the device name that you identified in Step 3.

Save the /etc/X11/xorg.conf file.
Restart the X Server.

Previous: Chapter 5 Using the Assistive Technologies