3 This is the Early Access Release of the Gnome Accessibility Project's
4 Assistive Technology Service Provider Interface.
6 *** Welcome to the Gnome Accessibility Project! ***
8 If you have not already done so, please visit
10 http://developer.gnome.org/projects/gap
12 for background information on accessibility, the Gnome
13 Accessibility Project, mailing list info, and project status.
15 Contents of this package ==================================
17 The directories within this package are arranged as follows:
19 idl : this directory contains the interface definitions
20 (in Interface Definition Language) for the
21 accessibility support interfaces exposed by
22 the AT central registry, accessible applications,
24 Though IDL is often associated with CORBA, and this
25 implementation of the at-spi is CORBA-based, these
26 interfaces are not CORBA-specific, rather they define
27 the abstract "contract" between accessible application
28 and client assistive technology.
30 Assistive Technologies will not normally be concerned
31 with the underlying implementation details of the IDL.
33 libspi : this directory contains implementation-specific
34 code which connects the in-process ATK interfaces
35 (implemented by GTK+ and, potentially, by other
36 native-code UI toolkits) to the interprocess SPI.
37 It also contains implementation code used by the
38 central accessibility registry. These sources are
39 used to build libspi.so, a shared object library which
40 is used by accessibility clients and servers alike.
41 This interfaces exposed in this library are ordinarily
42 not directly used by AT, but are used by the C bindings,
43 thus AT must dynamically link to this library.
45 registryd : this directory contains code specific to the
46 central accessibility registry, and the registry
47 executable is built in this directory.
49 at-bridge : this directory contains code that bridges
50 the at-spi to the GTK+ toolkit, and which is
51 loaded at runtime by GTK+-based Gnome applications.
52 The 'bridge' automatically registers GTK+-2.0
53 applications with the accessibility registry,
54 and relays UI events from application to registry.
55 It is also responsible for servicing requests from
56 the registry to register handlers for specific event
59 cspi : this directory contains the C bindings for use by
60 ATs, and the code which adapts the implementation-specific
61 code to the C bindings API. The header file
62 "spi.h" contains the API declarations used by AT clients.
64 tests : this directory should be called 'examples', since
65 it contains not only test programs, but examples
66 of how to use the AT-SPI. The sample program
67 "simple-at.c" is currently the primary example of
68 how the C bindings API should be used.
70 docs : this directory contains documentation for the AT-SPI.
71 Documentation is currently limited to API documentation
72 for the C bindings API, and is built from sources
73 via the 'gtk-doc' system.
75 Building the documentation ============================
77 Pre-built versions of the HTML documentation are available at
78 http://developer.gnome.org/projects/gap/tech-docs/at-spi-docs/book1.html.
79 However the documentation in the docs directory is the most up-to-date.
80 Building the docs requires docbook and jade, see the 'gtk-doc'
81 package (from Gnome CVS) for more information.
83 Use of the AT-SPI ======================================
85 Accessible applications will register with this registry service
86 (via bonobo-activation) and adaptive/assistive technologies will
87 register with the service as well, to indicate their interest in
88 receiving UI events. ATs can also use the registry's services
89 programmatically to query accessible applications.
91 Running the test programs: ============================
93 At the moment the only clients and are two test at clients
94 ('at' and 'simple-at'). There is also a test app ('app) in
95 the 'tests' subdirectory.
97 If you have a working ORBit2/bonobo-activation installation you can
98 run the tests after adding the registryd directory to the
99 bonobo-activation directory list with bonobo-activation-sysconf,
100 or by installing Accessibility_Registry.server in your
101 bonobo-activation 'servers' directory.
103 You can then run './at' and './app' from the 'test' directory, to see
104 'app' register as an application, and 'at' as a listening client.
105 Bonobo should take care of the job of bootstrapping the registry daemon
106 ('registryd') for you. These test programs use the bonobo/CORBA
109 The third test program, "simple-at", is a better illustration of how
110 most actual AT should use the at-spi, via the C bindings library
111 (documented online at
112 http://developer.gnome.org/projects/gap/tech-docs/at-spi-docs/book1.html).
113 Though 'simple-at' will work with the test application 'app',
114 a better demonstration of the AT-SPI can be made after installing
115 libspi and libcspi (via 'make install'). If you set the GTK_MODULES
116 environment variable to "libgail:libat-bridge", any GTK+2.0
117 application run subsequently will register with the at-spi registry,
118 and 'simple-at' will register for and receive focus and
119 buttonpress events from those applications.
121 At the moment application and at deregistration are broken, so you are
122 advised to kill the registry daemon if you exit either 'at' or 'app'
123 instances, via the 'bonobo-slay' command. You may run as many instances
124 of each application or sample AT client as you like, concurrently -
125 you may find it useful to do so in separate terminal windows.
127 'at' connects to the registry as an event listener, then queries the
128 service for the number of virtual desktops (currently always 0 or 1),
129 and queries each desktop for the accessible applications it is running.
130 It then prints out the name of each such application (as reported by the
131 application's accessibility interfaces), and then waits to receive events.
133 'app' connects to the registry as an application, then dispatches an
134 event which the registry should relay to all registered listeners.
135 Thus instances of 'app' run after 'at' should cause the 'at' instances