• R/O
  • SSH
  • HTTPS

nvdajp: Commit


Commit MetaInfo

Revision97 (tree)
Zeit2014-01-05 22:30:25
Autornishimoto

Log Message

added devDocs.ja.po

Ändern Zusammenfassung

Diff

--- sandbox/website/devDocs/devDocs.ja.po (nonexistent)
+++ sandbox/website/devDocs/devDocs.ja.po (revision 97)
@@ -0,0 +1,1734 @@
1+# SOME DESCRIPTIVE TITLE
2+# Copyright (C) YEAR Free Software Foundation, Inc.
3+# This file is distributed under the same license as the PACKAGE package.
4+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
5+#
6+#, fuzzy
7+msgid ""
8+msgstr ""
9+"Project-Id-Version: PACKAGE VERSION\n"
10+"POT-Creation-Date: 2013-12-14 22:15+0000\n"
11+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13+"Language-Team: LANGUAGE <LL@li.org>\n"
14+"Language: \n"
15+"MIME-Version: 1.0\n"
16+"Content-Type: text/plain; charset=UTF-8\n"
17+"Content-Transfer-Encoding: 8bit\n"
18+
19+#. type: Plain text
20+#, no-wrap
21+msgid "[[!meta title=\"NVDA Add-on Development Guide\"]]\n"
22+msgstr ""
23+
24+#. type: Plain text
25+msgid ""
26+"Welcome to NVDA add-on Development Guide. This is the one-stop guide on how "
27+"NvDA add-ons are developed, as well as explaining some useful code segments "
28+"from NvDA core source code useful when writing add-ons."
29+msgstr ""
30+
31+#. type: Plain text
32+msgid ""
33+"For more information on NVDA development, please visit [NvDA Community "
34+"Development page][1]. Be sure to go over [NVDA Developer Guide][2] to "
35+"familiarize yourself with key terms and basics on getting started with add-"
36+"on development."
37+msgstr ""
38+
39+#. type: Title ##
40+#, no-wrap
41+msgid "Audience"
42+msgstr ""
43+
44+#. type: Plain text
45+msgid ""
46+"This guide is designed for both beginners who are new to Python and/or NVDA "
47+"development in general, as well as experts and power users and programmers "
48+"who are familiar with Python or other programming languages and/or familiar "
49+"with NvDA source code structure."
50+msgstr ""
51+
52+#. type: Plain text
53+msgid ""
54+"If you are new to NVDA add-on or core development, we recommend that you get "
55+"to know Python first, as it gives necessary programming background for "
56+"understanding the rest of the guide. If you are a Python programmer but are "
57+"new to NvDA development, please checkout NVDA development Guide and Design "
58+"Overview document, both of which can be found on the NVDA Community website."
59+msgstr ""
60+
61+#. type: Title ###
62+#, no-wrap
63+msgid "Authors, contributions and copyright"
64+msgstr ""
65+
66+#. type: Plain text
67+msgid ""
68+"This guide was originally written by Joseph Lee and is shaped by NVDA user "
69+"and developer community. We welcome your feedback and contributionn."
70+msgstr ""
71+
72+#. type: Plain text
73+msgid ""
74+"Copyright: NVDA is copyright 2006-2013 NV Access. Microsoft Windows, "
75+"Microsoft Office, Win32 API and other MS products are copyright Microsoft "
76+"Corporation. IAccessible package is copyright IBM and Linux Foundation. "
77+"Python is copyright Python Foundation. Other products mentioned are "
78+"copyrighted by authors of these products."
79+msgstr ""
80+
81+#. type: Title ##
82+#, no-wrap
83+msgid "System requirements"
84+msgstr ""
85+
86+#. type: Plain text
87+msgid ""
88+"To create an add-on for NVDA, please make sure the following system "
89+"requirements are met:"
90+msgstr ""
91+
92+#. type: Bullet: '* '
93+msgid ""
94+"A version of NVDA is available on your computer (either a portable or "
95+"installed version will work, but we strongly recommend that you install a "
96+"copy of NVDA on your development computer)."
97+msgstr ""
98+
99+#. type: Bullet: '* '
100+msgid "Python 2.7 series, version 2.7.5 32-bit for Windows."
101+msgstr ""
102+
103+#. type: Bullet: '* '
104+msgid "SCons 2, version 2.3.0 for generating add-on packages."
105+msgstr ""
106+
107+#. type: Bullet: '* '
108+msgid "Markdown 2.0.1 or later for generating add-on documentation."
109+msgstr ""
110+
111+#. type: Bullet: '* '
112+msgid "GNU Gettext package for Windows for message localization support."
113+msgstr ""
114+
115+#. type: Bullet: '* '
116+msgid ""
117+"Git 1.7.9 or later if you wish to upload the add-on to a repository such as "
118+"Bitbucket (optional, see below). You can use various Git clients, such as "
119+"Git Bash, Cygwin's Git, Tortoise Git and so forth."
120+msgstr ""
121+
122+#. type: Bullet: '* '
123+msgid ""
124+"The NVDA Community Add-on template for ease of add-on file and folder "
125+"packaging and management (optional; [click here][3] to download the add-on "
126+"template)."
127+msgstr ""
128+
129+#. type: Bullet: '* '
130+msgid "Additional Python modules or dependencies for your add-on."
131+msgstr ""
132+
133+#. type: Title ##
134+#, no-wrap
135+msgid "What are add-ons?"
136+msgstr ""
137+
138+#. type: Plain text
139+msgid ""
140+"An add-on is an additional package that extends NvDA's functionality or "
141+"support for programs. This may include adding global features, enhancing "
142+"support for an application or adding support for newer braille displays or "
143+"speech synthesizers."
144+msgstr ""
145+
146+#. type: Plain text
147+msgid ""
148+"Currently, the following add-on modules are supported. Note that an add-on "
149+"may include more than one add-on modules such as a global plugin and a "
150+"speech synthesizer packaged into one add-on."
151+msgstr ""
152+
153+#. type: Bullet: '* '
154+msgid ""
155+"Global plugin: A global plugin adds features for NVDA which can be used "
156+"anywhere, such as OCR capability."
157+msgstr ""
158+
159+#. type: Bullet: '* '
160+msgid ""
161+"App module: An app module allows enhanced support for a program, such as "
162+"specific windows or controls of a program such as audio editors."
163+msgstr ""
164+
165+#. type: Bullet: '* '
166+msgid ""
167+"Driver: A driver allows a program to talk to hardware. Currently one can "
168+"write drivers for new braille displays or speech synthesizers."
169+msgstr ""
170+
171+#. type: Plain text
172+msgid ""
173+"Each NVDA add-on package (composed of one or more add-on modules) is a zip "
174+"file with the file extension of .nvda-addon. These can be installed via Add-"
175+"ons Manager, found in NvDA 2012.2 or later. Alternativley, one can install "
176+"them from file manager if one uses NVDA 2012.3 or later installed on the "
177+"computer."
178+msgstr ""
179+
180+#. type: Plain text
181+msgid ""
182+"Throughout this guide, we refer to standard NVDA modules which comes with "
183+"NVDA as \"NvDA Core\" to distinguish it from add-on modules."
184+msgstr ""
185+
186+#. type: Title ##
187+#, no-wrap
188+msgid "Setting up the add-on development environment"
189+msgstr ""
190+
191+#. type: Plain text
192+msgid "Follow these steps to prepare your computer for writing NVDA add-ons."
193+msgstr ""
194+
195+#. type: Title ###
196+#, no-wrap
197+msgid "Installing dependencies"
198+msgstr ""
199+
200+#. type: Bullet: '1. '
201+msgid ""
202+"If you don't have NVDA, download and install NVDA from NV access website."
203+msgstr ""
204+
205+#. type: Bullet: '2. '
206+msgid ""
207+"Install Python 2.7.x 32-bit on your computer (if using Windows, install "
208+"using the 32-bit Windows installer package)."
209+msgstr ""
210+
211+#. type: Bullet: '3. '
212+msgid "Install Markdown and SCons using their Windows installer packages."
213+msgstr ""
214+
215+#. type: Bullet: '4. '
216+msgid "If you plan to share your add-on code with others, install Git clients."
217+msgstr ""
218+
219+#. type: Bullet: '5. '
220+msgid ""
221+"Paste the Gettext executable files to your add-on development folder (see "
222+"the next section on add-on development folder)."
223+msgstr ""
224+
225+#. type: Bullet: '6. '
226+msgid ""
227+"If you are developing support for a program, speech synthesizer or a braille "
228+"display, install the needed software and/or have the hardware handy."
229+msgstr ""
230+
231+#. type: Title ###
232+#, no-wrap
233+msgid "The add-on development folder"
234+msgstr ""
235+
236+#. type: Plain text
237+msgid ""
238+"When writing add-ons, it is recommended that you store your add-on code in "
239+"separate folders, one per add-on. If you chose to download the add-on "
240+"template, the folder structure will be automatically created."
241+msgstr ""
242+
243+#. type: Plain text
244+msgid ""
245+"Once you install the needed dependencies (see above), paste the Gettext "
246+"package executables into this add-on folder."
247+msgstr ""
248+
249+#. type: Title ###
250+#, no-wrap
251+msgid "Add-on folder structure"
252+msgstr ""
253+
254+#. type: Plain text
255+msgid ""
256+"Each add-on folder, at a minimum, must contain the following files and "
257+"folders:"
258+msgstr ""
259+
260+#. type: Plain text
261+#, no-wrap
262+msgid ""
263+" * manifest.ini to store manifesst information such as add-on name and author.\n"
264+"* An \"addon\" subfolder with the add-on module directory underneath this subfolder (appModules, globalPlugins, synthDrivers, brailleDisplays). One or more module folders can be specified.\n"
265+msgstr ""
266+
267+#. type: Plain text
268+msgid ""
269+"If you are using the add-on template, the folder structure will "
270+"automatically be created, so you need to create only the addon subfolder and "
271+"the add-on module folder(s) and code inside this folder. See the readme file "
272+"in the template folder for more information on customizing your add-on "
273+"manifest using the template files."
274+msgstr ""
275+
276+#. type: Title ###
277+#, no-wrap
278+msgid "Packaging add-ons"
279+msgstr ""
280+
281+#. type: Plain text
282+msgid "There are two ways of packaging add-ons:"
283+msgstr ""
284+
285+#. type: Bullet: '1. '
286+msgid ""
287+"To package your add-on manually, zip up (compress) your add-on folder as a ."
288+"zip file, then rename the file extension to .nvda-addon."
289+msgstr ""
290+
291+#. type: Bullet: '2. '
292+msgid ""
293+"To use the add-on template with SCons, open Command Prompt with "
294+"administrator mode (Windows Vista or later), change to your add-on folder "
295+"and type `scons~."
296+msgstr ""
297+
298+#. type: Plain text
299+msgid ""
300+"For more information on add-on management, see the management chapter in "
301+"this guide."
302+msgstr ""
303+
304+#. type: Title ##
305+#, no-wrap
306+msgid "Getting started: Hands-on examples"
307+msgstr ""
308+
309+#. type: Plain text
310+msgid ""
311+"So are you ready to start your adventure with add-ons, but not sure as to "
312+"how to bring it to life? If that is you, please go through this chapter, as "
313+"it gives you basic information to get you started with add-ons and give you "
314+"tips on writing code."
315+msgstr ""
316+
317+#. type: Plain text
318+msgid ""
319+"Note: for this chapter, we will not use the actual add-on packages. Instead, "
320+"we'll use plugin folders - a number of subdirectories in your NVDA user "
321+"configuration folder (available from Start Menu/Screen if NVDA is installed) "
322+"to store our example Python files."
323+msgstr ""
324+
325+#. type: Plain text
326+msgid ""
327+"To edit .py files, you need a word processor which can handle .py files. The "
328+"best one we recommend is Notepad++."
329+msgstr ""
330+
331+#. type: Title ###
332+#, no-wrap
333+msgid "How add-on code is organized"
334+msgstr ""
335+
336+#. type: Plain text
337+#, no-wrap
338+msgid " Your add-on code is stored in one or more Python files (.py file). Despite different kinds of add-ons out there, they all have similar layout.\n"
339+msgstr ""
340+
341+#. type: Plain text
342+#, no-wrap
343+msgid " First, you start by writing an optional header for your add-on, such as your name, a brief sentence or two on what the add-on is for and so on. Although this is optional, it is recommend that you write the header as a reminder to keep track of what you are doing with your add-on.\n"
344+msgstr ""
345+
346+#. type: Plain text
347+#, no-wrap
348+msgid " Next, you tell NVDA the modules you need for your add-on file. This is done by writing `import module` where module is the name of the module you wish to use in your code. For example, if you want to hear tones while writing your add-on, write `import tones`. Typically you may need to import two or more modules for your specific add-on (see below on list of modules you need for the type of add-on module you are writing).\n"
349+msgstr ""
350+
351+#. type: Plain text
352+#, no-wrap
353+msgid " after declaring the modules you need or import, you write your add-on code (defining classes, variables, methods and so on). The most important section is the add-on class code, which will determine the type of add-on module your code will be assigned to.\n"
354+msgstr ""
355+
356+#. type: Plain text
357+#, no-wrap
358+msgid " For instance, if you wish to add support for a program, after importing appModuleHandler and other needed modules, you would write:\n"
359+msgstr ""
360+
361+#. type: Plain text
362+#, no-wrap
363+msgid " `class appModule(appModuleHandler.AppModule):`\n"
364+msgstr ""
365+
366+#. type: Plain text
367+msgid ""
368+"After that, all you are writing is Python code (see the Python documentation "
369+"on how to write Python programs)."
370+msgstr ""
371+
372+#. type: Title ###
373+#, no-wrap
374+msgid "Running your add-on in this example chapter"
375+msgstr ""
376+
377+#. type: Plain text
378+msgid ""
379+"To run your example add-ons from this chapter, open your NVDA user "
380+"configuration directory (from Start Menu/Screen, look for Explore NVDA user "
381+"configuration folder\" item). Then paste your .py file to the appropriate "
382+"folder: appModules folder for app module examples, and globalPlugins folder "
383+"for global plugins."
384+msgstr ""
385+
386+#. type: Title ###
387+#, no-wrap
388+msgid "Example 1: Hear a tone when pressing NVDA+A"
389+msgstr ""
390+
391+#. type: Plain text
392+msgid ""
393+"Let us start with a simple example: if you press NvDA+A, you would hear a "
394+"tone for 1 second from any program. Since we want to use this everywhere, it "
395+"must be a global plugin."
396+msgstr ""
397+
398+#. type: Plain text
399+msgid ""
400+"First, open your user configuration folder, then open globalPlugins folder. "
401+"Create a new .py file and give it a descriptive name such as example1.py (it "
402+"is strongly recommended that when you name your global plugin file, give it "
403+"a short descriptive name). Then open the newly created .py file in the word "
404+"processor."
405+msgstr ""
406+
407+#. type: Plain text
408+msgid ""
409+"The below code implements our example. Put this in your .py file as exactly "
410+"as shown:"
411+msgstr ""
412+
413+#. type: Plain text
414+#, no-wrap
415+msgid "\t# Add-on development first example\n"
416+msgstr ""
417+
418+#. type: Plain text
419+#, no-wrap
420+msgid ""
421+"\timport globalPluginHandler\n"
422+"\timport tones # We want to hear beeps.\n"
423+msgstr ""
424+
425+#. type: Plain text
426+#, no-wrap
427+msgid "\tclass GlobalPlugin(globalPluginHandler.GlobalPlugin):\n"
428+msgstr ""
429+
430+#. type: Plain text
431+#, no-wrap
432+msgid ""
433+"\t\tdef script_doBeep(self, gesture):\n"
434+"\t\t\ttones.beep(440, 1000) # Beep a standard middle A for 1 second.\n"
435+msgstr ""
436+
437+#. type: Plain text
438+#, no-wrap
439+msgid ""
440+"\t\t__gestures={\n"
441+"\t\t\t\"kb:NVDA+A\":\"doBeep\"\n"
442+"\t\t}\n"
443+msgstr ""
444+
445+#. type: Plain text
446+msgid ""
447+"In Python, you put comments by putting hash sign (#) at the start of the "
448+"comment line."
449+msgstr ""
450+
451+#. type: Title ###
452+#, no-wrap
453+msgid "Example 1 code explanation"
454+msgstr ""
455+
456+#. type: Plain text
457+msgid ""
458+"Our first example let's us sound a beep for one second when we press NVDA+A. "
459+"But you might be wondering what that above code means, so let's step through "
460+"the code, one piece at a time."
461+msgstr ""
462+
463+#. type: Bullet: '1. '
464+msgid ""
465+"At the top of the file, we wrote a header which tells us that this is an "
466+"example add-on."
467+msgstr ""
468+
469+#. type: Bullet: '2. '
470+msgid ""
471+"Since this is a global plugin, we need to import a crucial module: global "
472+"plugin handler, so we wrote `import globalPluginHandler`."
473+msgstr ""
474+
475+#. type: Bullet: '3. '
476+msgid ""
477+"Then we wrote `import tones` to import (load, or include) the tones module, "
478+"a built-in module from NVDA. Whenever you wish to use a method from a given "
479+"module, import the needed module(s)."
480+msgstr ""
481+
482+#. type: Bullet: '4. '
483+msgid ""
484+"Next, we defined a class called GlobalPlugin. The text inside the brackets "
485+"tells us where this class is coming from (more on this concept in a second). "
486+"A class, in programming, describes an object, such as a person, a desk, a "
487+"program and others."
488+msgstr ""
489+
490+#. type: Bullet: '5. '
491+msgid ""
492+"Inside the class, we wrote a method (function) called `script_doBeep`. This "
493+"is an example of a script, a method that'll be run or executed when you "
494+"press a command. Inside this script, we wrote `tones.beep(440, 1000)` to "
495+"tell NVDA to sound a middle A tone for 1 second. In programming, a function "
496+"can take arguments, or a set or parameters which tells the function what to "
497+"do based on the given values (we'll meet them later). In fact, many methods "
498+"you'll be writing, including our doBeep script takes one or more arguments. "
499+"More on scripts later as we journey through the guide."
500+msgstr ""
501+
502+#. type: Bullet: '6. '
503+msgid ""
504+"Lastly, we wrote a simple dictionary (a collection) to store our command "
505+"(script) bindings for our doBeep script. Here, we told NVDA to assign NVDA+A "
506+"command for doBeep script."
507+msgstr ""
508+
509+#. type: Plain text
510+msgid ""
511+"Save this file, then restart NVDA. Now whenever you press NvDA+A, you'll "
512+"hear a middle A tone for 1 second. Once you are comfortable with the add-on "
513+"code and how it is laid out, you can delete the newly created .py file."
514+msgstr ""
515+
516+#. type: Title ###
517+#, no-wrap
518+msgid "I don't understand those above terms"
519+msgstr ""
520+
521+#. type: Plain text
522+msgid ""
523+"For some, the terms \"class\", \"method\" and so on might be new. Let's go "
524+"over what these terms are, as they are fundamental for add-on development:"
525+msgstr ""
526+
527+#. type: Bullet: '* '
528+msgid ""
529+"Class: a class describes an object. It could describe anything, such as a "
530+"person, a desk, an NVDA add-on and others. Classes are fundamental to NVDA "
531+"and other programs - in fact, a number of programmers are skilled at coming "
532+"up with classes."
533+msgstr ""
534+
535+#. type: Bullet: '* '
536+msgid ""
537+"Method: A method is a short program or a routine that a program runs for "
538+"doing something, such as generating tones, calculating huge numbers, loading "
539+"NVDA add-ons and so on. Some people call them \"functions.\""
540+msgstr ""
541+
542+#. type: Bullet: '* '
543+msgid ""
544+"Script: A script is a method which runs when the user performs commands such "
545+"as pressing certain keys on a keyboard. For example, when you press NVDA"
546+"+F12, NVDA runs dateTime script, located in one of the NVDA core modules "
547+"named Global Commands. A script takes two arguments: where the script would "
548+"be executed (usually \"self\"; more on that later) and the gesture for the "
549+"script (see below)."
550+msgstr ""
551+
552+#. type: Bullet: '* '
553+msgid ""
554+"Variable: A variable is something that can change, such as name of a person, "
555+"name of the NVDA add-on we're running, version of NVDA you are using and so "
556+"on. An add-on file may define one or more variables (for example, to store "
557+"common constants such as strings)."
558+msgstr ""
559+
560+#. type: Bullet: '* '
561+msgid ""
562+"Module: A module is a collection of methods and variables in a file. When we "
563+"write add-ons, we are in fact writing additional modules that NVDA can use "
564+"while it is running."
565+msgstr ""
566+
567+#. type: Plain text
568+msgid "There are other terms that we'll get to know shortly."
569+msgstr ""
570+
571+#. type: Title ###
572+#, no-wrap
573+msgid "Example 2: Generate a tone when switching to Notepad"
574+msgstr ""
575+
576+#. type: Plain text
577+msgid "Most of the below code comes from NvDA Developer Guide."
578+msgstr ""
579+
580+#. type: Plain text
581+msgid ""
582+"Not only NVDA let's you add global commands, but it also allows writing code "
583+"to enhance usage of programs through app modules. An app module is also a "
584+"Python file except that, this time, the name of the .py file is the name of "
585+"the executable for a program. For example, an app module for Notepad would "
586+"be named notepad.py."
587+msgstr ""
588+
589+#. type: Plain text
590+msgid ""
591+"The below code, from NVDA developer Guide, gives a short example of a "
592+"typical app module: play a short beep when switching to Notepad. Put the "
593+"below code in notepad.py, which in turn should be placed in appModules "
594+"folder in your user configuration folder in order for it to run."
595+msgstr ""
596+
597+#. type: Plain text
598+#, no-wrap
599+msgid "\t# An example app module.\n"
600+msgstr ""
601+
602+#. type: Plain text
603+#, no-wrap
604+msgid ""
605+"\timport appModuleHandler\n"
606+"\timport tones\n"
607+msgstr ""
608+
609+#. type: Plain text
610+#, no-wrap
611+msgid "\tclass AppModule(appModuleHandler.AppModule):\n"
612+msgstr ""
613+
614+#. type: Plain text
615+#, no-wrap
616+msgid ""
617+"\t\tdef event_gainFocus(self, obj, nextHandler):\n"
618+"\t\t\ttones.beep(256, 200)\n"
619+"\t\t\tnextHandler()\n"
620+msgstr ""
621+
622+#. type: Title ###
623+#, no-wrap
624+msgid "Example 2 code explanation"
625+msgstr ""
626+
627+#. type: Plain text
628+msgid ""
629+"We're seeing more new code here. Let's go over this, again piece by piece:"
630+msgstr ""
631+
632+#. type: Bullet: '1. '
633+msgid ""
634+"Unlike the first example, the crucial module we need is appModuleHandler."
635+msgstr ""
636+
637+#. type: Bullet: '2. '
638+msgid "The class that we are using is AppModule."
639+msgstr ""
640+
641+#. type: Bullet: '3. '
642+msgid ""
643+"Unlike last time, we're using events, a method run when certain events occur "
644+"such as when names of controls change. Events take an object as one of its "
645+"arguments, the object for which the event needs to be dealt with, or, as "
646+"many people say, \"fired.\""
647+msgstr ""
648+
649+#. type: Bullet: '4. '
650+msgid ""
651+"Inside the event method, we're also seeing a call to `nextHandler`. This "
652+"method is used in event methods to tell NvDA to pass the event so it can be "
653+"taken care of, such as saying the name of a control after beeping."
654+msgstr ""
655+
656+#. type: Title ###
657+#, no-wrap
658+msgid "More new terms please"
659+msgstr ""
660+
661+#. type: Plain text
662+msgid "Other terms you may see include:"
663+msgstr ""
664+
665+#. type: Bullet: '* '
666+msgid ""
667+"Event: An event is a method that'll be run when some events happen, such as "
668+"when a program is on focused, when names of controls change and so on."
669+msgstr ""
670+
671+#. type: Bullet: '* '
672+msgid ""
673+"Call: We say a function calls some another method when we run the second "
674+"method from another method. For example, in our first example, we're calling "
675+"tones.beep method from our script method."
676+msgstr ""
677+
678+#. type: Bullet: '* '
679+msgid ""
680+"Object: An object is an instance of a class - that is, a class coming to "
681+"life when a program runs. Throughout your add-ons, as you write classes and "
682+"when you run your add-ons, your classes come to life as objects, commonly "
683+"abbreviated to obj. In NVDA, an object may refer to controls or parts of a "
684+"program."
685+msgstr ""
686+
687+#. type: Bullet: '* '
688+msgid ""
689+"Self: In Python, the word \"self\" means current class (if we're defining "
690+"one, such as when writing add-ons), or means the class for which a method is "
691+"defined. For example, in a class called numbers, the add method would have "
692+"self as the first argument, reminding us that add method is part of the "
693+"class of numbers. In NVDA development world, self usually means the current "
694+"NVDA object (see below), or in the add-on development, the instance of an "
695+"add-on. Many of your methods will have self as the first argument."
696+msgstr ""
697+
698+#. type: Plain text
699+msgid ""
700+"Just like example 1, once you're comfortable with app module code, you may "
701+"wish to delete the Notepad app module code unless you want to keep hearing "
702+"beeps when you switch to Notepad. The actual differences between global "
703+"plugins and app modules will become more clear when we talk about them in "
704+"more detail throughout this guide."
705+msgstr ""
706+
707+#. type: Title ###
708+#, no-wrap
709+msgid "A few tips for beginners"
710+msgstr ""
711+
712+#. type: Plain text
713+msgid "Here are a few useful tips passed on by add-on writers:"
714+msgstr ""
715+
716+#. type: Bullet: '* '
717+msgid "Start with easy add-ons, such as saying a message, tones and so on."
718+msgstr ""
719+
720+#. type: Bullet: '* '
721+msgid "Write and test one method at a time."
722+msgstr ""
723+
724+#. type: Bullet: '* '
725+msgid ""
726+"If you are writing app modules or drivers, become familiar with programs, "
727+"synthesizers or braille displays you wish to support (e.g. read "
728+"documentation, try using them, etc.)."
729+msgstr ""
730+
731+#. type: Bullet: '* '
732+msgid ""
733+"When defining commands (especially in global plugins), consult commands used "
734+"in NvDA and other add-ons first before assigning a new command in your add-"
735+"on to avoid command conflicts."
736+msgstr ""
737+
738+#. type: Title ##
739+#, no-wrap
740+msgid "Useful modules from NVDA core"
741+msgstr ""
742+
743+#. type: Plain text
744+msgid ""
745+"Throughout the life of add-on development, you'll come across some useful "
746+"modules from NvDA core that would be helpful in your add-on code. This "
747+"section explains them and some functions in those modules that would be "
748+"useful."
749+msgstr ""
750+
751+#. type: Title ###
752+#, no-wrap
753+msgid "List of useful NVDA core modules and methods"
754+msgstr ""
755+
756+#. type: Plain text
757+msgid ""
758+"The following lists available NVDA core modules and some useful methods "
759+"found in those modules:"
760+msgstr ""
761+
762+#. type: Bullet: '* '
763+msgid ""
764+"Addon Handler (addonHandler.py): The module which implements the add-on "
765+"subsystem. The addonHandler.initTranslation() method is used to initialize "
766+"internationalization support for your add-on."
767+msgstr ""
768+
769+#. type: Bullet: '* '
770+msgid ""
771+"NVDA basic API (api.py): A collection of core methods used throughout NVDA, "
772+"such as obtaining focus and navigator object, setting focus and so on. See "
773+"the next list on useful methods from this module."
774+msgstr ""
775+
776+#. type: Bullet: '* '
777+msgid ""
778+"App Module subsystem (appModuleHandler.py, appModules): The subsystem in "
779+"charge of handling app modules (see chapter on app modules for more "
780+"information)."
781+msgstr ""
782+
783+#. type: Bullet: '* '
784+msgid ""
785+"ARIA support (aria.py): Implements support for Accessible Rich Internet "
786+"Applications (ARIA)."
787+msgstr ""
788+
789+#. type: Bullet: '* '
790+msgid ""
791+"Base object collection (baseObject.py): Contains useful base objects such as "
792+"scriptable objects (see the chapter on NvDA objects and overlay objects for "
793+"more information)."
794+msgstr ""
795+
796+#. type: Bullet: '* '
797+msgid ""
798+"Braille input and output subsystem (braille.py, brailleInput.py): Controls "
799+"braille output to and input from braille displays, needed by braille display "
800+"driver add-ons."
801+msgstr ""
802+
803+#. type: Bullet: '* '
804+msgid ""
805+"Build-in modules (builtin.py): Allows access to builtin modules when working "
806+"with add-ons."
807+msgstr ""
808+
809+#. type: Bullet: '* '
810+msgid ""
811+"Configuration (config): Manages configuration and profiles (profiles are "
812+"available in 2013.3 or later)."
813+msgstr ""
814+
815+#. type: Bullet: '* '
816+msgid ""
817+"Controls and states collection (controltypes.py): Includes dictionaries on "
818+"control types (roles) and possible states that a control can be in."
819+msgstr ""
820+
821+#. type: Bullet: '* '
822+msgid "Events (eventHandler.py): Handles various events such as gaining focus."
823+msgstr ""
824+
825+#. type: Bullet: '* '
826+msgid ""
827+"Global Commands collection (globalCommands.py): A list of global commands "
828+"available while using NVDA (see section on script scope for more "
829+"information)."
830+msgstr ""
831+
832+#. type: Bullet: '* '
833+msgid ""
834+"Global Plugin subsystem (globalPluginHandler.py): The module needed for "
835+"controlling global plugins."
836+msgstr ""
837+
838+#. type: Bullet: '* '
839+msgid ""
840+"NVDA GUI (gui): A collection of classes used by NVDA to display its messages "
841+"graphically. Includes GUI's for NVDA menu, add-on manager and others."
842+msgstr ""
843+
844+#. type: Bullet: '* '
845+msgid ""
846+"Hardware port utilities (hwPortUtils.py): A set of utilities for "
847+"communicating over serial and other hardware ports, useful during driver add-"
848+"on development."
849+msgstr ""
850+
851+#. type: Bullet: '* '
852+msgid ""
853+"IAccessible support (IAccessibleHandler.py, IAccessible objects): Used for "
854+"supporting IAccessible controls."
855+msgstr ""
856+
857+#. type: Bullet: '* '
858+msgid "Input management (inputCore.py): Manages input from the user."
859+msgstr ""
860+
861+#. type: Bullet: '* '
862+msgid ""
863+"Java Access Bridge support (JABHandler.py): A collection of methods used for "
864+"supporting JAB subsystem used for Java applications."
865+msgstr ""
866+
867+#. type: Bullet: '* '
868+msgid ""
869+"Keyboard input (keyboardHandler.py): Supports entering commands from the "
870+"keyboard."
871+msgstr ""
872+
873+#. type: Bullet: '* '
874+msgid ""
875+"Logging facility (logHandler.py): Allows a module to write logs to be viewed "
876+"by a developer or a user via Log Viewer."
877+msgstr ""
878+
879+#. type: Bullet: '* '
880+msgid "Mouse support (mouseHandler.py): Supports mouse commands."
881+msgstr ""
882+
883+#. type: Bullet: '* '
884+msgid ""
885+"NvDA objects collection (NVDAObjects): A collection of NvDA objects or "
886+"controls used in many applications and standards such as UIA (User Interface "
887+"Automation)."
888+msgstr ""
889+
890+#. type: Bullet: '* '
891+msgid ""
892+"Scripts support (scriptHandler.py): Handles scripts, methods executed due to "
893+"the user pressing keyboard commands and other input."
894+msgstr ""
895+
896+#. type: Bullet: '* '
897+msgid "Speech output (speech.py): Controls speech output."
898+msgstr ""
899+
900+#. type: Bullet: '* '
901+msgid ""
902+"Synthesizer driver support (synthDriverHandler.py): This is the core module "
903+"needed for speech synthesizer add-ons."
904+msgstr ""
905+
906+#. type: Bullet: '* '
907+msgid ""
908+"Widget text access (textInfos): Allows access to text for widget and "
909+"documents."
910+msgstr ""
911+
912+#. type: Bullet: '* '
913+msgid ""
914+"Touchscreen support (touchHandler.py): Provides support for touchscreen "
915+"input (installed versions only)."
916+msgstr ""
917+
918+#. type: Bullet: '* '
919+msgid "Tone output (tones.py): Allows the user to hear tones."
920+msgstr ""
921+
922+#. type: Bullet: '* '
923+msgid ""
924+"User interface messages (ui.py): Includes ui.message method used to speak or "
925+"braille certain text."
926+msgstr ""
927+
928+#. type: Bullet: '* '
929+msgid ""
930+"Virtual buffers (virtualBuffers): Handles virtual buffer documents such as "
931+"websites."
932+msgstr ""
933+
934+#. type: Plain text
935+msgid ""
936+"The modules without .py extension are directories, containing specialist "
937+"modules."
938+msgstr ""
939+
940+#. type: Title ###
941+#, no-wrap
942+msgid "Useful methods"
943+msgstr ""
944+
945+#. type: Plain text
946+msgid ""
947+"Here is a list of some useful methods used in add-ons. For more information "
948+"on how they're implemented, see the NvDA source code documentation. For "
949+"worked out examples, see the section of this guide on add-on components."
950+msgstr ""
951+
952+#. type: Plain text
953+msgid "From addonHandler:"
954+msgstr ""
955+
956+#. type: Bullet: '* '
957+msgid ""
958+"`addonHandler.initTranslation()`: Sets up the translation subsystem for add-"
959+"ons via Gettext."
960+msgstr ""
961+
962+#. type: Plain text
963+msgid "From api.py:"
964+msgstr ""
965+
966+#. type: Bullet: '* '
967+msgid ""
968+"`api.getFocusObject()`: Retrieves the focused control (returns the object "
969+"with focus)."
970+msgstr ""
971+
972+#. type: Bullet: '* '
973+msgid ""
974+"`api.getNavigatorObject()`: Fetches the current navigator object. If NvDA is "
975+"set to follow system focus, the focus and navigator object will be the same, "
976+"otherwise a different object is returned."
977+msgstr ""
978+
979+#. type: Bullet: '* '
980+msgid ""
981+"`api.getForegroundObject()`: Returns the foreground window of the current "
982+"application (the parent of this object is the application itself)."
983+msgstr ""
984+
985+#. type: Bullet: '* '
986+msgid ""
987+"These have a corresponding method to set certain object as the focus or "
988+"navigator object."
989+msgstr ""
990+
991+#. type: Plain text
992+msgid "From logHandler:"
993+msgstr ""
994+
995+#. type: Bullet: '* '
996+msgid "`logHandler.Log`: The class which implements logging facility."
997+msgstr ""
998+
999+#. type: Plain text
1000+msgid "From tones:"
1001+msgstr ""
1002+
1003+#. type: Bullet: '* '
1004+msgid ""
1005+"`tones.beep(pitch in hertz, duration in milliseconds, left channel volume, "
1006+"right channel volume)`: Plays a tone of specified pitch for specified "
1007+"duration. The first two arguments are mandatory, while the other two are "
1008+"optional."
1009+msgstr ""
1010+
1011+#. type: Plain text
1012+msgid "From ui:"
1013+msgstr ""
1014+
1015+#. type: Bullet: '* '
1016+msgid ""
1017+"`ui.message(message to be spoken/brailled)`: Speaks or brailles the message. "
1018+"This should be a string surrounded by quotes."
1019+msgstr ""
1020+
1021+#. type: Plain text
1022+msgid ""
1023+"There are other useful methods out there, but the above are the most useful "
1024+"ones. See the NVDA source code documentation for other methods, or see the "
1025+"examples below on how these methods and others are used throughout the life "
1026+"of an add-on."
1027+msgstr ""
1028+
1029+#. type: Title ##
1030+#, no-wrap
1031+msgid "Add-on module components and development tips"
1032+msgstr ""
1033+
1034+#. type: Plain text
1035+msgid ""
1036+"An add-on module consists of a number of components. This includes handling "
1037+"input and output, working with different NvDA objects, reacting to events, "
1038+"storing configuration and more."
1039+msgstr ""
1040+
1041+#. type: Plain text
1042+msgid ""
1043+"This chapter introduces key components and concepts that are used in add-on "
1044+"development, such as NVDA objects, scripts, event handling and additional "
1045+"topics with examples."
1046+msgstr ""
1047+
1048+#. type: Plain text
1049+msgid ""
1050+"Note that the NVDA core development guide introduces the below concepts. "
1051+"This chapter is intended as an extension of that document. Consult the NVDA "
1052+"development guide for a brief introductions."
1053+msgstr ""
1054+
1055+#. type: Title ###
1056+#, no-wrap
1057+msgid "Working with objects on screen"
1058+msgstr ""
1059+
1060+#. type: Plain text
1061+msgid ""
1062+"An object is an instance of a class - that is, a class coming to life while "
1063+"a program is running. For example, if a class called button has been "
1064+"defined, the button on a screen is the object of this button class."
1065+msgstr ""
1066+
1067+#. type: Plain text
1068+msgid ""
1069+"In NVDA, an object is representation of a control or parts of a program. "
1070+"This includes buttons, check boxes, edit fields, toolbars, sliders and even "
1071+"the application window. These are organized into hierarchies, or parent-"
1072+"child relationship where an object may contain child objects - for example, "
1073+"a list object in Windows Explorer may contain one or more list items, and "
1074+"the parent of this list might be the Windows Explorer window. The object "
1075+"that you're examining right now is termed \"navigator object.\""
1076+msgstr ""
1077+
1078+#. type: Plain text
1079+msgid ""
1080+"The NVDA objects (or simply called objects) contains a number of useful "
1081+"properties or atributes. These include the object's name, its value "
1082+"(checked, text of the edit window, etc.), role (check box, window, embedded "
1083+"object, etc., location (screen coordinates) and more. NVDA objects also "
1084+"contain useful methods for manipulating them, such as changing the value of "
1085+"the object, reacting to events for the object (gains focus, value changed, "
1086+"etc.) and so on."
1087+msgstr ""
1088+
1089+#. type: Plain text
1090+msgid ""
1091+"In many situations, an NvDA object may belong to a class of related objects. "
1092+"For each object classes, NvDA provides ways of handling them. These classes "
1093+"include IAccessible, JAB, UIA and so forth. These classes and behaviors for "
1094+"each class of objects is defined in NVDAObjects directory in the NvDA source "
1095+"code, and to use them in your add-on, import the appropriate object class "
1096+"handler for the object you're using (e.g. if you're working with an "
1097+"IAccessible object, impore NVDAObjects.IAccessible.)."
1098+msgstr ""
1099+
1100+#. type: Plain text
1101+msgid ""
1102+"Two of these object classes merit special mention: virtual buffers and tree "
1103+"interceptors. A tree interceptor allows NvDA to work with a \"tree\" of "
1104+"objects as though they are just one object. A special case of tree "
1105+"interceptor is virtual buffer, which allows NVDA to work with complex "
1106+"documents such as PDF documents."
1107+msgstr ""
1108+
1109+#. type: Title ###
1110+#, no-wrap
1111+msgid "Examining object hierarchy"
1112+msgstr ""
1113+
1114+#. type: Plain text
1115+msgid ""
1116+"There are a number of ways which you can use to see the hierarchy of an "
1117+"object for a given program:"
1118+msgstr ""
1119+
1120+#. type: Bullet: '1. '
1121+msgid ""
1122+"Using object navigation commands (NvDA+Numpad 2/4/5/6/8) with simple review "
1123+"mode turned off."
1124+msgstr ""
1125+
1126+#. type: Bullet: '2. '
1127+msgid ""
1128+"Using Python Console, use obj.next/previous/parent/firstChild/lastChild "
1129+"attributes. If you want to see all available properties, from mPython "
1130+"Console, type dir(obj)."
1131+msgstr ""
1132+
1133+#. type: Plain text
1134+msgid ""
1135+"If you wish to see a more detailed description about the navigator object, "
1136+"while the navigator object is located at the object you're interested in, "
1137+"press NvDA+F1 to launch log viewer. The root of all objects in Windows is "
1138+"the desktop, or shell object."
1139+msgstr ""
1140+
1141+#. type: Title ###
1142+#, no-wrap
1143+msgid "Focus vs. navigator object"
1144+msgstr ""
1145+
1146+#. type: Plain text
1147+msgid ""
1148+"In your add-on, you might wish to work with various objects and manipulate "
1149+"them. These may include changing the focused object, synchronizing navigator "
1150+"and focus objects, changing the role of an object and so on."
1151+msgstr ""
1152+
1153+#. type: Plain text
1154+msgid ""
1155+"A focus object is the currently focused control. These are linked to "
1156+"keyboard focus - that is, it follows the highlighted control. In contrast, a "
1157+"navigator object is the object you're interested in. Since navigator objects "
1158+"can move anywhere, you can examine two objects at once: the focused object "
1159+"and the navigator object. For instance, you might be focused on an edit "
1160+"field while examining the title bar as the navigator object."
1161+msgstr ""
1162+
1163+#. type: Plain text
1164+msgid ""
1165+"In your add-on, to fetch the object with focus, write `someObj = api."
1166+"getFocusObject()`. The someObj can be named differently - the convention is "
1167+"to use the name \"obj\". To fetch the navigator object (which might be "
1168+"different from the focused object), use `obj = api.getNavigatorObject()`."
1169+msgstr ""
1170+
1171+#. type: Title ###
1172+#, no-wrap
1173+msgid "Other useful object-related goodies"
1174+msgstr ""
1175+
1176+#. type: Plain text
1177+msgid ""
1178+"Here are some other methods which works with NVDA objects, all located in "
1179+"api.py module:"
1180+msgstr ""
1181+
1182+#. type: Bullet: '* '
1183+msgid ""
1184+"If you wish to obtain the foreground object (useful if you wish to look at "
1185+"some child object of the foreground window), use `obj = api."
1186+"getForegroundObject()`."
1187+msgstr ""
1188+
1189+#. type: Bullet: '* '
1190+msgid ""
1191+"From Python Console, to see the number of child objects that an object "
1192+"contains (for instance, the children, or widgets of a foreground window), "
1193+"type `obj.childCount`. The value 0 means that there are no more child "
1194+"objects."
1195+msgstr ""
1196+
1197+#. type: Bullet: '* '
1198+msgid ""
1199+"To set some object as the new focus or navigator object, use `api."
1200+"setFocusObject(obj)` or `api.setNavigatorObject(obj)`."
1201+msgstr ""
1202+
1203+#. type: Bullet: '* '
1204+msgid ""
1205+"You can fetch various properties of an object by specifying obj.property "
1206+"where property is the attribute you wish to see (e.g. obj.value)."
1207+msgstr ""
1208+
1209+#. type: Title ###
1210+#, no-wrap
1211+msgid "Example 1: Finding the value of a slider in a program"
1212+msgstr ""
1213+
1214+#. type: Plain text
1215+msgid ""
1216+"Suppose you are asked by a user to give him the value of a slider in a "
1217+"program using an app module. After looking at the object hierarchy and other "
1218+"properties, you know that the toolbar is the last child of the foreground "
1219+"object."
1220+msgstr ""
1221+
1222+#. type: Plain text
1223+msgid "Here is the code to implement this feature:"
1224+msgstr ""
1225+
1226+#. type: Plain text
1227+#, no-wrap
1228+msgid "\t# Object example 1\n"
1229+msgstr ""
1230+
1231+#. type: Plain text
1232+#, no-wrap
1233+msgid ""
1234+"\timport api\n"
1235+"\timport appModuleHandler\n"
1236+msgstr ""
1237+
1238+#. type: Plain text
1239+#, no-wrap
1240+msgid "\t\tsliderChildIndex = -1 # The variable to store the child index.\n"
1241+msgstr ""
1242+
1243+#. type: Plain text
1244+#, no-wrap
1245+msgid ""
1246+"\t\tdef getSliderValue(self):\n"
1247+"\t\t\tfg = api.getForegroundObject()\n"
1248+"\t\t\tsliderVal = fg.children[self.sliderChildIndex].value\n"
1249+"\t\t\treturn sliderVal\n"
1250+msgstr ""
1251+
1252+#. type: Plain text
1253+msgid ""
1254+"In this code, the method `fg.children[index]` is used to retrieve the child "
1255+"with the given index (here, since we said the toolbar is the last child, the "
1256+"index would be minus 1, or the very last child; we could have used fg."
1257+"lastChild)."
1258+msgstr ""
1259+
1260+#. type: Plain text
1261+msgid ""
1262+"However, this code has an issue: what if the slider value is actually within "
1263+"the first child of the actual slider control? One way to fix this is to "
1264+"check the object's role. The modified code looks like this:"
1265+msgstr ""
1266+
1267+#. type: Plain text
1268+#, no-wrap
1269+msgid ""
1270+"\tdef getSliderValue(self):\n"
1271+"\t\tfrom controltypes import ROLE_SLIDER # It is possible to import from within a method.\n"
1272+"\t\tfg = api.getForegroundObject()\n"
1273+"\t\tslider = fg.lastChild\n"
1274+"\t\tif slider.role == ROLE_SLIDER: return slider.firstChild.value\n"
1275+msgstr ""
1276+
1277+#. type: Plain text
1278+msgid ""
1279+"Thus, when we know for sure that we're dealing with the slider, the method "
1280+"returns the value of the slider's first child (if that is the case). Note "
1281+"the two equals signs for equality, as opposed to just one equals sign for "
1282+"assignment."
1283+msgstr ""
1284+
1285+#. type: Plain text
1286+msgid ""
1287+"There are other examples you can try to familiarize yourself with object "
1288+"navigation and manipulation:"
1289+msgstr ""
1290+
1291+#. type: Bullet: '* '
1292+msgid ""
1293+"Obtaining the name of an object that is located somewhere else in the "
1294+"program."
1295+msgstr ""
1296+
1297+#. type: Bullet: '* '
1298+msgid "Moving the navigator to the foreground object."
1299+msgstr ""
1300+
1301+#. type: Bullet: '* '
1302+msgid "Setting focus to another program."
1303+msgstr ""
1304+
1305+#. type: Plain text
1306+msgid ""
1307+"For real-life examples on objects in NvDA, consult the NvDA source code or "
1308+"source codes of various community add-ons."
1309+msgstr ""
1310+
1311+#. type: Title ###
1312+#, no-wrap
1313+msgid "Specialist objects and overriding object properties at runtime"
1314+msgstr ""
1315+
1316+#. type: Plain text
1317+msgid ""
1318+"Sometimes, it is not enough to work with default behavior for a control. For "
1319+"example, some parts of a program may need custom gestures, or one may need "
1320+"to change the role of a window to that of a button."
1321+msgstr ""
1322+
1323+#. type: Plain text
1324+msgid ""
1325+"NVDA provides two methods for creating specialist, or overlay objects (or "
1326+"classes), each suited for different needs:"
1327+msgstr ""
1328+
1329+#. type: Bullet: '* '
1330+msgid ""
1331+"`event_NvDAObject_init(self, object we're dealing with)`: If you wish to "
1332+"override certain attributes of a control such as its role or label (name), "
1333+"you can use this method to ask NvDA to take your \"input\" to account when "
1334+"meeting objects for the first time (or initialized). For instance, if the "
1335+"control has the window class name of TForm (seen on many Delphi "
1336+"applications), you can ask NVDA to treat this control as a standard window "
1337+"by assigning obj.role = ROLE_WINDOW (see control types dictionary for list "
1338+"of available roles)."
1339+msgstr ""
1340+
1341+#. type: Bullet: '* '
1342+msgid ""
1343+"`chooseNVDAObjectOverlayClasses(self, object, list of classes)`: This allows "
1344+"NVDA to use your own logic when dealing with certain objects. For example, "
1345+"this is useful if you wish to assign custom gestures for certain parts of a "
1346+"program in your app module (in fact, many app modules creates objects to "
1347+"deal with certain parts of a program, then uses "
1348+"chooseNvDAObjectOverlayClasses to select the correct object when certain "
1349+"conditions are met). These custom objects must be based on a solid object "
1350+"that we wish to eeal with (mostly IAccessible is enough, thus most overlay "
1351+"objects inherit from, or is the child or specialist class of IAccessible "
1352+"objects)."
1353+msgstr ""
1354+
1355+#. type: Plain text
1356+msgid ""
1357+"Note that in case of the second method, the class(s) with the given name "
1358+"must be present in the file, which is/are inherited from a known base object "
1359+"(in Python, the syntax for the inheritence is `childClass(baseClass)`, and "
1360+"is usually read as, \"this child class inherits from this base class\". "
1361+"We'll see code like this later)."
1362+msgstr ""
1363+
1364+#. type: Title ###
1365+#, no-wrap
1366+msgid "Examples of overlay classes and modified roles"
1367+msgstr ""
1368+
1369+#. type: Plain text
1370+msgid ""
1371+"Below examples illustrate the uses of the two overlay and attribute "
1372+"modification methods we've discussed above:"
1373+msgstr ""
1374+
1375+#. type: Plain text
1376+msgid "An example of the first case: modifying an atribute."
1377+msgstr ""
1378+
1379+#. type: Plain text
1380+#, no-wrap
1381+msgid ""
1382+"\t# Reassign some Delphi forms as window.\n"
1383+"\t\tdef event_NvDAObject_init(self, obj):\n"
1384+"\t\t\tif obj.windowClassName == \"TForm\": obj.role = ROLE_WINDOW\n"
1385+msgstr ""
1386+
1387+#. type: Plain text
1388+msgid ""
1389+"This means that whenever we encounter a window with the class name of \"TForm"
1390+"\", NvDA will treat this as a normal window."
1391+msgstr ""
1392+
1393+#. type: Plain text
1394+msgid ""
1395+"Example 2 deals with an app module which has two objects for dealing with "
1396+"specific parts of a program, then uses chooseNVDAObjectOverlayClasses to "
1397+"assign the logic for each control."
1398+msgstr ""
1399+
1400+#. type: Plain text
1401+#, no-wrap
1402+msgid "\t#An example of overlay classes\n"
1403+msgstr ""
1404+
1405+#. type: Plain text
1406+#, no-wrap
1407+msgid ""
1408+"\tclass enhancedEdit(IAccessible):\n"
1409+"\t\t# Some code to be run when window class name is MyEdit.\n"
1410+msgstr ""
1411+
1412+#. type: Plain text
1413+#, no-wrap
1414+msgid ""
1415+"\tclass MainWindow(IAccessible):\n"
1416+"\t\t# Another code, this time adding custom gestures for main window of the program.\n"
1417+msgstr ""
1418+
1419+#. type: Plain text
1420+#, no-wrap
1421+msgid "\t# In the app module:\n"
1422+msgstr ""
1423+
1424+#. type: Plain text
1425+#, no-wrap
1426+msgid ""
1427+"\tdef chooseNVDAObjectOverlayClasses(self, obj, clsList):\n"
1428+"\t\tif obj.windowClassName == \"myEdit\": clsList.insert(0, enhancedEdit)\n"
1429+"\t\telif obj.windowClassName == \"TWindow\": clsList.insert(0, mainWindow)\n"
1430+msgstr ""
1431+
1432+#. type: Plain text
1433+msgid ""
1434+"In both cases, the object that we wish to check must be inserted as the "
1435+"first element of the clsList. The effect is that these custom objects will "
1436+"take precedence when looking up gestures or code (behavior) for the object, "
1437+"and in the developer info, these custom objects will come first when MRO "
1438+"(Method Resolution Order) for the navigator object is displayed."
1439+msgstr ""
1440+
1441+#. type: Title ###
1442+#, no-wrap
1443+msgid "Input and output: scripts and UI messages"
1444+msgstr ""
1445+
1446+#. type: Plain text
1447+msgid ""
1448+"Another crucial component of add-ons is handling commands from users and "
1449+"displaying what the add-on is doing. These are done via scripts (input) and "
1450+"UI messages (output)."
1451+msgstr ""
1452+
1453+#. type: Plain text
1454+msgid ""
1455+"A script is a method run when the user performs certain commands. For "
1456+"example, when you press NvDA+T, NVDA runs a script in global commands module "
1457+"called SayTitle. In Poedit, for instance, when a translator presses Control"
1458+"+Shift+A, NvDA will read translator comments added by the programmer to help "
1459+"clarify a given translatable string. this command is not a native NvDA "
1460+"command, but it is defined in the Poedit app module to perform this function."
1461+msgstr ""
1462+
1463+#. type: Plain text
1464+msgid ""
1465+"Typically, an add-on which accepts scripts will have a list of command:"
1466+"function map somewhere in the module. The simplest is a gestures (commands) "
1467+"dictionary, a python dictionary (typically named __gestures) which holds "
1468+"commands as keys and scripts as values for these keys (more than one key, or "
1469+"command can be bound to scripts). These dictionaries are loaded when add-on "
1470+"loads and is cleared when either NvDA exits or the app for the app module "
1471+"loses focus (that is, the user has switched to another program)."
1472+msgstr ""
1473+
1474+#. type: Plain text
1475+msgid ""
1476+"Another way to bind scripts is via runtime insertion. This is done by "
1477+"creating another gestures dictionary apart from __gestures dictionary which "
1478+"holds context-sensitive gestures such as manipulating a single control. Then "
1479+"the developer would use inputCore.bindGesture (or inputCore.bindGestures if "
1480+"more than one gestures/scripts are defined) to define certain gestures for a "
1481+"time, then using inputCore.clearGestures then inputCore.bindGestures"
1482+"(__gestures) to remove the added gestures. A more elegant way, which "
1483+"involves scripts for specific objects, will be covered when we talk about "
1484+"overlay classes."
1485+msgstr ""
1486+
1487+#. type: Plain text
1488+msgid ""
1489+"As of time of writing, NvDA supports input from the keyboard, braille "
1490+"dislays with or without braille keyboard and touchscreens."
1491+msgstr ""
1492+
1493+#. type: Title ###
1494+#, no-wrap
1495+msgid "Example 2: A basic script dictionary"
1496+msgstr ""
1497+
1498+#. type: Plain text
1499+msgid ""
1500+"In this example, we'll define two scripts called \"sayHello\" and say"
1501+"\"GoodBye\", then bind them into two separte gestures."
1502+msgstr ""
1503+
1504+#. type: Plain text
1505+#, no-wrap
1506+msgid ""
1507+"\t# An example fragment for script assignment.\n"
1508+"\timport ui\n"
1509+msgstr ""
1510+
1511+#. type: Plain text
1512+#, no-wrap
1513+msgid ""
1514+"\tdef script_sayHello(self, gesture):\n"
1515+"\t\tui.message\"Hello!\")\n"
1516+msgstr ""
1517+
1518+#. type: Plain text
1519+#, no-wrap
1520+msgid ""
1521+"\tdef script_sayGoodBye(self, gesture):\n"
1522+"\t\tui.message(\"Good Bye!\")\n"
1523+msgstr ""
1524+
1525+#. type: Plain text
1526+#, no-wrap
1527+msgid ""
1528+"\t__gestures={\n"
1529+"\t\t\"kb:control+NVDA+1\":\"sayHello\",\n"
1530+"\t\t\"kb:Control+NVDA+2\":\"sayGoodBye\"\n"
1531+"\t}\n"
1532+msgstr ""
1533+
1534+#. type: Plain text
1535+msgid ""
1536+"Now when you press Control+NvDA+1, NvDA will say, \"Hello\", and when you "
1537+"press Control+NvDA+2, NVDA will say, \"Good bye.\""
1538+msgstr ""
1539+
1540+#. type: Title ###
1541+#, no-wrap
1542+msgid "Example 3: runtime script insertion/removal"
1543+msgstr ""
1544+
1545+#. type: Plain text
1546+#, no-wrap
1547+msgid "\t# Future sections #\n"
1548+msgstr ""
1549+
1550+#. type: Plain text
1551+msgid "Please delete this notice when appropriate sections are done."
1552+msgstr ""
1553+
1554+#. type: Title ##
1555+#, no-wrap
1556+msgid "Add-on components and development tips"
1557+msgstr ""
1558+
1559+#. type: Plain text
1560+msgid ""
1561+"Includes introductions to input and scripts, output systems, objects, "
1562+"events, configuration, add-on settings and reloading plug-ins. Also includes "
1563+"some tips on add-on development such as debugging. It concludes with some "
1564+"useful examples and do's and don'ts."
1565+msgstr ""
1566+
1567+#. type: Plain text
1568+msgid ""
1569+"Planned sections (please feel free to contribute your knowledge in this "
1570+"section):"
1571+msgstr ""
1572+
1573+#. type: Bullet: '* '
1574+msgid "Introduction to NVDA objects."
1575+msgstr ""
1576+
1577+#. type: Bullet: '* '
1578+msgid "Examining object attributes with Python Console."
1579+msgstr ""
1580+
1581+#. type: Bullet: '* '
1582+msgid "Fetching and setting objects."
1583+msgstr ""
1584+
1585+#. type: Bullet: '* '
1586+msgid ""
1587+"Object hierarchy and differences between regular and simple review modes."
1588+msgstr ""
1589+
1590+#. type: Bullet: '* '
1591+msgid "The event_NVDAObject_init and chooseNVDAObjectOverlayClasses methods."
1592+msgstr ""
1593+
1594+#. type: Bullet: '* '
1595+msgid "Events and list of available events."
1596+msgstr ""
1597+
1598+#. type: Bullet: '* '
1599+msgid "Next handlers."
1600+msgstr ""
1601+
1602+#. type: Bullet: '* '
1603+msgid ""
1604+"Input from keyboard, braille displays, mouse and touchscreen via scripts."
1605+msgstr ""
1606+
1607+#. type: Bullet: '* '
1608+msgid "Script lookup process and conflicts."
1609+msgstr ""
1610+
1611+#. type: Bullet: '* '
1612+msgid ""
1613+"Static and dynamic script bindings, gesture dictionaries and script "
1614+"categories."
1615+msgstr ""
1616+
1617+#. type: Bullet: '* '
1618+msgid "Braille, speech and tone output."
1619+msgstr ""
1620+
1621+#. type: Bullet: '* '
1622+msgid "Debugging add-ons."
1623+msgstr ""
1624+
1625+#. type: Bullet: '* '
1626+msgid "If something goes wrong (common errors and exceptions)."
1627+msgstr ""
1628+
1629+#. type: Bullet: '* '
1630+msgid "Few working and non-working examples for each topic."
1631+msgstr ""
1632+
1633+#. type: Bullet: '* '
1634+msgid "These plan sections may change."
1635+msgstr ""
1636+
1637+#. type: Title ##
1638+#, no-wrap
1639+msgid "Global Plugins"
1640+msgstr ""
1641+
1642+#. type: Plain text
1643+msgid "A chapter devoted to global plugins."
1644+msgstr ""
1645+
1646+#. type: Plain text
1647+msgid "Planned sections:"
1648+msgstr ""
1649+
1650+#. type: Bullet: '* '
1651+msgid "What exactly is global plugin."
1652+msgstr ""
1653+
1654+#. type: Bullet: '* '
1655+msgid ""
1656+"Importance of consulting NvDA and add-on commands to minimize command "
1657+"conflicts."
1658+msgstr ""
1659+
1660+#. type: Bullet: '* '
1661+msgid "When not to use global plugins."
1662+msgstr ""
1663+
1664+#. type: Bullet: '* '
1665+msgid "A few worked out examples."
1666+msgstr ""
1667+
1668+#. type: Bullet: '* '
1669+msgid "These sections may change."
1670+msgstr ""
1671+
1672+#. type: Title ##
1673+#, no-wrap
1674+msgid "App Modules"
1675+msgstr ""
1676+
1677+#. type: Plain text
1678+msgid "A chapter devoted to app modules."
1679+msgstr ""
1680+
1681+#. type: Bullet: '* '
1682+msgid "What is an app module."
1683+msgstr ""
1684+
1685+#. type: Bullet: '* '
1686+msgid "App module scripts."
1687+msgstr ""
1688+
1689+#. type: Bullet: '* '
1690+msgid "Defining objects representing different parts of a program."
1691+msgstr ""
1692+
1693+#. type: Bullet: '* '
1694+msgid "Silencing NVDA for a program."
1695+msgstr ""
1696+
1697+#. type: Bullet: '* '
1698+msgid "How app developers can help NVDA users through accessible app designs."
1699+msgstr ""
1700+
1701+#. type: Bullet: '* '
1702+msgid ""
1703+"A few worked out examples and examples from existing app modules from NVDA "
1704+"core and from community."
1705+msgstr ""
1706+
1707+#. type: Bullet: '* '
1708+msgid "These topics may change."
1709+msgstr ""
1710+
1711+#. type: Title ##
1712+#, no-wrap
1713+msgid "Drivers"
1714+msgstr ""
1715+
1716+#. type: Plain text
1717+msgid "A chapter devoted to driver development."
1718+msgstr ""
1719+
1720+#. type: Title ##
1721+#, no-wrap
1722+msgid "Misc items"
1723+msgstr ""
1724+
1725+#. type: Plain text
1726+msgid ""
1727+"Includes Bitbucket repo, add-ons lisst, other topics and contact information."
1728+msgstr ""
1729+
1730+#. type: Plain text
1731+msgid ""
1732+"[1]: http://community.nvda-project.org/wiki/Development [2]: http://"
1733+"community.nvda-project.org/documentation/developerGuide.html"
1734+msgstr ""
Show on old repository browser