Traduction du NVDA 2011.1 Developer Guide

Source : NVDA 2011.3 Developer Guide

Introduction

Ce guide fournit des informations pour les nouveaux développeurs qui souhaitent développer des composants pour NVDA. Notez que ce n'est qu'une introduction. Les développeurs devraient consulter la documentation du code pour avoir une information plus complète.

À propos de Python

NVDA et ses composants sont principalement écrits en langage de programmation Python. Le but de ce guide n'est pas de vous apprendre Python, bien que des exemples soient fournis tout au long de ce guide, qui vous aideront à vous familiariser avec la syntaxe de Python. La documentation et d'autres ressources liées au langage Python se trouvent sur le site http://www.python.org/

Translation

In order to support multiple languages/locales, NVDA must be translated and data specific to the locale must be provided.

Character Descriptions

Sometimes, it can be very difficult or even impossible to distinguish one character from another. For example, two characters might be pronounced the same way, even though they are actually different characters. To help users when this occurs, character descriptions can be provided which describe the character in a unique way.

Character descriptions can be provided for a locale in a file named characterDescriptions.dic in the directory for the locale. This is a UTF-8 encoded text file. Blank lines and lines beginning with a "#" character are ignored. All other lines should contain a character, followed by a tab, then one or more descriptions separated by tabs.

For example:

# This is a comment.
a	alpha
b	bravo

See the file locale\en\characterDescriptions.dic for a full example.

Symbol Pronunciation

It is often useful to hear punctuation and other symbols pronounced as words when reading text, particularly when moving by character. Unfortunately, the pronunciation of symbols is inconsistent between speech synthesisers and many synthesisers do not speak many symbols and/or do not allow control over what symbols are spoken. Therefore, NVDA allows information about symbol pronunciation to be provided.

This is done for a locale by providing a file named symbols.dic in the directory for the locale. This is a UTF-8 encoded text file. Blank lines and lines beginning with a "#" character are ignored. All locales implicitly inherit the symbol information for English, though any of this information can be overridden.

The file contains two sections.

Defining Complex Symbols

The first section is optional and defines regular expression patterns for complex symbols. Complex symbols are symbols which aren't simply a character or sequence of characters, but instead require a more complicated match. An example is the full stop (.) sentence ending in English. The "." is used for multiple purposes, so a more complicated check is required to determine whether this refers to the end of a sentence.

The complex symbols section begins with the line:

complexSymbols :

Subsequent lines contain a textual identifier used to identify the symbol, a tab and the regular expression pattern for that symbol. For example:

