Java ATK Wrapper
Contents
About
Java ATK Wrapper is a implementation of ATK by using JNI technic. It converts Java Swing events into events which ATK can understand and then sends these events to ATK-Bridge. Order of the java stack down to ATK is Java Application > JRE JAAPI > JAW > ATK and JAW consists of two major parts:
The Java library that listens to Swing events, and adapting JAAPI to fit the interfaces of ATK
The C library that converts Swing events into GSignals and talks to ATK-Bridge.
Getting Started
Download and Install
You need to first install the dependencies: autoconf-archive, libatk1.0-dev, libatspi2.0-dev, and a java SDK.
The java-atk-wrapper source code is hosted by GNOME
git clone git://git.gnome.org/java-atk-wrapper
Then enter the install root directory using the cd command and run the autogen.sh script to install:
cd java-atk-wrapper ./autogen.sh --prefix=/opt/gnome && make && make install
You may wish to set a prefix to avoid permission errors while building (e.g. ./autogen.sh --prefix=/opt/gnome && make && make install)
As the compiler is set to fail on warnings by default. If the compilation fails try compiling with:
cd java-atk-wrapper ./autogen.sh --enable-compile-warnings=no && make && make install
Run a java program with the wrapper
To run with a java application (e.g. SwingSet3)
java -jar -Dassistive_technologies=org.GNOME.Accessibility.AtkWrapper SwingSet3.jar
One can also enable it in /etc/java-11-openjdk/accessibility.properties by uncommenting the following line:
assistive_technologies=org.GNOME.Accessibility.AtkWrapper
Testing
SwingSet2 is traditionally used to test java accessibility. However, it is a little out of date with deprecated functions, unchecked operations and accessible information which is not always complete. Work is being done on a SwingSet fork to ensure that testing is more comprehensive and up to date. To get hold of that version of SwingSet, type the following into the terminal from an appropriate working directory:
git clone https://github.com/thisMagpie/SwingSet3.git
Compile the java classes:
cd SwingSet3; javac *.java
Build SwingSet3.jar with:
jar cvmf META-INF/MANIFEST.MF SwingSet3.jar *.class resources
To get debugging information, add the -verbose:jni flag when running SwingSet with the wrapper:
java -jar -Dassistive_technologies=org.GNOME.Accessibility.AtkWrapper -verbose:jni SwingSet3.jar
The wrapper can be tested using some example pyatspi python scripts or with Accerciser, the accessibility testing tool for GNOME.
Making changes
After making any changes to the wrapper, it's very important to make sure that the build and install are clean before testing or the new change will not be updated when the wrapper is reinstalled.
To remove the system installed files like java-atk-wrapper.jar, accessibility.properties and the libatk-wrapper.* files run:
make uninstall
To remove the files generated in the build directory by ./configure use
make clean
To clean gitignored files but leave any untracked files which you may be working on run:
git clean -fdX
Debugging
Firstly, run a program like SwingSet2 then to check SwingSet2's PID, run the following command:
ps -ef | grep SwingSet2
This reveals a number called the PID which is associated to the running SwingSet2 application. The application can be attached to a gdb session using its PID, as follows:
gdb attach $PID
A bunch of debugging symbols get read until a gdb prompt appears. At the prompt we can tell gdb to stop and create a breakpoint at the first sign of trouble:
(gdb) b g_log
Before we can start properly debugging, we need the application to continue on as normal. The command for that is cont:
(gdb) cont Continuing.
Now we can return to the running SwingSet2 application to test some functionality until we see a problem and the (gdb) prompt appears to indicate that a breakpoint was created. At the prompt we can get a trace to see what the problem is:
(gdb) bt
Bugs
All bugs must be filed against Java ATK Wrapper in gitlab and patches must be submitted as merge requests for review.
Community
Please direct user support questions to the [https://discourse.gnome.org/tag/a11y|accessibility section]] and technical questions to the platform section in the GNOME support forum.
This module is maintained by Samuel Thibault.