diff --git a/user_docs/de/developerGuide.md b/user_docs/de/developerGuide.md deleted file mode 100644 index 19398982edb..00000000000 --- a/user_docs/de/developerGuide.md +++ /dev/null @@ -1,684 +0,0 @@ -# NVDA NVDA_VERSION Handbuch für Entwickler - -[TOC] - - - -## Einleitung {#toc2} - -Dieses Handbuch stellt informationen zur Entwicklung von NVDA und dessen Komponenten sowie ihre Übersetzungen bereit. -(HINWEIS: Dies ist lediglich eine Einführung. Für die komplette Referenz ist es für Entwickler empfehlenswert sich die Code-Dokumentation durchzulesen.) - -### Eine Anmerkung zu Python {#toc3} - -NVDA und dessen Erweiterungen werden in der Programmiersprache Python geschrieben. -Das Ziel dieses Handbuches ist nicht, Ihnen Python beizubringen, lediglich stellt es Beispiele zur Veranschaulichung der Syntax in Python bereit. -Die Dokumentationen und weitere Materialien sind einer oder mehreren der folgenden Bezugsquellen zu finden: - -* Einen guten Einstieg in Python bietet das Buch [Python](http://openbook.galileocomputing.de/python/index.htm#_top) von Galileo computing. -* Ein sehr gutes Nachschlagewerk bietet außerdem das [deutsche Python-Wiki](http://wiki.python.de/) -* Mit Hilfe der Python-Konsole können weitere Informationen über ein bestimmtes Objekt gewonnen werden. Wenn Sie den Navigator auf das fragliche Objekt gesetzt und die Python-Konsole aufgerufen haben, können Sie mit den folgenden Befehlen weitere Informationen über dieses Objekt erhalten: - * Um die Code-Dokumentation und die Online-Hilfe zu dem aktuellen Navigator-Objekt anzuzeigen, verwenden Sie den folgenden Befehl: help(nav) Die ausgabe des Befehls kann sehr umfangreich sein, weil nicht nur Informationen über das Navigator-Objekt selbst, sondern auch über alle seine Vorfahren angezeigt werden. Es ist daher zu empfehlen, sich den Inhalt des ausgabefensters in einer Textdatei zu speichern, um bei der weiteren Entwicklungsarbeit darauf zurückgreifen zu können. - * Um alle Eigenschaften und Methoden des aktuellen Navigator-Objekts als Python-Wörterbuch anzuzeigen, verwenden Sie den folgenden Befehl: dir(nav) - -## Übersetzung {#toc4} - -Damit NVDA mehrere Sprachen bzw. Sprachräume unterstützt, muss es übersetzt und sprachspezifische Daten müssen zur Verfügung gestellt werden. - -### Beschreibungen der Sonderzeichen {#toc5} - -Manchmal kann es schwierig bis unmöglich sein, zwei Zeichen voneinander zu unterscheiden. -Zwei Zeichen können beispielsweise identisch ausgesprochen werden, auch wenn es eigentlich völlig unterschiedliche Zeichen sind. -Um dieses problem zu lösen, können Zeichenbeschreibungen bereitgestellt werden, die jedes Zeichen eindeutig beschreiben. - -Zeichenbeschreibungen für einen Sprachraum können in einer Datei characterDescriptions.dic bereitgestellt werden, die sich im Verzeichnis des jeweiligen Sprachraums befinden muss. -Die Datei muss im UTF-8 kodiert werden. -Leerzeilen und Zeilen, die mit einem "#" beginnen, werden ignoriert. -Alle anderen Zeilen müssen ein Zeichen gefolgt von einem Tabulator und dessen Beschreibung enthalten. - -zum Beispiel: - - # Dies ist ein Kommentar - a Anton - b Berta - -Ein vollständiges Beispiel finden Sie in der Datei "locale\de\characterDescriptions.dic". - -### Aussprache der Symbole {#toc6} - -Für Sprachausgabennutzer ist es oft sinnvoll, beim zeichenweisen Navigieren Sonderzeichen als Wörter angesagt zu bekommen. -Unglücklicherweise sprechen verschiedene Sprachausgaben die Sonderzeichen sehr unterschiedlich aus. Manche Sprachausgaben erlauben keine Kontrolle über die Aussprache von Sonderzeichen. -Hierfür können Informationen über die Aussprache von Sonderzeichen in NVDA mitgegeben werden. - -Dieses kann sprachspezifisch in der im UTF-8 kodierten Datei namens "Symbols.dic" im Verzeichnis des jeweiligen Sprachraums erfolgen. -Leerzeilen und Zeilen, die mit einem "#" beginnen, werden ignoriert. -Alle Sprachräume erben die Sonderzeichenaussprache des Englischen. - -Die Datei enthält dabei zwei Abschnitte. - -#### Komplexe Symbole definieren {#toc7} - -Der erste Abschnitt ist optional und enthält Definitionen komplexer Symbole in Form regulärer Ausdrücke. -Komplexe Symbole sind nicht einfach nur Sonderzeichen oder Sequenzen von Sonderzeichen, die durch Wörter ersetzt werden sollen. Stattdessen erfordern sie eine kompliziertere Überprüfung auf Übereinstimmung. -Ein Beispiel ist der Punkt als Satzzeichen im Deutschen. -Da der Punkt mehrere Bedeutungen hat, ist eine komplexere Überprüfung erforderlich um zu bestimmen, ob er sich auch tatsächlich am Ende eines Satzes befindet. - -Der Abschnitt für komplexe Symbole beginnt mit der folgenden Zeile: - - complexSymbols: - -Die einzelnen Zeilen innerhalb dieses Abschnittes enthalten einen Namen für ein Symbol, ein Tab-Zeichen und einen Regulären Ausdruck für ein Symbol. - -Zum Beispiel: - - . Satzende (?<=[^\s.])\.(?=[\"')\s]|$) - -Da ein jeder Sprachraum die komplexen Symbole des englischen Sprachraumes erbt, brauchen Sie diese in Ihrer Symboldefinition nicht noch einmal aufzuführen. - -#### Symbol-Informationen definieren {#toc8} - -Der zweite Abschnitt enthält Informationen darüber, ob und wie Symbole ausgesprochen werden. -Er beginnt mit der Zeile: - - symbols: - -Die Zeilen dieses Abschnitts enthalten mehrere Felder, die durch Tabstopps getrennt sind. -Die einzigen Pflichtfelder sind der Name des Symbols und der Ersatztext. -Für leere Felder wird der Standardwert verwendet. - -Folgende Felder sind verfügbar: - -* Name: Der Name eines Symbols -Meistens wird hier das zu verarbeitende Sonderzeichen oder der name eines komplexen Symbols angegeben. Einige Sonderzeichen können nicht eingegeben werden. Hierfür können die folgenden Sequenzen verwendet werden: -* \0: Null -* \t: Tabulator -* \n: Zeilenumbruch -* \r: Wagenrücklauf -* \f: Seitenvorschub -* \#: #-Zeichen (benötigt einen Backslash, da dieses #-Zeichen sonst als Kommentar angesehen wird) -* Ersatztext: der Text, der anstelle des Symbols ausgesprochen werden soll. -* Ebene: die Symbolebene, ab der das Symbol gesprochen werden soll. - -Die Symbolebene kann vom Anwender konfiguriert werden und gibt die Menge an auszusprechenden Sonderzeichen an. -Dieses Feld sollte einen der Werte "none", "some", "most", "all" oder "char" enthalten oder "-", um den Standardwert zu erzwingen. -Die Spezifikation "char" bedeutet, dass das Symbol nur bei der zeichenweisen Navigation verarbeitet wird. -Standardmäßig wird hier der vom Englischen geerbte Wert verwendet oder "all", falls es nichts zu erben geben sollte. -* Beibehalten: Dieses Feld muss immer dann belegt sein, wenn ein bestimmtes Symbol unverarbeitet an den Synthesizer weitergegeben werden soll, um eine korrekte Aussprache zu ermöglichen. -Beispiele hierfür sind Sonderzeichen, die Sprachpausen verursachen, wie z.B. der Punkt, das Komma etc. -Dieses Feld kann die folgenden Werte enthalten: -* never: Das Symbol wird nie beibehalten. -* always: das Symbol wird immer beibehalten. -* norep: Das Symbol wird nur dann beibehalten, wenn es nicht ersetzt wird (z.B. wenn der Anwender die Satzzeichen- und Symbolebene niedriger eingestellt hat, als für das betreffende Symbol. -* -: verwendet den Standardwert. -Standardmäßig wird der Wert vom englischen Sprachraum vererbt oder "never" verwendet, falls es nichts zu erben geben sollte. - -Am ende der Zeile kann schließlich noch ein Anzeigename für ein Symbol vergeben werden. -Dieser Name wird Anwendern angezeigt, wenn sie die komplexen Symbole bearbeiten wollen. Er kann auch von übersetzern verwendet werden, um übersetzte Namen für die englischen komplexen Symbole bereitzustellen. - -Hierzu einige Beispiele: - - ( runde Klammer auf most - -Dies bedeutet, dass das Zeichen "(" als "Runde Klammer auf" gesprochen werden soll, wenn der Anwender die Satzzeichen- und Symbolebene auf "meiste" oder "alle" eingestellt hat. - - , Komma all always - -Dies bedeutet, dass das Zeichen "," als "Komma" gesprochen werden soll, wenn als Satzzeichen- und Symbolebene "all" eingestellt ist. Außerdem wird das Zeichen immer unverändert an den Synthesizer übergeben, um Sprechpausen korrekt zu setzen. - - . sentence ending point # . fin de phrase - -Diese Zeile stammt aus der französischen Datei symbols.dic. -Sie besagt, dass das komplexe Symbol ". sentence ending" als "point" gesprochen werden soll.. -Ebene und Einstellung zum Beibehalten des Symbols sind hier nicht angegeben, werden also vom englischen Sprachraum geerbt. -Ein anzeigename wird ebenfalls angegeben, sodass französische nvda-Nutzer wissen, was dieses Symbol bedeutet. - -Bitte sehen Sie sich die Datei locale\en\symbols.dic für die englischsprachigen Symboldefinitionen an. - -## Plugins {#toc9} -### Übersicht {#toc10} - -Mittels der Plugins erhalten Sie die Möglichkeit, das Verhalten global oder in bestimmten Anwendungen nach Ihren Wünschen anzupassen. -Das sind unter anderem: - -* Auf bestimmte Ereignisse reagieren, wenn sich zum Beispiel der Fokus verschiebt oder wenn sich die Eigenschaften eines Objekts ändern. -* Befehle implementieren, die an bestimmte Tastendrücke oder andere Eingabemethoden gebunden werden können. -* Das Verhalten bestimmter Steuerelemente beeinflussen oder weitere Funktionen hinzufügen. -* Unterstützung für Textinhalte oder komplexe Dokumente anpassen oder hinzufügen. - -Dieser Abschnitt enthält lediglich eine Einführung in die Entwicklung von Plug-ins. Schauen Sie sich die Code-Dokumentation für eine komplette Referenz an. - -### Typen der Plugins {#toc11} - -Folgende zwei Typen der Plugins gibt es: - -* Anwendungsmodule: Enthalten speziellen Code für eine bestimmte Anwendung. -Ein Anwendungsmodul nimmt Ereignisse für eine bestimmte Anwendung entgegen, auch wenn die Anwendung momentan nicht fokussiert ist. -Wenn eine Anwendung fokussiert ist, kann der Nutzer sämtliche Befehle ausführen, die im Anwendungsmodul definiert und an Eingabemethoden zugewiesen wurden. -* Allgemeine Plugins: Diese enthalten Code, die überall, auch in allen Anwendungen funktionieren. -Dabei nehmen Sie alle Ereignisse von allen Elementen im Betriebssystem entgegen. -Befehle, die in allgemeinen Plugins an Eingabemethoden zugewiesen wurden, können unabhängig davon ausgeführt werden, welche Anwendung grade aktiv ist. - -Wenn Sie vorhaben die Zugänglichkeit von NVDA für bestimmte Anwendungen zu verbessern, sind die Anwendungsmodule empfehlenswert. -Im Gegensatz, wenn Sie vorhaben globalen Code für NVDA zu entwickeln, der systemweit zugänglich sein soll, zum Beispiel um sich die Signalstärke von Funknetzwerken anzeigen zu lassen, ist ein allgemeines Plugin empfehlenswert. - -Anwendungsmodule und die allgemeinen Plugins sind sehr ähnlich. -Dies sind beides Python-Quelldateien (mit der Erweiterung .py), die dabei eine spezielle Klasse definieren, die sämtliche Ereignisse, Skripte und Komponenten beinhalten und die Zugriffssteuerung der eigenen Klassen, Textpassagen und komplexen Dokumenten definieren. -Dabei unterscheiden sie sich jedoch in einigen Punkten. - -Die folgenden Abschnitte beschreiben separat die Anwendungsmodule und die allgemeinen Plugins Anschließend werden wieder allgemeinere Punkte erläutert. - -### Grundlagen eines Anwendungsmoduls {#toc12} - -Anwendungsmodule besitzen die Erweiterung .py und haben den gleichen Namen wie die Anwendungen, für die sie verwendet werden sollen. -Ein Anwendungsmodul für den Editor müsste zum Beispiel notepad.py heißen, weil die ausführbare Datei des Editors notepad.exe heißt. - -Anwendungsmodule müssen im Unterordner "appModules" der Benutzerkonfiguration von nvda liegen. -Weitere Informationen über den Standort Ihres benutzerspezifischen Konfigurationsverzeichnisses finden Sie im Benutzerhandbuch von NVDA. - -Anwendungsmodule müssen eine Klasse "appModule" definieren, die alle Eigenschaften und Methoden von appModuleHandler.AppModule erbt. -Diese Klasse kann dann Ereignisse, Scripte, Eingabemethodenzuweisungen und anderen Code enthalten. -Details hierzu lesen Sie weiter unten. - -Sobald NVDA erkennt, dass eine bestimmte Anwendung gestartet wird, wird das jeweilige Anwendungsmodul geladen. -Wenn die betreffende Anwendung oder NVDA beendet wird, wird auch das Anwendungsmodul wieder aus dem Speicher entfernt. - -### Beispiel 1: Ein Anwendungsmodul erzeugt Signaltöne bei Ereignissen, wenn sich der Fokus verändert {#Example1} - -Das folgende anwendungsmodul gibt jedes mal einen Signalton wieder, wenn sich innerhalb des Editors der Fokus ändert. -Dieses Beispiel veranschaulicht den grundsätzlichen Aufbau eines Anwendungsmoduls. - -Fügen Sie den Folgenden Code zwischen den Start- und Endmarken (jedoch nicht die Marken selbst) in eine Datei mit dem Namen notepad.py und speichern Sie diese im Unterverzeichnis appmodules in ihrer benutzerspezifischen nvda-Konfiguration. -Übernehmen Sie hierbei auch alle Tab- und Leerzeichen. - -Starten Sie anschließend NVDA neu oder wählen Sie Plugins neu laden" aus dem Menü Extras, damit die Änderungen wirksam werden. - -Öffnen Sie zu guter Letzt den Editor und bewegen Sie den Fokus innerhalb der Anwendung (z.B. innerhalb des Menüs, innerhalb von Dialogfeldern, etc.). -Sie sollten nun jedes Mal einen Signalton hören, wenn sich der Fokus ändert. -Wenn Sie sich jedoch außerhalb des Editors (z. B. im Explorer) befinden, sollten Sie keine Signaltöne hören. - - --- Beginn --- - # NVDA-Anwendungsmodul für den Editor - # Beispiel 1 aus dem Entwicklerhandbuch - - import appModuleHandler - - class AppModule(appModuleHandler.AppModule): - - def event_gainFocus(self, obj, nextHandler): - import tones - tones.beep(550, 50) - nextHandler() - - --- Ende --- - -Dieses Anwendungsmodul beginnt mit zwei Kommentarzeilen, die den Zweck des Anwendungsmoduls beschreiben. - -Anschließend wird das Modul "appmodule" importiert, welches die Basisklasse für Anwendungsmodule zur Verfügung stellt. - -Als nächstes wird eine Klasse namens AppModule definiert, die von appModuleHandler.AppModule abgeleitet ist. - -Innerhalb der Klasse werden ein oder mehr Ereignisse, scripte oder Eingabemethodenzuweisungen definiert. -Dieses Beispiel definiert ein Ereignis namens gainfocus (event_gainFocus), das bei jeder Ausführung einen kurzen Signalton abspielt. -Die Implementierung des Ereignisses ist für dieses Beispiel noch nicht wichtig, wichtig ist lediglich die Definition der Klasse. - -Ereignisse werden weiter unten in diesem Handbuch näher erläutert. - -Denken Sie - wie bei anderen Beispielen in diesem handbuch - daran, das erstellte anwendungsmodul zu löschen und NVDA neu zu starten bzw. die Plugins neuzuladen, wenn Sie Ihre Tests abgeschlossen haben, um das ursprüngliche Verhalten von NVDA wiederherzustellen. - -### Grundlagen der Allgemeinen Plugins {#toc14} - -Globale Plug-ins sollten die Erweiterung .py besitzen und einen kurzen Namen haben, der ihren Zweck beschreibt. - -Globale Plugins müssen im unterordner "GlobalPlugins" des benutzerspezifischen Konfigurationsverzeichnisses liegen. -Weitere Informationen darüber, wo Sie das benutzerspezifische Konfigurationsverzeichnis finden, finden Sie im NVDA-Benutzerhandbuch. - -Globale Plugins müssen eine Klasse namens GlobalPlugin, definieren, die ein direkter Nachkomme von globalPluginHandler.GlobalPlugin ist. -Diese klasse kann anschließend Ereignisse, Script-Methoden, Eingabemethoden-zuweisungen und anderen Code enthalten. -All dies wird im Folgenden behandelt. - -NVDA lädt alle globalen Plug-ins, sobald er gestartet wird und entlädt sie beim Beenden wieder. - -### Beispiel 2: Eine Standarderweiterung - Ein Skript zur Ansage der NVDA-Version {#toc15} - -Das folgende Beispiel erlaubt Ihnen, sich von überall im System aus mit der Tastenkombination NVDA+Umschalt+V die NVDA-Version anzeigen zu lassen. -Das Beispiel dient lediglich dazu, den grundlegenden Aufbau globaler Plugins zu veranschaulichen. - -Kopieren sie den folgenden Text zwischen den Anfangs- und Endmarkern (jedoch nicht die Marker selbst), in eine Datei namens beispiel2.py und speichern Sie diese im Unterofdner "GlobalPlugins" Ihres NVDA-Konfigurationsverzeichnisses. -Lassen Sie dabei alle Tabs und Leerzeichen stehen. - -Starten Sie nach dem Speichern entweder NVDA neu oder wählen aus dem menü Extras des nvda-Menüs den Befehl Plug-ins neu laden. - -Von nun an können Sie NVDA+Umschalt+V drücken, um die NVDA-Version angesagt und in Braille angezeigt zu bekommen. - - --- Beginn --- - # Plugin zur Ausgabe der Versionsinformationen in NVDA - # Beispiel 2 aus dem Entwicklerhaldbuch - - 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", - } - - --- Ende --- - -Dieses globale Plugin beginnt mit zwei Kommentarzeilen, die den Zweck der Datei kurz beschreiben. - -Anschließend wird das Modul globalPluginHandler importiert, sodass das Plug-in Zugriff auf die Basisklasse GlobalPlugin hat. - -Außerdem werden noch die Module UI und Versioninfo importiert, damit das Plugin die Versionsinformationen ausgeben kann. - -Als nächstes wird eine Klasse GlobalPlugin, definiert, die ein Nachkomme von globalPluginHandler.GlobalPlugin ist. - -Innerhalb dieser Klasse werden ein oder mehrere Ereignisse, Scripte oder Eingabemethoden-Zuweisungen definiert. -In diesem Beispiel enthält die Klasse ein Script, das die Versionsinformationen ausgibt und eine eingabemethoden-Zuweisung, die dieses Script an NVDA+Umschalt+V zuweist. -Die Details des Scripts und der Eingabemethodenzuweisung sind für dieses Beispiel jedoch nicht von Belang. -Das wichtigste ist die Klasse selbst. - -Um das urspründliche Verhalten von NVDA wiederherzustellen, müssen Sie die globale Plugin-Datei löschen und NVDA anschließend neu starten oder die Plugins neu laden. - -### NVDA-Objekte {#toc16} - -NVDA stellt Steuerelemente und andere Bestandteile von Benutzeroberflächen in Form von NVDA-Objekten dar. -Diese Objekte enthalten standardisierte Eigenschaften wie name, Typ, Wert, Status und Beschreibung. Dies erlaubt anderen Teilen von NVDA, diese Informationen über ein Objekt in verallgemeinerter Form abzufragen oder darzustellen. -Die Schaltfläche "OK" in einem Dialogfeld wird beispielsweise den Namen "OK" und den Steuerelementtyp "Schaltfläche" besitzen. -So ähnlich würde beispielsweise ein Kontrollkästchen mit der Beschriftung "Ich stimme zu" den Namen "Ich stimme zu", den Typ Kontrollkästchen und - falls aktiviert - den Status aktiviert besitzen. - -Auch wenn es unterschiedliche Komponentenbausätze für Benutzeroberflächen und Zugänglichkeitsschnittstellen gibt, abstrahieren NVDA-Objekte diese unterschiede zu einer einheitlichen Form, gleichgültig, mit welchem Komponentenbausatz ein Steuerelement erzeugt wurde oder über welche ugänglichkeitsschnittstelle darauf zugegriffen wird. -Der oben angesprochene Schalter "OK" könnte also beispielsweise ein Java-Objekt sein. Genauso gut könnte er aber auch ein MSAA-Objekt, ein iAccessible2-Objekt oder ein UIA-Element sein. - -NVDA-Objekte haben viele Eigenschaften. -einige der nützlichsten sind: - -* name: Die Beschriftung des Steuerelements -* role: Der Typ des Steuerelements, repräsentiert durch eine der ROLE_*-Konstanten aus dem Anwendungsmodul controltypes -Schaltfläche, Dialogfeld, Eingabefeld, Fenster und Kontrollkästchen sind nur einige Beispiele für Steuerelementtypen. -* states: Status des Steuerelements, repräsentiert durch einen Satz von 0 oder mehr STATE_*-Konstanten as dem Modul controltypes. -hervorhebbar, hervorgehoben, ausgewählt, auswählbar, erweitert, reduziert und aktiviert sind nur einige Beispiele für den Status. -* value: Der Wert des Steuerelements z.B. der aktuelle Stand einer Fortschrittsanzeige oder der aktuelle gewählte Eintrag in einem Kombinationsfeld. -* description: Eine kurze Beschreibung, die den Zweck des Steuerelements erläutert (üblicherweise identisch mit der Minihilfe). -* location: Der Abstand eines Objektes von der oberen linken Ecke des Bildschirms sowie dessen Breite und Höhe in Form von Bildschirmkoordinaten. -* parent: Das übergeordnete Objekt -Das Übergeordnete Objekt eines Listeneintrags ist beispielsweise die Liste, die ihn enthält. -* next: Das nächste Objekt in der logischen Reihenfolge -* previous: Das vorherige Objekt in der logischen Reihenfolge -* firstChild: Der erste direkte Nachkomme eines Objekts. -Der erste Nachkomme einer Liste ist beispielsweise deren erster Eintrag. -* lastChild: Der letzte Nachkomme eines Objekts. - * children: Eine Liste aller Nachkommen eines Objekts (beispielsweise alle Einträge eines Menüs). -- - -Es gibt auch noch Eigenschaften, die sich auf die vereinfachte Navigation beziehen wie "simpleParent", "simpleNext", "simpleFirstChild" und "simpleLastChild". -Diese entsprechen den oben beschriebenen Eigenschaften, NVDA filtert hier jedoch nutzlose Objekte aus. -Diese eigenschaften werden immer dann verwendet, wenn der vereinfachter Darstellungsmodus in NVDA aktiviert ist, was der Normalfall ist. -Die vereinfachten Eigenschaften sind zwar leichter zu verwenden, die komplexeren Eigenschaften spiegeln jedoch diezugrundeliegende Objektstruktur des Betriebsystems wesentlich besser wieder. - -Wenn Sie NVDA-Plugins entwickeln, spielt es meistens keine Rolle, mit welchem Komponentenbausatz die Benutzeroberfläche erstellt wurde oder mit welcher Zugänglichkeitsschnittstelle Sie darauf zugreifen müssen. Meistens können sie mit Standardeigenschaften auf die Objekte zugreifen wie z. B. dessen Namen, Wert oder Status. -Wenn Plug-ins komplexer werden, kann es jedoch erforderlich werden tiefer in die Objekte abzusteigen, um Komponentenbausatz- oder zugänglichkeitsschnittstellen-spezifische Informationen zu erhalten. - -Es gibt drei Möglichkeiten, wie Plug-ins nvda-Objekte verwenden können: -* Die meisten Ereignisse verarbeiten ein Argument, das dasjenige Objekt angibt, auf das sich das Ereignis bezieht. -Das Ereignis event_gainfocus übernimmt beispielsweise dasjenige Objekt als Parameter, das soeben den Fokus bekommen hat. -* Skripte und Ereignisse können Objekte verarbeiten Wie z. B. das aktuell hervorgehobene Objekt, das aktuelle navigatorobjekt oder den Desktop. -Anschließend könnte auf andere Objekte bezug genommen und Informationen von ihnen abgerufen werden. -* Das Plug-in könnte auch eine eigene NVDA-Objektklasse definieren, um ein bestimmtes Steuerelement darin einzuschließen. Solche benutzerdefinierten NVDA-Objekte können einem NVDA-Objekt neue Fnktionalität geben, dessen Eigenschaften umwandeln, etc. - -Ebenso wie Anwendungsmodule oder globale Plug-ins können nvda-Objekte Scripte, Ereignisse und Eingabemethoden-zuweisungen enthalten. - -### Skripte und Tastenanbindung {#toc17} - -Anwendungsmodule, globale Plugins und NVDA-Objekte können Methoden enthalten, die an Ereignisse wie z.B. Tastendrücke zugewiesen werden können. -Auf solche Methoden greift NVDA mit Hilfe von Skripten zu. - -Ein Skript ist eine standard-Python-Instanzmethode, deren Name mit "Script_" beginnt, wie z. B. "script_sayDateTime". - -Eine Skriptmethode verarbeitet zwei Argumente: - -* self: Eine Referenz auf das Anwendungsmodul, globale Plugin oder NVDA-Objekt, von dem aus das Skript aufgerufen wird. -* gesture: Ein Eingabemethoden-Objekt, das die Ausführung des Script verursacht hat. - -Neben dem eigentlichen Skript muss noch ein Eingabemethoden-Objekt definiert werden, damit NVDA bekannt ist, durch welches Ereignis das Script aufgerufen werden soll. - -Um eine Eingabemethode an ein Skript zuzuweisen, kann ein spezielles Python-Wörterbuch namens "__gestures" als Klassenvariable definiert werden. Dies kann innerhalb eines anwendungsmoduls, eines globalen Plug-ins oder eines NVDA-Objekts geschehen. -Diese Wörterbücher sollten Einträge mit den Eingabemethoden enthalten, die auf die entsprechenden Scripts zeigen. Der name muss hierbei ohne das Präfix "Script_" angegeben werden. - -Es gibt zwar noch kompliziertere und dynamischere Methoden, Eingabemethoden zuzuweisen, das Wörterbuch __gestures ist jedoch der einfachste Weg. - -Der Bezeichner für eine Eingabemethode ist eine einfache Zeichenfolge, die die Eingabemethode repräsentiert. -Er enthält einen zweistelligen Code, der die Eingabequelle beschreibt, einen optionalen Gerätenamen in Klammern, einen Doppelpunkt und eine oder mehrere Tastenbezeichnungen, die durch ein Pluszeichen voneinander getrennt werden. - -Einige Beispiele für eingabemethodenbezeichner sind: - -* "kb:NVDA+Shift+V" -* "br(freedomScientific):leftWizWheelUp" -* "kb(laptop):NVDA+T" - -Aktuell werden folgende Eingabequellen unterstützt: - -* kb: Tastatureingaben -* br: Tastendrücke und andere navigierende Eingaben an Braillezeilen - -Wenn NVDA eine Tastatureingabe registriert, sucht es in eine bestimmten Reihenfolge nach einr entsprechenden Eingabemethoden-Zuweisung. -Wurde eine Zuweisung gefunden, so wird das entsprechende Skript ausgeführt. Weder wird weiter nach Eingabemethoden-Zuweisungen gesucht, noch wird der Tastendruck ans Betriebssystem weitergereicht. - -Folgende Reihenfolge wird bei der Suche nach Eingabemethodenzuweisungen verwendet: - -* Geladene globale Plugins -* Anwendungsmodul der aktiven Anwendung -* Der Interceptor des NVDA-Objekts, das den Fokus hat (wie beispielsweise ein virtueller Puffer). -* Das NVDA-Objekt, welches den Fokus besitzt -* Globale, eingebaute Befehle wie beispielsweise das Beenden von NVDA, die Objektnavigation, usw. - -### Beispiel 3: Ein globales Plugin zum Aufspüren von FensterKlassen und Steuerelementen {#toc18} - -Das folgende globale Plugin bewirkt, dass Sie NVDA+Pfeil_links drücken können, um die Fensterklasse des aktuellen Fensters zu erfahren. Ebenso können Sie NVDA+Pfeil_rechts drücken, um die Steuerelement-id des aktuellen Objekts zu erfahren. -Das Beispiel veranschaulicht, wie Sie ein Skript und eine Eingabemethodenzuweisung in einem globalen Plugin definieren. - -Speichern Sie den Text innerhalb der Start- und Endmarken (jedoch nicht die Marken selbst) in einer Datei beispiel3.py im Unterverzeichnis "globalPlugins" ab. -Achten Sie dabei darauf, alle Tabs und Leerzeichen exakt zu übernehmen. - -Starten Sie nach dem Speichern entweder NVDA neu oder wählen Sie im NVDA-Menü den Befehl "Plugins neu laden" aus dem Menü "Extras". - - --- Beginn --- - # Hilfs-Skript für NVDA - # Beispiel 3 aus dem Entwicklerhandbuch - - 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("Das Fenster %s besitzt die Fensterklasse %s" % (name, windowClassName)) - - def script_announceWindowControlID(self, gesture): - focusObj = api.getFocusObject() - name = focusObj.name - windowControlID = focusObj.windowControlID - ui.message("Das Fenster %s hat die Steuerelementnummer %d" % (name, windowControlID)) - - __gestures = { - "kb:NVDA+leftArrow": "announceWindowClassName", - "kb:NVDA+rightArrow": "announceWindowControlID", - } - - --- Ende --- -### Ereignisse {#toc19} - -wenn NVDA ein Betriebssystemereignis erkennt, so wird dieses abstrahiert und ein eignes Ereignis bei nvda-Objekten ausgelöst. - -Wenngleich die meisten Ereignisse zu bestimmten NVDA-Objekte gehören (wie z. B. Umbenennungen, Fokuserhalt, Statusänderung, etc.), können sie auf unterschiedlichen Ebenen verarbeitet werden. -Wird ein Ereignis behandelt, so wird es nicht mehr weitergereicht. -Das Weiterreichen des Ereignsses kann jedoch durch Code innerhalb der Ereignisbehandlungsroutine erzwungen werden, falls nötig. - -Ereignisse werden in folgender Reihenfolge abgearbeitet: - -* Durch geladene globale Plugins. -* Durch das Anwendungsmodul, das dem Objekt zugeordnet wurde, bei dem das Ereignis eintrat. -* Durch den Interceptor (falls vorhanden) der dem Objekt zugeordnet wurde, bei dem das Ereignis eintrat. -* Durch das NVDA-Objekt selbst. - -Ereignisse sind Python-Instanzmethoden, deren namen mit event_ beginnen, gefolgt von dem Namen des eigentlichen Ereignisses (wie z. B. gainFocus). - -Diese Ereignismethoden verarbeiten unterschiedliche Argumente, abhängig davon, auf welcher Ebene sie aufgerufen werden. - -Wenn ein Ereignis, das sich auf ein NVDA-Objekt bezieht im NVDA-Objekt selbst definiert wird, akzeptiert es ein Argument namens "self", das die Instanz des NVDA-Objekts darstellt. -einige Ereignisse verarbeiten noch zusätzliche Argumente, dies ist allerdings ziemlich selten. - -Wird ein Ereignis, das sich auf ein NVDA-Objekt bezieht, in einem globalen Plug-in, in einem Anwendungsmodul oder in einem Interceptor definiert, verarbeitet es die folgenden Argumente: - -* self: Die Instanz des Anwendungsmoduls, des globalen Plugins oder des Interceptors. -* obj: Das NVDA-Objekt, welches das Ereignis ausgelöst hat. -* nextHandler: Eine Funktion, die bei ihrem Aufruf das Ereignis weiter durchreicht. - -einige häufig verwendete NVDA-Objektereignisse sind: - -* foreground: Dieses Objekt wurde zum neuen Vordergrundfenster d.h. zur neuen aktiven Anwendung. -* gainFocus: Das Objekt erhielt soeben den Fokus. -* loseFocus: Das Objekt hat den Fokus verloren. -* nameChange: Das Objekt wurde umbenannt. -* valueChange: In dem Objekt wurde der Wert geändert (z. B., wenn in einem Kombinationsfeld ein neuer Eintrag ausgewählt wurde). -* stateChange: Das Objekt änderte seinen Status (aktivieren / deaktivieren von Kontrollfeldern, etc.). -* caret: Wird ausgelöst, sobald sich der System-Cursor innerhalb des Objektes bewegt. -* locationChange: Wird ausgelöst, sobald ein Objekt physisch auf dem Bildschirm verschoben wird. - -Es gibt zwar noch viel mehr, die oben aufgeführten Ereignisse sind jedoch die gebräuchlichsten. - -Ein Beispiel für eine Ereignisbehandlungsroutine finden Sie im Beispiel 1. - -### Die Schlafmodus-Variablen der Anwendungsmodule {#toc20} - -Anwendngsmodule besitzen eine sehr nützliche Eigenschaft namens "aleepmode". Diese Eigenschaft deaktiviert, wenn sie auf True gesetzt wird, fast alle Funktionen von NVDA. -Der Schlafmodus ist nützlich für anwendung, die eigene Bildschirmlese-Funktionen besitzen oder für Spiele, bei denen man volle Kontrolle über die Tastatur benötigt. - -Obwohl der Anwender den Schlafmodus mit NVDA+Umschalt+S ein- und ausschalten kann, kann der Entwickler trotzdem die Standardeinstellung des Schlafmodus vorgeben. -Dies geschied einfach durch setzen der Eigenschaft sleepMode auf True in der Klasse des Anwendungsmoduls. - -### Beispiel 4: Ein Schlafmodus-Anwendungsmodul {#toc21} - -Der folgende Code kann kopiert und im Anwendungsmodul-Verzeichnis in einer Datei für eine Anwendung gespeichert werden, für die Sie den Schlafmodus aktivieren möchten. -Die Datei muss, wie immer, die Endung .py erhalten. - - --- Beginn --- - import appModuleHandler - - class AppModule(appModuleHandler.AppModule): - - sleepMode = True - - --- Ende --- -### Eigene NVDA-Objektklassen angeben {#toc22} - -Um die Zugänglichkeit von anwendungen mit NVDA zu verbessern, ist das Definieren von eigenen NVDA-Objektklassen der effektivste Weg. -Dies erlaubt Ihnen, die gesamte für ein Steuerelement relevante Logik an einer einzigen Stelle zusammenzufassen, anstatt sie auf verschiedene Plugin-Ereignisse aufzuteilen. - -die definition einer eigenen Objektklasse erfolgt in zwei Schritten: - -* Definieren der NVDA-Objektklasse und deren Skripte, Ereignisse, Eigenschaften und Eingabemethoden-Zuweisungen -* NVDA mitteilen, dass diese Klasse in bestimmten Situationen zu verwenden ist, indem sie sie mit Hilfe der Methode "chooseNVDAObjectOverlayClasses" auf Plugin-Ebene einbinden. - -Wenn Sie eigene NVDA-Objektklassen definieren, haben Sie viele NVDA-Objekt-basisklassen zur Auswahl. -Diese Basisklassen enthalten die grundlegene Unterstützung von Betriebssystem- oder Zugänglichkeitsschnittstellen wie win32, MSAA oder Java Access Bridge. -Sie sollten in der benutzerdefinierten Objektklasse üblicherweise die höchste Basisklasse erben. -Wenn Sie beispielsweise eine benutzerdefinierte Fensterklasse bei einem Steuerelement verwenden wollen, dessen Fensterklasse "edit" ist und dessen Steuerelement-ID 15 ist, werden Sie vermutlich von der Klasse "NVDAObjects.Window.Window" erben wollen, weil es sich bei dem besagten Objekt um ein Fenster handelt. -so ähnlich werden Sie Ihr Objekt von der Klasse "NVDAObjects.IAccessible.IAccessible" ableiten, wenn Sie nach der Eigenschaft "accrole" suchen wollen. -Außerdem sollten Sie genau wissen, welche Eigenschaften Sie bei Ihrer benutzerdefinierten Klasse überschreiben wollen. -Wenn Sie beispielsweise eine iAccessible-spezifische Eigenschaft wie "shouldAllowIAccessibleFocusEvent" überschreiben wollen, müssen Sie Ihr Objekt von "NVDAObjects.IAccessible.IAccessible" ableiten. - -Die Methode "chooseNVDAObjectOverlayClasses" kann in Anwendungsmodulen oder globalen Plugins eingesetzt werden. -Dabei verarbeitet sie drei Argumente: - -1. self: Die Instanz des anwendungsmoduls oder des globalen Plugins. -1. obj: Das Objekt, für das eine neue Klasse ausgewählt werden soll. -1. clsList: Eine Python-Liste mit Klassen, die für das Objekt benutzt werden sollen. - -Innerhalb dieser Methode sollten Sie entscheiden, welche benutzerdefinierten Objektklasse(n) das objekt verwenden soll, indem Sie dessen Eigenschaften prüfen. -Wenn eine benutzerdefinierte Klasse verwendet werden soll, können Sie sie in die Klassenliste (üblicherweise vorn) einfügen. Sie können auch von NVDA ausgewählte Klassen aus der Liste entfernen, dies ist jedoch selten erforderlich. - -### Beispiel 5: Das Eingabefeld im Editor beschriften, welches ein eigenes NVDA-Objekt verwendet {#toc23} - -Dieses Anwendungsmodul bringt NVDA dazu, das Haupt-eingabefeld des Editors mit "Inhalt" zu benennen. -Das bedeutet, dass NVDA "Inhalt Eingabefeld" sagen wird, sobald das Editorfenster den Fokus erhält. - -Der folgende Code kann kopiert und in eine Textdatei eingefügt werden, welche den Namen notepad.py tragen muss und im Ordner AppModules gespeichert wird. - - --- Beginn --- - 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 = "Inhalt" - - --- Ende --- -## Verpacken von Code als NVDA-Erweiterungen {#toc24} - -Um das Verteilen und die Installation von Plug-ins und Treibern zu erleichtern, können diese in einzelne Paketdateien verpackt werden, die dann mit Hilfe der Funktion "Erweiterungen verwalten" installiert werden können. Diese Funktion ist im Menü "Extras" zu finden. -Erweiterungspakete werden nur von NVDA 2012.2 und neuer unterstützt. -Ein Paket ist einfach eine Datei im Zip-Format mit der Erweiterung .nvda-addon, die folgende Dateien und Verzeichnisse enthalten kann: - -* Eine Manifest-Datei mit grundlegenden Informationen über das Paket. -* Ordner mit Plugins und Treibern, die in NVDA installiert werden sollen. -* Zusätzlichen Code, der bei der Installation bzw. der Deinstallation des Pakets ausgeführt werden soll. -* Übersetzungen der in Ihren Plugins und Treibern verwendeten Meldungen für unterschiedliche Srachräume. - -++ Nicht-ASCII-Dateinamen in Zip-Archiven ++ -wenn Ihr Archiv Dateien enthält, in deren Namen Zeichen vorkommen, die nicht zum Ascii-Zeichensatz gehören, muss das Archiv so erstellt werden, dass die Dateinamen utf-8-codiert werden. -Dies ermöglicht ein Entpacken des Archivs unabhängig davon, für welche Sprache das Zielsystem ausgelegt ist. -Unglücklicherweise unterstützen viele Archivierungsprogramme (einschließlch Windows-Explorer) diese Methode nicht. -Generell mss die utf8-Codierung von Datinamen asdrücklich aktiviert werden, auch wenn das Archivierungsprogramm dies von hause aus unterstützt. -In [http://www.7-zip.org/](7-Zip) können Sie die utf-8-Codierung von Dateinamen beispielsweise durch Angabe des Parameters "cu=on" beim Erstellen des Archivs einschalten. - -++ Manifest-Dateien ++ -Jedes Paket muss eine Manifest-Datei namens "manifest.ini" enthalten. -Diese Datei enthält Zeilen der Form "Name = Wert", die grundlegende Informationen über ein Paket bereitstellen wie z. B. den Namen, den Autor oder eine kurze Beschreibung. -Die Datei muss im UTF-8 kodiert sein. - -+++ Verfügbare Felder +++ -Auch wenn empfohlen wird, alle Felder auszufüllen, müssen lediglich diejenigen Felder Daten enthalten, die in der nachfolgenden Übersicht als Pflichtfelder markiert sind. -Anderenfalls wird das Paket nicht installiert. -* name: Ein kurzer eindeutiger Name für die Erweiterung, dieser wird benutzt, um die Erweiterungen intern voneinander zu unterscheiden (Pflichtfeld). -* summary: Eine kurze Beschreibung des Pakets im Telegrammstil, dies wird dem Anwender als Name angezeigt (Pflichtfeld). -* version: Die Version der Erweiterung z. B. 2.0 (Pflichtfeld). -* author: Der Autor des Pakets, vorzugsweise in der Form "Voller Name " (Pflichtfeld) -* description: Eine längere Beschreibung über den Sinn und Zweck der Erweiterung. -* url: Eine Internetadresse, unter der die Erweiterung, weitere Informationen oder Aktualisierungen zu finden sind. - -#### Beispiel für eine Manifest-Datei {#toc25} - --- start --- - name = mentestpaket - summary = Coole Erweiterung zum Testen - version = 1.0 - description = Eine Beispielerweiterung die zeigt, wie Erweiterungen erstellt werden - author = Michael Curran - url = http://www.nvda-project.org/wiki/Development - --- end --- -### Plugins und Treiber {#toc26} - -Die folgenden Plugins und Treiber können in einer Erweiterung enthalten sein: - -* Anwendungsmodule: Diese müssen in einem Ordner namens "appModules" innerhalb des Archivs liegen. -* Braillezeilentreiber: Diese müssen in einem Ordner namens "brailleDisplayDrivers" innerhalb des Archivs liegen. -* globale Plug-ins: Diese müssen in einem Ordner namens "globalPlugins" innerhalb des archivs liegen. -* Treiber für Sprachausgaben: Diese müssen in einem Ordner namens "synthDrivers" innerhalb des Archivs liegen. - -### Zusätzlicher Code zur Installation / deinstallation {#toc27} - -Falls Sie während der Installation oder der Deinstallation des Pakets zusätzlichen Code ausführen möchten, um z. B. Lizenzinformationen zu prüfen oder Dateien an einen benutzerdefinierten Ort zu kopieren, können Sie in ihrem Paket eine Datei namens installTasks.py bereitstellen, die spezielle Funktionen enthält. Diese Funktionen werden immer dann aufgerufen, wenn die Erweiterung installiert/deinstalliert wird. -Sie sollten unbedingt das unnötige Laden von Modulen vermeiden (Insbesondere Python-C-Erweiterungen oder dlls ihrer eigenen Erweiterung), weil dies sonst die Deinstalation des Pakets verhindern könnte. -Sollte dies jedoch vorkommen, so wird das Verzeichnis der Erweiterung umbenannt und erst beim nächsten Start von NVDA gelöscht. - -#### Die Funktion onInstall {#toc28} - -Nachdem die Dateien der Erweiterung aus dem Paket entpackt und in NVDA integriert wurden, wird NVDA die Datei installtasks.py nach einer Funktion namens onInstall durchsuchen und diese ausführen. -Auch wenn die Erweiterung zu diesem Zeitpunkt bereits entpackt wurde, besitzt das Verzeichnis immer noch den Namenszusatz .pendinginstall. Dieser wird erst nach einem Neustart von NVDA entfernt und die Erweiterung wird zum ersten Mal geladen. -Wenn die Funktion einen Ausnahmefehler auslöst, wird die Installation abgebrochen und das Verzeichnis gelöscht. - -#### Die Funktion onUninstall {#toc29} - -Wenn NVDA nach der Deinstallation eines Pakets neu gestartet wird, wird die Datei InstallTasks.py nach einer Funktion onUninstall durchsucht und diese ausgeführt. -Wurde diese Funktion erfolgreich ausgeführt, wird das Verzeichnis der Erweiterung automatisch entfernt. -Da dies zu einem Zeitpunkt geschieht, noch bevor andere Komponenten von NVDA geladen wurden, kann die funktion keinerlei Eingaben vom Benutzer entgegennehmen. - -### Erweiterungen lokalisieren {#toc30} - -Sie können für Ihre Erweiterung sprachspezifische Informationen hinterlegen. -Diese werden im Ordner "locale" innerhalb des Archivs gespeichert. -Der Ordner sollte Unterordner für jeden Sprachraum enthalten, für den Sie Meldungen hinterlegen wollen. Hierbei muss dasselbe Namensformat benutzt werden, wie bei den Kernkomponenten von NVDA so z. B. "en" für Englisch oder "de" für deutsch. - -#### Sprachspezifische Manifest-Dateien {#toc31} - -Jedes Sprachenverzeichnis kann eine sprachspezifische Manifest.ini enthalten, die einige der oben beschriebenen Manifest-Felder in übersetzter Form bereitstellt. -Dies sind die Felder Summary und Description. -Alle anderen Felder werden ignoriert. - -#### Sprachspezifische Meldungen {#toc32} - -Jedes sprachverzeichnis kann auch GetText-kompatible Kataloge mit Übersetzungen von Meldungen enthalten. -Wie bei den NVDA-Kernkomponenten auch, sollten Sie die Meldungsdatei in kompilierter Form unter dem Namen "nvda.mo" im Unterverzeichnis LC_MESSAGES des Sprachenverzeichnisses ablegen. -Um Ihren Plugins zu erlauben, mittels der Funktion _() auf GetText-Katalogdateien zuzugreifen, müssen Sie die Übersetzung am Beginn eines jeden Python-Moduls initialisieren. Rufen Sie hierzu die Funktion addonHandler.initTranslations() auf. -Weitere Informationen über gettext und allgemeine Informationen über die Übersetzung von NVDA finden Sie in folgendem Artikel: -http://www.nvda-project.org/wiki/TranslatingNVDA - -## Die Python-Konsole von NVDA {#toc33} - -Die Python-Konsole emuliert innerhalb von NVDA den interaktiven Python-Interpreter. -Sie ist zur Fehlerbehebung oder zum Erkunden von NVDA's Interna oder zum Erkunden von Zugänglichkeitsschnittstellen nützlich. - -### Verwendung {#toc34} - -Die Konsole kann auf zwei Arten aktiviert werden: - -* Durch Drücken von NVDA+Steuerung+Z. -Wenn Sie die Konsole auf diese Art aktivieren, werden Informationen über den Zustand von NVDA in Variablen gespeichert, die über die Konsole verfügbar sind. -Lesen Sie den Abschnitt zu [Schnappschuss-Variablen](#PythonConsoleSnapshotVariables) für weitere Informationen. -* Durch Aufrufen des Befehls Extras --> Python-Konsole aus dem NVDA-Menü. - -Die Konsole ähnelt dem Standard-Python-Interpreter. -Die Eingabe wird zeilenweise abgearbeitet. -Die aktuelle Zeile wird durch Drücken von Eingabe abgearbeitet. -Mit den Pfeiltasten können Sie durch die Ausgaben von ausgeführten Befehlen navigieren. - -Die ausgabe des Befehls wird beim Drücken von Eingabe vorgelesen. -Mit F6 können Sie zwischen Ein- und Ausgabefenster wechseln. - -durch Schließen des Fensters wird die Sitzung lediglich verborgen. Dies macht es möglich, zur Konsole zurückzukehren und alle bisherigen Eingaben und Variablen beizubehalten - -### Namensraum {#PythonConsoleNamespace} -#### Automatische Importe {#toc36} - -Der Einfachheit halber werden die folgenden Module und Variablen automatisch importiert: -sys, os, wx, log (aus logHandler), api, queueHandler, speech, braille - -#### Schnappschuss-Variablen {#PythonConsoleSnapshotVariables} - -Wann immer NVDA+Steuerung+Z gedrückt wird, werden einige Variablen gesetzt, die eine Momentaufnahme von NVDA darstellen. -Diese Variablen sind: - -* focus: Das Objekt, welches momentan den Fokus besitzt. -* focusAnc: Die Vorfahren des aktuell fokussierten Objekts. -* fdl: Ebenen der Fokusunterschiede. -* fg: Das aktuelle Vordergrundfenster. -* nav: Das aktuelle Navigatorobjekt. -* mouse: Das Objekt, auf dem sich der Mauszeiger befindet. -* brlRegions: Die Braille-Regionen des aktiven Braille-Puffers. - -## Die Remote-Python-Konsole {#toc38} - -Für Situationen, in denen Fehler in NVDA über ein Netzwerk hinweg aus der Ferne korrigiert werden müssen, ist eine Remote-Python-Konsole verfügbar. -Diese funktioniert ähnlich wie die weiter oben beschrieben [lokale Python-Konsole](#PythonConsole), der Zugriff erfolgt jedoch über TCP. - -Bitte bedenken Sie, dass dies ein hohes Sicherheitsrisiko darstellt! -Sie sollten die Remote-Python-Konsole nur dann aktivieren, wenn Sie mit vertrauenswürdigen Netzwerken wie etwa VPNs verbunden sind. - -### Verwendung {#toc39} - -Um die Remote-Python-Konsole zu aktivieren, verwenden Sie die lokale Python-Konsole und importieren Sie remotePythonConsole. Rufen Sie anschließend remotePythonConsole.initialize() auf. -Jetzt können Verbindungen über den typ-Port 6832 aufgebaut werden. -Die Eingabeaufzeichnungsliste für zuvor eingegebene Befehle wird nicht unterstützt. -Der Namensbereich ist identisch mit dem [Namensbereich der lokalen Python-Konsole](#PythonConsoleNamespace). - -Es gibt jedoch einige weitere spezielle Funktionen: - -* snap(): Erstellt einen Schnappschuss des aktuellen Zustands von NVDA und speichert diesen in den [Schnappschuss-Variablen](#PythonConsoleSnapshotVariables). -* rmSnap(): Entfernt alle Schnappschuss-Variablen. - -Ende des Dokuments. - diff --git a/user_docs/pt_BR/developerGuide.md b/user_docs/pt_BR/developerGuide.md deleted file mode 100644 index 318ac5cf57c..00000000000 --- a/user_docs/pt_BR/developerGuide.md +++ /dev/null @@ -1,574 +0,0 @@ -# Guia do Desenvolvedor do NVDA NVDA_VERSION - -[TOC] - -Nota; Alguns termos deverão ser mantidos em Inglês por referirem-se a programação e Jargões Técnicos - - - -## Introdução {#toc2} - -Esse manual proporciona informações concernentes ao desenvolvimento do NVDA, incluindo tradução e o desenvolvimento de componentes para este programa. - -### Uma Nota Sobre Python {#toc3} - -O NVDA e seus componentes são escritos primariamente na linguagem de programação Python. -Não é o objetivo deste manual ensiná-lo sobre python, ainda que exemplos sejam fornecidos ao longo deste documento para ajudá-lo a familiarizar-se com a sintaxe desta linguagen. -Documentação e outros recursos relacionados com python podem ser encontrados no cite [[www.python.org/](http://www.python.org/)]. - -## Tradução {#toc4} - -Para suportar muitos idiomas/localizações, o NVDA deve ser traduzido e devem ser fornecidos dados específicos para a localização. - -### Descrições de Caracteres {#toc5} - -Algumas vezes, é muito difícil ou mesmo impossível distinguir um caractere de outro. -Por exemplo, dois caracteres podem ser pronunciados da mesma forma, embora sejam caracteres diferentes. -Para ajudar aos usuários quando isso ocorre, podem ser fornecidas descrições de caracteres que descrevem o caractere de uma única forma. - -Descrições de caracteres podem ser fornecidas para uma localização em um um arquivo denominado characterDescriptions.dic na pasta desta localização. -Este é um arquivo de texto codificado em UTF-8. -Linhas em branco ou iniciadas por cardinal "#" são ignoradas. -Todas as outras linhas devem conter um caractere seguido de um tab, e em seguida uma ou mais descrições separadas por tab. - -Por exemplo: - - # Esse é um Comentário - a alfa - b bravo - -Veja o arquivo locale\pt_BR\characterDescriptions.dic para um exemplo completo. - -### Pronúncia de Sinais {#toc6} - -É bastante útil ouvir a pontuação e outros sinais pronunciados como palavras quando lemos textos, particularmente ao movermo-nos por caracteres. -Infelizmente, a pronúncia de sinais é inconsistente entre sintetizadores de voz e muitos sintetizadores não falam vários sinais e/ou não permitem controlar que sinais serão falados. -Por isso, o NVDA oferece informações sobre pronúncia de sinais a ser fornecida. - -Isso é feito para uma localização, fornecendo um arquivo denominado symbols.dic em sua pasta. -Esse é um arquivo de texto codificado em UTF-8. -Linhas em branco ou iniciadas por cardinal "#" são ignoradas. -Todas as localizações inerentemente herdam a informação do sinal para Inglês, embora qualquer dessas informações possam ser substituidas. - -O arquivo contém duas seções. - -#### Definindo Sinais Complexos {#toc7} - -A primeira seção é opcional e define expressões regulares originais para sinais complexos. -Sinais complexos são sinais que não são simplesmente um caractere ou seqüência de caracteres, mas em lugar disso necessitam de uma combinação mais complicada. -Um exemplo disso é a parada completa (.) fim de sentença em português. -O ponto "." é usado para muitos propósitos, então uma checagem mais complicada é necessária para determinar se esse se refere ao fim de uma sentença. - -A seção de sinais complexos inicia-se com a linha: - - complexSymbols: - -As linhas seguintes contêm um identificador textual usado para identificar o sinal, um tab e a expressão regular original para aquele sinal. -Por exemplo: - - . sentence ending (?<=[^\s.])\.(?=[\"')\s]|$) - -Repetindo, os sinais em inglês são herdados por todas as outras localizações, de modo que você não precisa incluir qualquer sinal complexo já definido para Inglês. - -#### Definindo Informações de Sinais {#toc8} - -A segunda seção proporciona informações sobre quando e como pronunciar sinais. -Ela inicia-se com a linha: - - symbols: - -As linhas seguintes devem conter vários campos separados por tab. -Os únicos campos obrigatórios são o do identificador e substituto. -O padrão será usado para campos omitidos. -Os campos são os seguintes: - -* identificador: O identificador do sinal. -Na maior parte dos casos, é apenas o caractere ou caracteres do sinal. -Todavia, ele pode também ser o identificador de um sinal complexo. -Certos caracteres não podem ser digitados dentro do arquivo, então as seguintes seqüências especiais podem ser usadas: -* \0: Null -* \t: Tab -* \n: fim de linha -* \r: Retorno -* \f: form feed -* \#: # caractere (necessário porque cardinal # no início de uma linha denota um comentário) -* substituto: O texto que deve ser falado para o sinal. -* grau: O grau de sinais no qual o sinal deve ser falado. -O grau de sinais é configurado pelo usuário e especifica a quantidade de sinais que deve ser falada. -Esse campo deve conter um dos graus "nada", "pouco", "muito", "tudo" ou "caractere", ou "-" usar o padrão. -"caractere" significa que o sinal só deve ser pronunciado ao mover-se por caractere. -O padrão é para herdar o valor ou "all" se nada existe para herdar. -* preservar: Se o próprio sinal deve ser preservado para facilitar a pronúncia correta pelo sintetizador. -Por exemplo, sinais que provocam pausas ou inflecção (tais como a vírgula em português) devem ser preservados. -Esse campo deve ser um dos seguintes: -* never: Nunca preservar o sinal. -* always: Sempre preservar o sinal. -* norep: Preservar o sinal apenas se ele não estiver sendo substituido; isto é, o usuário tiver ajustado o grau de sinais para um menor que o grau deste. -* -: Usar o padrão. - O padrão é para herdar o valor ou "never" se nada existe para herdar. - -Finalmente, um nome para exibição para o sinal pode ser fornecido num comentário depois de um tab ao final da linha. -Esse será mostrado aos usuários ao editar a informação do sinal e é útil especialmente para os tradutores definirem nomes traduzidos para sinais complexos oriúndos do inglês. - -Aqui vão alguns exemplos: - - ( abre parêntese most - -Isso significa que o caractere "(" deve ser falado como "abre parêntese" apenas quando o grau de sinais estiver ajustado para muito ou superior; isto é, muito ou tudo. - - , vírgula all always - -Isso significa que o caractere "," deve ser falado como "vírgula" quando o grau de sinais estiver ajustado para "tudo" e que o próprio caractere sempre deve ser preservado de modo que o sintetizador efetue a pausa apropriadamente. - - . sentence ending point # . fin de phrase - -Essa linha aparece no arquivo symbols.dic em francês. -Isso significa que ". finais de sentença" sinais complexos devem ser falados como "point". -O grau e o modo de preservação não são especificados, pois serão tomados do Inglês. -Um nome para amostra é fornecido de modo que os usuários franceses conhecerão o que o sinal representa. - -Por favor consulte o arquivo locale\pt_Br\symbols.dic para as definições que são herdadas do Inglês para todas as localizações. -Esse também é um bom exemplo completo. - -## Plugins {#toc9} -### Resumo {#toc10} - -Plugins lhe permitem personalizar a forma de o NVDA comportar-se em geral ou dentro de um aplicativo em particular. -Eles são capazes de: - -* Responder a eventos em particular como mudanças no foco ou em propriedades dos objetos; isto é, quando um controle altera seu nome. -* Implementar comandos que estão vinculados ao pressionamento de teclas em particular ou outras entradas. -* Personalizar o comportamento e implementar funcionalidades adicionais para controles em particular. -* Personalizar ou adicionar novo suporte para conteúdo de texto e documentos complexos. - -Essa seção proporciona uma introdução para o desenvolvimento de plugins. -Os desenvolvedores devem consultar a documentação do código para uma referência completa. - -### Tipos de Plugins {#toc11} - -Existem dois tipos de plugins. eles são: - -* App Modules: códigos específicos para um aplicativo em particular. -Um App Module recebe todos os eventos para um aplicativo em particular, mesmo qe este não esteja atualmente ativo. -Quando o aplicativo está ativo, qualquer comando a que o App Module esteja vinculado pelo pressionamento de teclas ou outras entradas pode ser executado pelo usuário. -* Global Plugins: Códigos globais para o NVDA, ou seja, é usado em todos os aplicativos. -Global Plugins recebem todos os eventos para todos os controles no sistema operacional -Quaisquer comandos vinculados a Global Plugins podem ser executados pelo usuário onde ele estiver no sistema operacional, indiferente do aplicativo. - -Se você quizer melhorar o acesso do NVDA para um aplicativo em particular, é muito provável que você pretenderá escrever um App Module. -Contrariamente, caso queira adicionar alguma funcionalidade ao NVDA em geral (tal como um script para anunciar a velocidade da conecção de internet atual estando em qualquer aplicativo), então um Global Plugin éo que você deseja. - -Tanto App Modules como Global Plugins compartilham um aspecto comum. -Ambos são arquivos em código Python (com a extensão .py), ambos definem uma classe especial contendo todos os eventos, scripts e vínculos, e podem definir classes personalizadas para acessar controles, conteúdos de texto e documentos complexos. -Todavia, eles diferenciam-se de algumas formas. - -As seguintes seções falarão separadamente sobre App Modules e Global Plugins. -Depois deste ponto, a discussão voltará a ser geral. - -### Básicas sobre um App Module {#toc12} - -Arquivos de App Modules têm a extensão .py, e tem o mesmo nome do principal executável do aplicativo para o qual você desejará que seja usado. -Por exemplo, um App Module para o notepad deverá ser denominado notepad.py, visto que o principal executável do notepad chama-se notepad.exe. - -Arquivos de App Modules devem ser armazenados na sub-pasta appModules da pasta de configurações do usuÁrio do NVDA. -Para mais informações sobre onde encontrar a pasta de configurações do usuário, por favor consulte o Guia do Usuário do NVDA. - -Os App Modules devem definir uma classe denominada AppModule, que herda do appModuleHandler.AppModule. -Essa classe pode então definir eventos e métodos de scripts, gestos de vínculos e outros códigos. -Isso tudo será explicado profundamente mais tarde. - -O NVDA carrega um App Module para um aplicativo logo que identifica que o mesmo está sendo executado. -O App Module é descarregado logo que o aplicativo é fechado ou quando o NVDA é encerrado. - -### Exemplo 1: Um App Module para Bipar em Eventos de Mudanças no Foco {#Example1} - -O exemplo seguinte de App Module faz com que o NVDA reproduza um beep cada vez que o foco muda dentro do aplicativo notepad. -Esse exemplo lhe mostra o esquema básico de um App Module. - -Copie e cole o código (mas sem incluir) os marcadores inicial e final para um novo arquivo de texto denominado notepad.py, que deve ser salvo na sub-pasta AppModules. -Seja bastante cuidadoso para manter todos os tabs e espaços intactos. - -Uma vez salvo no local correto, reinicie o NVDA ou selecione Recarregar Plugins localizado em Ferramentas no menu do NVDA. - -Finalmente, abra o Notepad e mova o foco pelo aplicativo; isto é, mova-o ao longo da barra de menus, abra alguma caixa de diálogo, etc. -Você deve ouvir beeps a cada vez que o foco mudar. -Note que se você se mover para uma instância fora do Notepad, para o Windows Explorer - você não ouvirá beeps. - - --- 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 --- - -Esse arquivo de App Module inicia-se com duas linhas de comentário, que descrevem para que o arquivo serve. - -Ele então importa o módulo appModuleHandler, de modo que o o App Module então possa ter acesso à classe base do AppModule. - -Em seguida, ele define uma classe denominada AppModule, que é herdada do appModuleHandler.AppModule. - -Dentro dessa classe, ele define 1 ou mais eventos, scripts ou gestos vinculados. -Nesse exemplo, ele define 1 método de evento para gainFocus events (event_gainFocus), que reproduz um pequeno beep cada vez que é executado. -A implementação desse evento não é importante para o propósito desse exemplo. -A parte mais important é a própria classe. -Eventos serão explicados com mais detalhes noutro momento. - -Como com outros exemplos nesse manual, lembramos que ao apagar o app module criado ao terminar o teste depois reiniciar o NVDA ou recarregar os plugins, então a funcionalidade original será restaurada. - -### Básicos sobre Global Plugins {#toc14} - -Arquivos de Global Plugins tem a extensão .py, e devem ter um único e curto nome que identifica o que ele faz. - -Arquivos de Global Plugins devem ser armazenados na sub-pasta globalPlugins da pasta de configurações do usuário do NVDA. -Para mais informações sobre onde encontrar a pasta de configurações do usuário, por favor consulte o Guia do Usuário do NVDA. - -Global Plugins devem definir uma classe denominada GlobalPlugin, que herda do globalPluginHandler.GlobalPlugin. -Essa classe pode então definir eventos e métodos de scripts, gestos vinculados e outros códigos. -Isso tudo será explicado de forma mais profunda posteriormente. - -O NVDA carrega todos os global plugins logo que é iniciado, e os descarrega ao encerrar. - -### Exemplo 2: Um Global Plugin que Proporciona um Script Para Anunciar a Versão do NVDA {#toc15} - -O exemplo seguinte de Global Plugin lhe permite pressionar NVDA+shift+v em qualquer lugar do sistema operacional para saber a informação da versão do NVDA. -Esse exemplo serve apenas para lhe mostrar o esquema básico de um Global Plugin. - -Copie e cole o código (sem incluir) os marcadores de início e fim para um novo arquivo de texto com o nome de exemplo2.py, que deve ser salvo na sub-pasta globalPlugins. -Seja bastante cuidadoso para manter todos os tabs e espaços intactos. - -Uma vez salvo no lugar correto, então reinicie o NVDA ou selecione Recarregar Plugins localizado em ferramentas no menu do NVDA. - -DE qualquer parte, você agora poderá pressionar NVDA+shift+v para ter a versão do NVDA falado e exibido em braille. - - --- start --- - # Version announcement plugin 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 --- - -Esse arquivo de Global Plugin inicia-se com duas linhas de comentário, que descrevem para que serve o arquivo. - -Ele então importa o módulo globalPluginHandler, de modo que o Global Plugin tenha acesso à classe base do GlobalPlugin. - -Ele também importa alguns outros módulos, nomeadamente ui e versionInfo, que esse plugin específico precisa para realizar as ações necessárias para anunciar a versão. - -Em seguida, ele define uma classe denominada GlobalPlugin, que é herdada do globalPluginHandler.GlobalPlugin. - -Dentro dessa classe, ele define 1 ou mais eventos, scripts ou gestos vinculados. -Nesse exemplo, ele define um método de script que proporciona o anúncio da version, e fornece um vínculo a partir de NVDA+shift+v para esse script. -Todavia, os detalhes do script e seus vínculos não são importantes para o propósito desse exemplo. -A parte mais importante é a própria classe. - -Como com outros exemplos nesse manual, lembramos que ao apagar o Global Plugin criado ao terminar o teste depois reiniciar o NVDA ou recarregar os plugins, então a funcionalidade original será restaurada. - -### Objetos no NVDA {#toc16} - -O NVDA representa controles e outros GUI elementos como seus Objetos. -Esses Objetos do NVDA contêm propriedades standardisadas, tais como nome, função, valor, estados e descrição, que permitem a outras partes do NVDA consultar ou apresentar informações sobre um controle de uma forma generalizada. -Por exemplo, o botão OK num diálogo pode ser representado como um Objeto do NVDA com o nome de "OK" e a função de botão. -Semelhantemente, uma caixa de seleção com a etiqueta de "Eu Concordo" pode ter o nome de "Eu concordo", a função de caixa de seleção, e se atualmente estiver marcada, o estado de marcada. - -As there are many differents GUI Toolkits and platform and accessibility APIs, NVDA Objects abstract these differences into a standard form that NVDA can use, regardless of the toolkit or API a particular control is made with. -For example, the Ok button, just discussed could be a widget in a Java application, an MSAA object, an IAccessible2 object or a UI Automation element. - -Os Objetos no NVDA possuem muitas propriedades. -Algumas das mais úteis são: - -* name: a etiqueta do controle. -* role: one of the ROLE_* constants from NVDA's controlTypes module. -Botão, diálogo, texto editável, janela e caixa de seleção são exemplos de funções. -* states: a set of 0 or more of the STATE_* constants from NVDA's controlTypes module. -Enfocável, enfocado, selecionado, selecionável, expandido, recolhido e marcado são alguns exemplos de estados. -* value: o valor do controle; isto é, a porcentagem de uma barra de deslocamento ou a configuração atual de uma caixa de combinação. -* description: uma sentença ou duas descrevendo o que o controle faz (normalmente, o mesmo que sua dica de ferramenta). -* location: the object's left, top, width and height positions in screen coordinates. -* parent: this object's parent object. -For example, a list item object's parent would be the list containing it. -* next: the object directly after this one on the same level in logical order. -For example, a menu item NVDA Object's next object is most likely another menu item within the same menu. -* previous: like next but in reverse. -* firstChild: the first direct child object of this object. -For example, a list's first child would be the first list item. -* lastChild: the last direct child of this object. - * children: a list of all the direct children of this object; e.g. all the menu items in a menu. -- - -There are also a few simplified navigation properties such as simpleParent, simpleNext, simpleFirstChild and simpleLastChild. -These are like their respective navigation properties described above, but NVDA filters out unuseful objects. -These properties are used when NVDA's simple review mode is turned on, which is the default. -These simple properties may be easier to use, but the real navigation properties more closely reflect the underlying Operating System structure. - -When developing plugins, most of the time, it is not important what toolkit or API backs an NVDA Object, as the plugin will usually only access standard properties such as name, role and value. -However, as plugins become more advanced, it is certainly possible to delve deeper into NVDA Objects to find out toolkit or API specific information if required. - -Plugins make use of NVDA Objects in three particular ways: -* Most events that plugins receive take an argument which is the NVDA Object on which the event occurred. -For example, event_gainFocus takes the NVDA Object that represents the control gaining focus. -* Scripts, events or other code may fetch objects of interest such as the NVDA Object with focus, NVDA's current navigator object, or perhaps the Desktop NVDA Object. -The code may then retreave information from that object or perhaps even retreave another object related to it (e.g. its parent, first child, etc.). -* the Plugin may define its own custom NVDA Object classes which will be used to wrap a specific control to give it extra functionality, mutate its properties, etc. - -Just like App Modules and Global Plugins, NVDA Objects can also define events, scripts and gesture bindings. - -### Scripts e Gestos Vinculados {#toc17} - -App Modules, Global Plugins e Objetos no NVDA podem definir métodos especiais que podem ser vinculados a uma parte de uma entrada tal como o pressionamento de uma tecla. -O NVDA identifica esses métodos como scripts. - -A script is a standard Python instance method with a name starting with "script_"; e.g. "script_sayDateTime". - -A script method takes two arguments: - -* self: a reference to the App Module, Global Plugin or NVDA Object instance the script was called on. -* gesture: an Input Gesture object, which represents the input that caused the script to run. - -As well as the actual script method, some form of gesture binding must be defined, so that NVDA knows what input should execute the script. - -To bind a gesture to a script, a special "__gestures" Python dictionary can be defined as a class variable on the App Module, Global Plugin or NVDA Object. -These dictionaries should contain gesture identifier strings pointing to the name of the requested script, without the "script_" prefix. - -There are more advanced ways of binding gestures in a more dynamic fashion, though the __gestures dictionary is the simplest. - -A gesture identifier string is a simple string representation of a piece of input. -It consists of a two leter character code denoting the source of the input, an optional device in brackets, a colon (:) and one or more names separated by a plus (+) denoting the actual keys or input values. - -Alguns exemplos de seqüências de identificadores de gesto são: - -* "kb:NVDA+shift+v" -* "br(freedomScientific):leftWizWheelUp" -* "kb(laptop):NVDA+t" - -Atualmente, os únicos códigos de entrada no NVDA são: - -* kb: entrada de teclado -* br: entrada de braille - -When NVDA receives input, it looks for a matching gesture binding in a particular order. -Once a gesture binding is found, the script is executed and no further bindings are used, nore is that particular gesture passed on automatically to the Operating System. - -The order for gesture binding lookup is: - -* Loaded Global Plugins -* App Module of the active application -* Tree Interceptor of the NVDA Object with focus if any; e.g. a virtualBuffer -* NVDA Object with focus -* Global Commands (built in commands like quitting NVDA, object navigation commands, etc.) - -### Exemplo 3: Um Global Plugin para Obter a Classe da Janela e a Identificação do Controle {#toc18} - -O Global Plugin a seguir lhe permite pressionar NVDA+seta a esquerda para obter o anúncio da classe da janela atualmente em foco, e NVDA+seta a direita para obter o anúncio da identificação do controle atualmente em foco. -Esse exemplo lhe mostra como definir um ou mais scripts e gestos vinculados numa classe tal como um App Module, Global Plugin o objeto do NVDA. - -Copie e cole o código (sem incluir) os marcadores de início e fim para um novo arquivo de texto com o nome de exemplo3.py, que deve ser salvo na sub-pasta globalPlugins. -Seja bastante cuidadoso para manter todos os tabs e espaços intactos. - -Uma vez salvo no lugar correto, então reinicie o NVDA ou selecione Recarregar Plugins localizado em ferramentas no menu do 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 --- -### Eventos {#toc19} - -When NVDA detects particular toolkit, API or Operating System events, it abstracts these and fires its own internal events on plugins and NVDA Objects. - -Although most events are related to a specific NVDA Object (e.g. name change, gain focus, state change, etc.), these events can be handled at various levels. -When an event is handled, it is stopped from going further down the chain. -However, code inside the event can choose to propagate it further if needed. - -The order of levels through which the event passes until an event method is found is: - -* Loaded Global Plugins -* The App Module associated with the NVDA Object on which the event was fired -* The Tree Interceptor (if any) associated with the NVDAObject on which the event was fired -* the NVDAObject itself. - -Events are Python instance methods, with a name starting with "event_" followed by the actual name of the event (e.g. gainFocus). - -These event methods take slightly different arguments depending at what level they are defined. - -If an event for an NVDA Object is defined on an NVDA Object itself, the method only takes one mandatory argument which is the 'self' argument; i.e. the NVDA Object instance). -Some events may take extra arguments, though this is quite rare. - -If an event for an NVDA Object is defined on a Global Plugin, App Module or Tree Interceptor, the event takes the following arguments: - -* self: the instance of the Global Plugin, App Module or Tree Interceptor -* obj: the NVDA Object on which the event was fired -* nextHandler: a function that when called will propagate the event further down the chain. - -Some common NVDA Object events are: - -* foreground: this NVDA Object has become the new foreground object; i.e. active top-level object -* gainFocus -* loseFocus -* nameChange -* valueChange -* stateChange -* caret: when the caret (insertion point) within this NVDA Object moves -* locationChange: physical screen location changes - -Existem muitos outros eventos, mas os listados acima são habitualmente os mais úteis. - -Para um exemplo de um evento controlado por um App Module, por favor reveja o [exemplo 1](#Example1) (beeps para o foco no notepad). - -### A variável SleepMode dos App Modules {#toc20} - -Os App Modules possuem uma propriedade bastante útil denominada "sleepMode" (modo dormir), que se ajustada para "true" desabilitam quase que por completo o NVDA dentro daquele aplicativo. -O Modo Dormir é muito útil para aplicativos com voz própria que tenham funcionalidade de leitura de tela, ou mesmo possíveis jogos que necesssitam do uso do teclado completo. - -Ainda que o Modo Dormir possa ser alternado entre ligado e desligado pelo usuário com o comando de teclado NVDA+shift+s, um desenvolvedor pode escolher tê-lo ativado por padrão para um determinado aplicativo. -Isso é feito fornecendo-se um App Module para esse aplicativo que simplesmente ajusta sleepMode para True na classe AppModule. - -### Exemplo 4: Um App Module para ativar Modo Dormir {#toc21} - -O código a seguir pode ser copiado e colado num arquivo de texto, depois salvo na pasta appModules com o nome do aplicativo para o qual você desejar ativar o modo dormir. -Como sempre, o arquivo deve ter a extensão .py. - - --- start --- - import appModuleHandler - - class AppModule(appModuleHandler.AppModule): - - sleepMode = True - - --- end --- -### Proporcionando Classes personalizadas para Objetos do NVDA {#toc22} - -Providing custom NVDA Object classes is probably the most powerful and useful way to improve the experience of an application in an NVDA plugin. -This method allows you to place all the needed logic for a particular control altogether in one NVDA Object class for that control, rather than scattering code for many controls across a plugin's events. - -There are two steps to providing a custom NVDA Object class: - -* Define the NVDA Object class and its events, scripts, gesture bindings and overridden properties. -* Tell NVDA to use this NVDA Object class in specific situations by handling it in the plugin's chooseNVDAObjectOverlayClasses method. - -When defining a custom NVDAObject class, you have many NVDAObject base classes to choose from. -These base classes contain the base support for the particular accessibility or OS API underlying the control, such as win32, MSAA or Java access Bridge. -You should usually inherit your custom NVDAObject class from the highest base class you need in order to choose your class in the first place. -For example, if you choose to use your custom NVDAObject class when the window class name is "Edit" and the window control ID is 15, you should probably inherit from NVDAObjects.window.Window, as clearly you are aware that this is a Window object. -Similarly, if you match on MSAA's accRole property, you would probably need to inherit from NVDAObjects.IAccessible.IAccessible. -You should also consider what properties you are going to override on the custom NVDA Object. -For instance, if you are going to override an IAccessible specific property, such as shouldAllowIAccessibleFocusEvent, then you need to inherit from NVDAObjects.IAccessible.IAccessible. - -the chooseNVDAObjectOverlayClasses method can be implemented on app modules or global plugin classes. -It takes 3 arguments: - -1. self: the app module or global plugin instance. -1. obj: the NVDAObject for which classes are being chosen. -1. clsList: a Python list of NVDAObject classes that will be used for obj. - -Inside this method, you should decide which custom NVDA Object class(es) (if any) this NVDA Object should use by checking its properties, etc. -If a custom class should be used, it must be inserted into the class list, usually at the beginning. -You can also remove classes chosen by NVDA from the class list, although this is rarely required. - -### Exemplo 5: Etiquetando os Campos de Edição do Notepad usando a Personalização de Objeto do NVDA {#toc23} - -Esse app module para o notepad faz com que o NVDA anuncie os principais campos de edição do Notepad como tendo um nome de "conteúdo". -Feito isto, quando este receber foco, o NVDA dirá "Edição de Conteúdo". - -O código a seguir pode ser copiado e colado em um arquivo de texto, depois salvo na pasta appModules com o nome de 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 --- -## O Console Python do NVDA {#toc24} - - O console pyhton do NVDA emula o interpretador Python interativo de dentro do NVDA. -Essa é uma ferramenta de desenvolvimento que é muito útil para depuração, inspeção geral interna do NVDA ou inspeção da hierarquia de acessibilidade de um aplicativo. - -### uso {#toc25} - -O console pode ser ativado de duas formas: - -* Pressionando NVDA+control+z. -Quando ativado dessa forma, um snapshot do atual estado do NVDA referente ao momento em que a tecla foi presionada será tomado e salvo em certas variáveis disponíveis no console. -Consulte [ Variáveis Snapshot](#PythonConsoleSnapshotVariables) para mais detalhes. -* Selecionando Ferramentas -> Console Python a partir do menu NVDA na barra do sistema. - -O console é semelhante ao interpretador Python standard interativo. -A entrada é aceita de uma linha por vez. -A linha atual é processada quando enter é pressionado. -Você pode navegar pelo históryco das linhas introduzidas anteriormente usando as setas para cima e para baixo. - -Saídas (respostas vindas do interpretador) são anunciadas quando enter é pressionado. -A tecla f6 alterna entre os controles de entrada e saída. - -Encerrando a janela do console simplesmente o oculta. -Isso permite que o usuário retorne à seção como foi deixada ao ser encerrada, incluindo o histórico e as variáveis. - -### Namespace {#toc26} -#### Importações Automáticas {#toc27} - -Por conveniência, os seguintes módulos e variáveis são importados automaticamente no console: -sys, os, wx, log (from logHandler), api, queueHandler, speech, braille - -#### Snapshot Variables {#PythonConsoleSnapshotVariables} - -Sempre que o comando NVDA+control+z é pressionado, certas variáveis disponíveis no console são atribuidas de acordo com o estado atual do NVDA. -Essas variáveis são: - -* focus: O objeto atualmente em foco -* focusAnc: O objeto ascendente ao atualmente em foco -* fdl: Diferença de Níveis no foco ; isto é, o nível ao qual o ascendente do atual e o atual objeto em foco diferenciam-se -* fg: O objeto atualmente em primeiro plano -* nav: O objeto de navegação atual -* mouse: O objeto atualmente sob o mouse -* brlRegions: As regiões de braille do buffer braille ativo -