README

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