The Linux Screen Reader is extensible with scripts called Perks that create, supplement, or redefine the user experience. Perks may be written to provide an LSR interface across all applications, for one particular application, or even for on particular type of interaction. For instance,

  • The BasicSpeechPerk packaged with LSR provides standard screen reader speech feedback all applications.

  • The MetacityPerk supplements the basic Perks by making the change desktop or change application panels accessible when they appear.

  • The GaimPerk provides usability improvements for the gaim chat client including reporting of user typing status, incoming messages, review of the message history, buddy list events, etc.

  • The DefaultDialogPerk manages the settings and Perk chooser dialogs, and updates the user's configuration when changes occur.

The LSR core supports Perk development in a number of ways.

  1. It defines an API that may be used to query and control accessible objects on the desktop without deep knowledge about platform accessibility. For example, a Perk developer does not have to worry about how toolkits (gtk, XUL, etc.) vary in their implementations of accessible widgets and events.
  2. It offers convenience methods for getting input and producing output on arbitrary devices, managing other Perks, showing custom dialogs, generating configuration dialogs, and performing many other useful actions.
  3. It provides a central system for dynamically registering, loading, and reloading Perks (and other extensions) at startup and at runtime. The user, Perks, and even external programs may use this registrar to define which Perks should constitute the user interface.
  4. It exposes an interface for settings configuration and persistence which alleviates the need for a Perk writer to create custom GUI dialogs or save data directly to disk.

Writing Perks

The following resources are available for Perk writers.

  • The Gaim Perk tutorial gives hands-on, step-by-step instructions about our experience writing a script for the gaim chat client. The tutorial covers the topics of registering handlers for foreground and background accessibility events, locating widgets of interest, moving focus programmatically, and overriding the default output. It is meant to serve as a concrete example of the more general knowledge captured by the Perk writer's guide. The tutorial document will evolve over time to reflect new features of LSR.

  • The Perk writer's guide (planned) gives general guidance for would-be script developers.
  • The LSR epydoc is generated from the Python docstrings in the LSR source code. The Task.Tools section of the documentation describes the API methods available to Perk writers. The epydoc s guaranteed to match the source before each major relase of LSR.

  • (Optional) The UNCSET team's a retrospective essay about writing Perks for LSR talks about the experience of working in the LSR project.

  • (Optional) The UNCSET team's Perk design document states how their Perks work and how they fit into the LSR architecture.

  • (Optional) The code for the Perks packaged with the LSR core are well-documented. Browsing their source may serve as a useful learning exercise.
  • (Optional) The LSR workbook gives an overview of the architecture of the LSR system. It describes fundamental LSR concepts and components, and links to parts of the generated source code documentation as a way of connecting design to implementation. The workbook is updated every few releases and may not reflect the current architecture of LSR.

How to contribute

  1. Check the project ideas page. Let us know if you want to implement any of them by emailing the LSR mailing list at .

  2. Write a Perk that does something useful for you. Perks don't have to be about accessibility and screen reading. Be creative and invent some new use for the LSR core (e.g. audible announcements of important syslog events for admins).

  3. Submit your Perk to the extensions repository. Attach it to that wiki page, create a description, and add a link to it.

  4. Lobby for your truly awesome Perk to be included with the LSR core. Tell us why everyone could benefit from your work by posting to .

Keyboard key assignments

A few of the key name constants such as AEK_BACK_SLASH may have different legends on the keys depending on keyboard layout. For example AEK_BACK_SLASH is actually the #~ key on a UK keyboard. The names defined in are actually X key codes which are related to physical keys, not what's printed on them (key sym). Thus the AEK constants define physical key locations (assuming the user has not reconfigured the X key map which is unlikely).

xev is a useful command to see what key code is generated for a key. xmodmap -pk prints a table of all codes and syms so is useful to find what key sym is assigned to a code on a particular keyboard.

Attic/LSR/ScriptDevelopers (last edited 2013-11-21 22:56:08 by WilliamJonMcCann)