. sentence ending	(?<=[^\s.])\.(?=[\"')\s]|$)

Again, the English symbols are inherited by all other locales, so you need not include any complex symbols already defined for English.

Defining Symbol Information

The second section provides information about when and how to pronounce all symbols. It begins with the line:

symbols:

Subsequent lines should contain several fields separated by tabs. The only mandatory fields are the identifier and replacement. The default will be used for omitted fields. The fields are as follows:

   identifier: The identifier of the symbol. In most cases, this is just the character or characters of the symbol. However, it can also be the identifier of a complex symbol. Certain characters cannot be typed into the file, so the following special sequences can be used:
       \0: null
       \t: tab
       \n: line feed
       \r: carriage return
       \f: form feed
       \#: # character (needed because # at the start of a line denotes a comment) 
   replacement: The text which should be spoken for the symbol.
   level: The symbol level at which the symbol should be spoken. The symbol level is configured by the user and specifies the amount of symbols that should be spoken. This field should contain one of the levels "none", "some", "most", "all" or "char", or "-" to use the default. "char" means that the symbol should only be pronounced when moving by character. The default is to inherit the value or "all" if there is nothing to inherit.
   preserve: Whether the symbol itself should be preserved to facilitate correct pronunciation by the synthesiser. For example, symbols which cause pauses or inflection (such as the comma in English) should be preserved. This field should be one of the following:
       never: Never preserve the symbol.
       always: Always preserve the symbol.
       norep: Only preserve the symbol if it is not being replaced; i.e. the user has set symbol level lower than the level of this symbol.
       -: Use the default. 
   The default is to inherit the value or "never" if there is nothing to inherit. 

Finally, a display name for the symbol can be provided in a comment after a tab at the end of the line. This will be shown to users when editing the symbol information and is especially useful for translators to define translated names for English complex symbols.

Here are some examples:

(	left paren	most

This means that the "(" character should be spoken as "left paren" only when the symbol level is set to most or higher; i.e. most or all.

,	comma	all	always

This means that the "," character should be spoken as "comma" when the symbol level is set to all and that the character itself should always be preserved so that the synthesiser will pause appropriately.

. sentence ending	point	# . fin de phrase

This line appears in the French symbols.dic file. It means that the ". sentence ending" complex symbol should be spoken as "point". Level and preserve are not specified, so they will be taken from English. A display name is provided so that French users will know what the symbol represents.

Please see the file locale\en\symbols.dic for the English definitions which are inherited for all locales. This is also a good full example.

Greffons logiciels

Aperçu

Les greffons vous permettent de personnaliser la façon dont se comporte NVDA en général ou dans une application particulière. Ils sont capables de :

• Répondre à des évènements particuliers tels que la prise de focus ou les changements dans les propriétés des objets, par exemple quand un contrôle change de nom.
• Mettre en œuvre les commandes qui sont liées à des touches spécifiques ou d'autres entrées.
• Personnaliser le comportement ou mettre en œuvre des fonctionnalités supplémentaires pour des contrôles spécifiques.
• Personnaliser ou ajouter un nouveau support pour le contenu textuel et les documents complexes.

=== Types de greffons ===

Il existe deux types de greffons :

• Les Modules App : code spécifique à une application particulière,

le module App reçoit tous les événements d'une application précise, même si ce n'est pas l'application courante. Lorsque l'application est active, toutes les commandes que le module App a associé aux touches ou à une autre entrée peuvent être exécutées par l'utilisateur.

• Plugins Globaux : le code Global de NVDA, C'est à dire utilisé dans toutes les applications.

Les greffons Globaux contiennent tous les événements liés à tous les contrôles du système d'exploitation. Toutes les commandes associées à un Plugin global peuvent être exécutées par l'utilisateur, où qu'elles soient dans le système d'exploitation, indépendamment de l'application.

Si vous souhaitez améliorer l'accès de NVDA à une application donnée, il est plus probable que vous vouliez écrire un module App. En revanche, si vous souhaitez ajouter des fonctionnalités à NVDA en général (par exemple un script donnant la puissance instantanée du réseau sans fil quelle que soit l'application), un greffon global est ce qu'il vous faut.

Modules et Plugins App Globaux se présentent de la même manière. Ce sont des fichiers source Python (avec une extension .Py), ils définissent tous deux une classe spéciale contenant tous les événements, les scripts et les bindings, et ils peuvent définir des classes personnalisées pour les accès, le contenu du texte et les documents complexes. Cependant, ils diffèrent à certains égards.

Les quelques sections suivantes traitent séparément les modules App et les greffons globaux. Après cela, la discussion est à nouveau plus générale.

Les bases d'un module App

Les fichiers des modules App ont l'extension .Py, et portent le même nom que l'exécutable principal de l'application pour laquelle vous souhaitez les utiliser. Par exemple, un module d'application pour Notepad seraient appelés notepad.py, puisque l'exécutable principal de Notepad est appelé notepad.exe.

Les fichiers du module App doivent être placés dans le sous-répertoire appModules du répertoire configuration de NVDA de l'utilisateur. Pour plus d'informations sur la localisation du répertoire de configuration de l'utilisateur, consultez, s'il-vous-plaît, le guide utilisateur de NVDA.

Les Modules App doivent définir une classe appelée AppModule, qui hérite de appModuleHandler.AppModule. Cette classe peut alors définir des événements et des méthodes pour les scripts, des gesture bindings et d'autres codes. Tout cela sera abordé en profondeur plus tard.

NVDA charge un module App pour une application dès qu'il détecte que l'application est exécutée. Le module App est déchargé une fois l'application fermée ou lorsqu'on quitte NVDA.

Exemple 1: Un module App qui génère un Bip lors des événements de changement du Focus

L'exemple suivant de module App, fait biper NVDA chaque fois que le focus change dans l'application Notepad. Cet exemple vous montre le schéma de base d'un module app.

Dans un nouveau fichier texte appelé notepad.py, qui doit être sauvegardé dans le répertoire AppModules, copiez et collez le code entre les marqueurs de début et de fin, sans les inclure. Faites très attention de garder toutes les tabulations et les espaces intactes.

Une fois enregistré à l'emplacement correct, vous pouvez redémarrer NVDA ou choisir de recharger les greffons. Vous trouverez ceci dans le sous-menu Outils du menu NVDA.

Pour finir, ouvrez le bloc-notes et placer le focus dans l'application. Par exemple, déplacer-vous le long de la barre de menu, ouvrez certaines boîtes de dialogue, etc. Vous devriez entendre des bips chaque fois que le focus change. Notez cependant que si vous vous déplacez en dehors de Notepad — par exemple, dans l'Explorateur Windows — vous ne devriez pas entendre de bips.

--- start ---
# Notepad App Module for NVDA
# Developer guide example 1

import appModuleHandler

class AppModule(appModuleHandler.AppModule):

	def event_gainFocus(self, obj, nextHandler):
		import tones
		tones.beep(550, 50)
		nextHandler()

--- end ---

Le fichier de ce Module App commence par deux lignes de commentaires, qui décrivent à quoi le fichier est destiné.

Il importe alors le module appModuleHandler, de sorte que le module App a alors accès à la classe AppModule base.

Ensuite, il définit une classe appelée AppModule, qui est héritée de appModuleHandler.AppModule.

À l'intérieur de cette classe, il définit un ou plusieurs événements, des scripts ou des gesture bindings. Dans cet exemple, il définit une méthode pour l’événement recevoir le focus (event_gainFocus), qui émet un bip court à chaque fois qu'il est exécuté. La mise en œuvre de cet événement n'est pas ce qui importe pour cet exemple ; la partie la plus importante est la classe elle-même. Les événements seront traités plus en détail ultérieurement.

De la même façon que pour d'autres exemples de ce guide, n'oubliez pas de supprimer le module Application créé lorsque vous avez terminé les essais ; puis redémarrez NVDA ou bien recharger les greffons, afin que la fonctionnalité d'origine soit restaurée.

Les bases d'un greffon global

Les fichiers de greffons globaux ont une extension .Py, et devraient avoir un nom court et unique identifiant ce qu'ils font.

Les fichiers de greffons globaux doivent être placés dans le sous-répertoire globalPlugins du répertoire configuration de NVDA de l'utilisateur. Pour plus d'informations sur la localisation du répertoire de configuration de l'utilisateur, consultez, s'il-vous-plaît, le guide utilisateur de NVDA.

Les greffons globaux doivent définir une classe appelée GlobalPlugin, qui hérite de globalPluginHandler.GlobalPlugin. Cette classe peut alors définir des événements et des méthodes de script, des gesture bindings et d'autres codes. Tout cela sera abordé plus précisément par la suite.

NVDA charge tous les greffons globaux au démarrage, et les décharge à la fermeture.

Exemple 2: un Plugin global qui Fourni un script annonçant la version de NVDA

L'exemple suivant de greffon global vous permet d'appuyer sur NVDA + Maj + V depuis n'importe où dans le système d'exploitation pour connaître la version de NVDA. Cet exemple est seulement là pour vous montrer la structure de base d'un greffon global.

Dans un nouveau fichier texte nommé example2.py, qui doit être sauvegardé dans le répertoire globalPlugins, copiez et collez le code entre les marqueurs de début et de fin, sans les inclure. Faites très attention de garder toutes les tabulations et les espaces intactes.

Une fois enregistré à l'emplacement correct, vous pouvez redémarrer NVDA ou choisir de recharger les greffons. Vous trouverez ceci dans le sous-menu Outils du menu NVDA.

Vous pouvez maintenant, de n'importe où, appuyer sur les touches NVDA + Maj + V pour entendre ou lire en braille la version de NVDA.

--- start ---
# Version announcement greffon for NVDA
# Developer guide example 2

import globalPluginHandler
import ui
import versionInfo

class GlobalPlugin(globalPluginHandler.GlobalPlugin):

	def script_announceNVDAVersion(self, gesture):
		ui.message(versionInfo.version)

	__gestures={
		"kb:NVDA+shift+v": "announceNVDAVersion",
	}

--- end ---

Le fichier de ce greffon global commence par deux lignes de commentaires, qui décrivent à quoi ce fichier doit servir.

Il importe alors le module globalPluginHandler, afin que le greffon global ait accès à la classe GlobalPlugin de base.

Il importe également quelques autres modules, à savoir UI et VERSIONINFO, dont un de ces greffons spécifiques est nécessaire pour effectuer l'ensemble des actions requises afin d'annoncer la version.

Puis il définit une classe appelée GlobalPlugin, qui est héritée de globalPluginHandler.GlobalPlugin.

x À l'intérieur de cette classe, il définit un ou plusieurs événements, des scripts ou des gesture bindings. Dans cet exemple, il définit une méthode de script qui effectue l'annonce de version, et lie NVDA + Maj + V à ce script. Toutefois, les détails du script et de son affectation importent peu dans cet exemple. La partie la plus importante est la classe elle-même.

De la même façon que pour d'autres exemples de ce guide, quand vous aurez terminé les essais n'oubliez pas de supprimer le greffon global que vous avez créé ; puis redémarrez NVDA ou bien recharger les greffons, afin que la fonctionnalité d'origine soit restaurée.

Objets NVDA

NVDA représente les contrôles et d'autres éléments d'interface graphique sous forme d'objets NVDA. Ces objets contiennent des propriétés NVDA standardisées, comme le nom, le rôle, la valeur, les états et la description, ce qui permet à d'autres parties de NVDA de demander ou d'afficher des informations à propos d'un contrôle d'une manière générale. Par exemple, le bouton OK d'une boîte de dialogue serait représenté par un objet NVDA avec un nom « OK » et un rôle de bouton. De même, une case à cocher avec une étiquette J'accepte aurait le nom « J'accepte », un rôle de case à cocher et si elle est cochée, un état coché.

Comme il existe de nombreux toolkits graphiques, de plateformes et API d'accessibilités, les objets NVDA font abstraction de ces différences dans un formulaire standard, utilisable par NVDA, indépendamment du tooltip ou de l'API avec lequel le contrôle est effectué. Par exemple, le bouton Ok, dont nous venons de discuter, pourrait être un widget dans une application Java, un objet MSAA, un objet ou un élément IAccessible2 UI Automation.

Les objets NVDA ont de nombreuses propriétés, parmi les plus utiles on a :

• name (nom) : l'étiquette du contrôle.
• rôle (rôle) : l'une des constantes ROLE_* du module controlTypes de NVDA.

Button, dialog, editableText, window et checkbox sont des exemples de rôles.

• states (états): une série de 0 ou plusieurs des constantes STATE_* à du module NVDA controlTypes.

Focusable, focused, selected, selectable, expanded, collapsed et checked sont quelques exemples d'états.

• value (valeur) : la valeur du contrôle ; par exemple le pourcentage d'une barre de défilement ou l'item sélectionné pour une liste déroulante.
• description (Description) : une phrase ou deux décrivant ce que le contrôle fait (en générale identique à son info-bulle).
• location (Emplacement): la position de l'objet en coordonnées écran (gauche, en haut, la largeur et la hauteur).
• parent (parent) : l'objet parent de cet objet.

Par exemple, le parent de l'objet élément de liste serait la liste qui le contient.

• next (suivant) : l'objet juste après celui-ci au même niveau d'un ordre logique.

Par exemple, l'objet le plus susceptible de suivre un objet item du menu NVDA est un autre item du même menu.

• previous (précédent) : comme next, mais dans l'ordre inverse.
• firstChild (premier enfant) : l'objet premier enfant direct de cet objet.

Par exemple, le premier enfant d'une liste serait le premier élément de la liste.

• lastChild (dernier enfant) : le dernier enfant direct de cet objet.
• children (enfants): une liste de tous les enfants directs de cet objet ; par exemple tous les items du menu dans un menu.

Il y a aussi quelques propriétés de navigation simplifiée tels que simpleParent, simpleNext, simpleFirstChild et simpleLastChild. Ce sont respectivement les mêmes propriétés de navigation que celles décrites ci-dessus, mais NVDA filtre les objets inutiles. Ces propriétés sont utilisées lorsque NVDA est en mode navigation simplifiée, ce qui est le mode par défaut. Ces propriétés simples peuvent être plus faciles à utiliser, mais les propriétés de navigation réelles reflètent mieux la structure sous-jacente du système d'exploitation.

Lors du développement de greffons, généralement, le toolkit ou l'API qui renvoie un objet NVDA importe peu, puisque le greffon va, la plupart du temps, n’accéder qu'aux propriétés standards, telles que le nom, le rôle et la valeur. Cependant, pour les greffons plus avancés, il est certainement possible de creuser davantage sur les objets NVDA pour trouver des informations sur les boîtes à outils ou API spécifiques si nécessaire.

Les greffons utilisent des objets NVDA pour trois raisons précises :

• La plupart des événements que les greffons reçoivent prennent en argument l'objet NVDA sur lequel l'événement s'est produit.

Par exemple, event_gainFocus prend l'objet NVDA qui représente le contrôle recevant le focus.

• Les scripts, les événements ou d'autres codes peuvent aller chercher des objets d'intérêt tels que les objets NVDA en focus, les objets de navigation courante de NVDA, ou peut-être l'objet NVDA du bureau.

Le code peut alors récupérer des informations de cet objet ou peut-être même d'un objet lié à celui-ci (par exemple, son parent, le premier enfant, etc.).

• Le greffon peut définir ses propres classes d'objets NVDA, elles seront utilisées pour contenir un contrôle spécifique afin de lui donner des fonctionnalités supplémentaires, muter ses propriétés, etc.

Tout comme les modules et greffons App globaux, les objets NVDA peuvent également définir des événements, des scripts et des gesture bindings.

Scripts et Gesture Bindings

Les Modules App, les Plugins globaux et les Objets NVDA peuvent définir des méthodes spéciales qui peuvent être liées à un raccourci spécifique, ainsi, une touche NVDA se réfère à ces méthodes de scripts.

Un script est une méthode standard d'instance de Python possédant un nom commençant par "script_", par exemple "script_sayDateTime".

Une méthode de script prend deux arguments :

• self (auto) : une référence au module App, au greffon global ou a une instance de l'objet NVDA du script qui a été appelé.
• gesture : un objet Input Gesture, qui représente l'entrée qui a déclenché le script à exécuter.

De même que la méthode de script, une certaine forme de gesture binding doit être définie, de sorte que NVDA sait quelle entrée doit exécuter le script.

Pour affecter la gesture à un script, un dictionnaire Python spécial "__gestures" peut être défini comme une variable de classe dans le module App, le greffon global ou l'objet NVDA. Ces dictionnaires doivent contenir des chaînes d'identification de gesture pointant vers le nom du script demandé, sans le préfixe

Il y a des manières plus avancées de faire des gestures binding dans un mode plus dynamique, même si le dictionnaire __gestures est le plus simple.

Une chaîne d'identification de gesture est une chaîne simple représentant un raccourci. Il se compose d'un code de deux lettres correspondant à la source d'entrée, une partie facultative entre parenthèses, deux points (:) et un ou plusieurs noms séparés par un signe plus (+) désignant des touches réelles ou valeurs d'entrée.

Quelques exemples de chaînes d'identification de gesture sont :

• "kb:NVDA+shift+v" ;
• "br(freedomScientific):leftWizWheelUp" ;
• "kb(laptop):NVDA+t".

Actuellement, les seules sources d'entrée de NVDA sont :

• kb: keyboard input (saisie au clavier) ;
• br: braille input (entrée braille).

Quand NVDA reçoit une entrée, il cherche les gestures bindings correspondantes dans un ordre précis. Une fois qu'une gesture binding est trouvée, le script est exécuté et aucune des bindings supplémentaires ne sont utilisées, Nore est gesture particulière transmise automatiquement au système d'exploitation. (nore is that particular gesture passed on automatically to the Operating System.)

L'ordre de recherche des gestures bindings est le suivant :

• les greffons globaux chargés ;
• les Module App de l'application active ;
• l'arborescence d'interception de l'objet NVDA sous le focus le cas échéant, par exemple un virtualBuffer ;
• l'objet NVDA sous le focus ;
• les commandes globales (intégrées dans les commandes comme quitter NVDA, les commandes d'objets de navigation, etc.).

Exemple 3: un Plugin global pour trouver la classe de fenêtre et le contrôle d'ID

Le greffon global ci-dessous, vous permet d'annoncer la classe de fenêtre du focus actuel en appuyant sur touche NVDA + flèche gauche et l'ID du contrôle sous le focus dans la fenêtre avec touche NVDA + flèche droite. Cet exemple vous montre comment définir un ou plusieurs scripts avec gesture bindings dans une classe comme un module App, un greffon global ou un objet NVDA.

Dans un nouveau fichier texte nommé example3.py, qui doit être sauvegardé dans le répertoire globalPlugins, copiez et collez le code entre les marqueurs de début et de fin, sans les inclure. Faites très attention de garder toutes les tabulations et les espaces intactes.

Une fois enregistré à l'emplacement correct, vous pouvez redémarrer NVDA ou choisir de recharger les greffons. Vous trouverez ceci dans le sous-menu Outils du menu NVDA.

--- start ---
#Window utility scripts for NVDA
#Developer guide example 3

import globalPluginHandler
import ui
import api

class GlobalPlugin(globalPluginHandler.GlobalPlugin):

	def script_announceWindowClassName(self, gesture):
		focusObj = api.getFocusObject()
		name = focusObj.name
		windowClassName = focusObj.windowClassName
		ui.message("class for %s window: %s" % (name, windowClassName))

	def script_announceWindowControlID(self, gesture):
		focusObj = api.getFocusObject()
		name = focusObj.name
		windowControlID = focusObj.windowControlID
		ui.message("Control ID for %s window: %d" % (name, windowControlID))

	__gestures = {
		"kb:NVDA+leftArrow": "announceWindowClassName",
		"kb:NVDA+rightArrow": "announceWindowControlID",
	}

--- end ---

Événements

Quand NVDA détecte des toolkits particuliers, l'API ou les événements du système d'exploitation, it abstracts these et appelle ses propres événements internes sur les greffons et les objets NVDA.

Bien que la plupart des événements soient liés à un objet NVDA spécifique (par exemple changement de nom, gain du focus, changement d'état, etc.), ces événements peuvent être traités à différents niveaux. Quand un événement est géré, il est empêché d'aller plus loin dans la chaîne. Toutefois, le code dans l'événement peut choisir de se propager davantage si nécessaire.

L'ordre des niveaux par lequel passe l'événement jusqu'à ce qu'une méthode d'événement soit trouvée est le suivant :

• les greffons globaux chargés ;
• les modules App associés à l'objet NVDA pour lesquels l'événement a été appelé ;
• l'arborescence d'interception (s'il existe) de l'objet NVDA pour lequel l'événement a été appelé ;
• l'objet NVDA lui-même.

Les événements sont des méthodes d'instance Python, possédant un nom commençant par "event_" suivi par le nom de l'événement (par exemple gainFocus).

Ces méthodes d'événement prennent des arguments légèrement différents selon le niveau auquel ils sont définis.

Si un événement d'un objet NVDA est défini pour lui-même, la méthode prend un seul argument obligatoire, le self argument : à savoir l'instance d'objet NVDA). Certains événements peuvent prendre des arguments supplémentaires, mais cela est assez rare.

Si un événement d'un objet NVDA est défini sur un greffon global, un module App ou l'arborescence d'interception, l'événement prend les arguments suivants :

• self (auto): l'instance du greffon global, du Module App ou de l'arborescence d'interception ;
• obj (objet): objet NVDA sur lequel l'événement a été appelé ;
• nextHandler: une fonction qui propagera l'événement dans la chaîne lorsqu’elle est appelée.

Certains événements communs aux objets NVDA sont :

• foreground (avant-plan): cet objet NVDA est passé en avant-plan, c'est à dire l'objet actif de plus haut niveau ;
• gainFocus (obtention du focus) ;
• loseFocus (perte du focus) ;
• nameChange (changement du nom) ;
• valueChange (changement de la valeur) ;
• stateChange (changement de l'état) ;
• caret (curseur): lorsque le curseur (point d'insertion) se déplace au sein de cet objet NVDA ;
• locationChange (changement de l'emplacement): changements physiques de l'emplacement à l'écran.

Il existe beaucoup d'autres événements, bien que ceux énumérés ci-dessus sont généralement les plus utiles.

Pour voir un exemple d'événement géré par un module App, référez-vous à l'exemple 1.

La variable SleepMode des modules App

Les modules App ont une propriété très utile appelée "sleepMode", qui, si elle est à "true", désactive presque complètement NVDA au sein de cette application. Le mode veille est très utile pour les applications auto-vocalisée qui possèdent leurs propres fonctionnalités de lecture d'écran, ou peut-être même certains jeux qui ont besoin d'utiliser pleinement le clavier.

Bien que le mode veille puisse être activé et désactivé par l'utilisateur avec la combinaison clavier NVDA + MAJ + S, un développeur peut choisir d'activé le mode veille par défaut pour une application donnée. Ceci est fait en fournissant un module App pour cette application, dans la classe AppModule sleepMode est simplement à "true".

Exemple 4 : Un module App mode veille

Vous pouvez copier-coller le code suivant dans un fichier texte, puis l'enregistrer dans le répertoire appModules en lui donnant le nom de l'application pour laquelle vous souhaitez activer le mode veille. Le fichier doit avoir l'extension .Py, comme d'habitude.

--- start ---
import appModuleHandler

class AppModule(appModuleHandler.AppModule):

	sleepMode = True

--- end ---

Fourniture de classes d'objets NVDA personnalisées

Fournir des classes d'objet NVDA à l'intérieur d'un greffon NVDA est probablement le moyen le plus puissant et le plus utile pour améliorer l'utilisation d'une application. Cette méthode vous permet de placer l'ensemble de tout ce qui est nécessaire pour un contrôle précis dans une classe d'objet NVDA, plutôt que de disperser le code des contrôles dans les événements de nombreux greffons.

Il y a deux étapes pour créer une classe d'objet NVDA personnalisée :

• Définir la classe d'objet NVDA et ses événements, scripts, gesture bindings et propriétés de remplacement ;
• Dire à NVDA d'utiliser cette classe d'objets NVDA pour des situations spécifiques en le définissant dans la méthode chooseNVDAObjectOverlayClasses du greffon.

Lors de la définition d'une classe d'objets NVDA personnalisée, vous pouvez choisir parmi les nombreuses classes de NVDAObjec de base. Ces classes de base contiennent le support de base, notamment pour l'accessibilité ou une OS API sous-jacente au contrôle, tels que Win32, MSAA ou Java access Bridge. Vous devriez normalement hériter vos classes personnalisées NVDAObject de la classe de base la plus élevée dont vous avez besoin pour que votre classe soit choisi en premier. Par exemple, si vous choisissez d'utiliser votre classe NVDAObject personnalisée lorsque le nom de la classe window est "Edit" (Edition) et l'ID du window contrôle est de 15, vous devriez probablement hériter de NVDAObjects.window.Window, aussi clairement que vous êtes conscient que c'est un objet fenêtre. De même, si vous lui associez la propriété accRole de MSAA, vous aurez probablement besoin d'hériter de NVDAObjects.IAccessible.IAccessible. Vous devriez également songer aux propriétés que vous allez substituer dans les objets personnalisés NVDA. Par exemple, si vous substituez une propriété IAccessible spécifiques tels que shouldAllowIAccessibleFocusEvent, alors vous aurez besoin d'hériter de NVDAObjects.IAccessible.IAccessible.

La méthode chooseNVDAObjectOverlayClasses peut être implémentée dans des modules App ou des classes de greffons globaux.

Elle prend 3 arguments :

• self (auto) : l'instance du module app ou du greffon global ;
• obj (objet) : le NVDAObject pour lequel les classes sont choisies ;
• clsList : une liste de classes Python de NVDAObject qui sera utilisées pour obj.

À l'intérieur de cette méthode, vous devez décider de l'usage des classes d'objets NVDA (le cas échéant) si cet objet NVDA doit être utilisé en vérifiant ses propriétés, etc. Si une classe personnalisée doit être utilisée, elle doit être insérée dans la liste de classes, généralement au début. Vous pouvez également supprimer de la liste de classes des classes choisies par NVDA, bien que cela soit rarement nécessaire.

Exemple 5 : étiquetage du champ d'édition de Notepad à l'aide d'un objet NDVA personnalisé

Ce module app pour Notepad fait renvoyer par NVDA le nom de la zone d'édition principale du bloc-notes comme étant "Content". Autrement dit, lorsqu'il reçoit le focus, NVDA dira "Content edit" (éditer le contenu).

Le code suivant peut être copié et collé dans un fichier texte, puis enregistré dans le répertoire appModules en le nommant notepad.py.

--- start ---
import appModuleHandler
from NVDAObjects.window import Window

class AppModule(appModuleHandler.AppModule):

	def chooseNVDAObjectOverlayClasses(self, obj, clsList):
		if isinstance(obj, Window) and obj.windowClassName == "Edit" and obj.windowControlID == 15:
			clsList.insert(0, LabelledEditField)

class LabelledEditField(Window):

	name="Content"

--- end ---

NVDA Python Console

The NVDA Python console emulates the interactive Python interpreter from within NVDA. It is a development tool which is useful for debugging, general inspection of NVDA internals or inspection of the accessibility hierarchy of an application.

Usage

The console can be activated in two ways:

• By pressing NVDA+control+z. If activated in this fashion, a snapshot of the current state of NVDA at the time the key was pressed will be taken and saved in certain variables available in the console. See Snapshot Variables for more details.
• By selecting Tools -> Python console from the NVDA system tray menu.

The console is similar to the standard interactive Python interpreter. Input is accepted one line at a time. The current line is processed when enter is pressed. You can navigate through the history of previously entered lines using the up and down arrow keys.

Output (responses from the interpreter) will be spoken when enter is pressed. The f6 key toggles between the input and output controls.

Closing the console window simply hides it. This allows the user to return to the session as it was left when it was closed, including history and variables.

Namespace

Automatic Imports

For convenience, the following modules and variables are automatically imported in the console: sys, os, wx, log (from logHandler), api, queueHandler, speech, braille

Snapshot Variables

Whenever NVDA+control+z is pressed, certain variables available in the console will be assigned according to the current state of NVDA. These variables are:

• focus: The current focus object
• focusAnc: The ancestors of the current focus object
• fdl: Focus difference level; i.e. the level at which the ancestors for the current and previous focus differ
• fg: The current foreground object
• nav: The current navigator object
• mouse: The current mouse object
• brlRegions: The braille regions from the active braille buffer