Skip to content

Commit 1272d22

Browse files
XLTechieXLTechie
authored
Merge 84192d0 into 9fe5207 
2 parents 9fe5207 + 84192d0 commit 1272d22

2 files changed

Lines changed: 108 additions & 8 deletions

File tree

‎devDocs/developerGuide.t2t‎

Lines changed: 107 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ It is not the goal of this guide to teach you Python, though examples are provid
3636
Documentation and other resources related to the Python language can be found at www.python.org/
3737

3838
++ C++ ++
39-
Some of NVDA is written in C++, EG nvdaHelper.
39+
Some of NVDA is written in C++, e.g. nvdaHelper.
4040
For an overview of nvdaHelper, including how to configure Visual Studio to enable intellisense see the
4141
[nvdaHelper readme https://github.com/nvaccess/nvda/blob/master/nvdaHelper/readme.md]
4242

@@ -297,10 +297,10 @@ As with other examples in this guide, remember to delete the created app module
297297

298298
++ App modules for hosted apps ++
299299
Some executables host various apps inside.
300-
These include javaw.exe for running various java programs and wwahost.exe for some apps in Windows 8 and later.
300+
These include javaw.exe for running various Java programs and wwahost.exe for some apps in Windows 8 and later.
301301

302302
If an app runs inside a host executable, the name of the app module must be the name as defined by the host executable, which can be found through AppModule.appName property.
303-
For example, an app module for a java app named "test" hosted inside javaw.exe must be named test.py.
303+
For example, an app module for a Java app named "test" hosted inside javaw.exe must be named test.py.
304304
For apps hosted inside wwahost, not only must the app module name be the name of the loaded app, but the app module must subclass the app module class found in wwahost.
305305

306306
++ Example 2: an app module for an app hosted by wwahost.exe ++
@@ -418,7 +418,7 @@ For example, a list's first child would be the first list item.
418418
-
419419

420420
There are also a few simplified navigation properties such as simpleParent, simpleNext, simpleFirstChild and simpleLastChild.
421-
These are like their respective navigation properties described above, but NVDA filters out unuseful objects.
421+
These are like their respective navigation properties described above, but NVDA filters out useless objects.
422422
These properties are used when NVDA's simple review mode is turned on, which is the default.
423423
These simple properties may be easier to use, but the real navigation properties more closely reflect the underlying Operating System structure.
424424
Also, these may change in future versions of NVDA as improvements are made to simple review, so they should generally be avoided when programmatically locating specific objects.
@@ -741,7 +741,7 @@ class AppModule(appModuleHandler.AppModule):
741741
--- end ---
742742
```
743743

744-
++ Parsing additional command line arguments in your plugin ++
744+
++ Parsing additional command line arguments in your plugin ++[PluginCLIArgs]
745745
By default NVDA accepts limited set of command line arguments and shows an error for an unknown ones.
746746
However if you want to use any additional arguments, this is possible by adding a handler to the extension point ``addonHandler.isCLIParamKnown``.
747747
Note that since command line arguments are processed just after NVDA starts, your add-on needs to process them in the global plugin, since app modules or other drivers may not be loaded at this stage.
@@ -761,7 +761,7 @@ addonHandler.isCLIParamKnown.register(processArgs)
761761
+ Packaging Code as NVDA Add-ons +[Addons]
762762
To make it easy for users to share and install plugins and drivers, they can be packaged in to a single NVDA add-on package which the user can then install into a copy of NVDA via the Add-ons Manager found under Tools in the NVDA menu.
763763
Add-on packages are only supported in NVDA 2012.2 and later.
764-
An add-on package is simply a standard zip archive with the file extension of nvda-addon which contains a manifest file, optional install/uninstall code and one or more directories containing plugins and/or drivers.
764+
An add-on package is simply a standard zip archive with the file extension of "``nvda-addon``" which contains a manifest file, optional install/uninstall code and one or more directories containing plugins and/or drivers.
765765

766766
++ Non-ASCII File Names in Zip Archives ++
767767
If your add-on includes files which contain non-ASCII (non-English) characters, you should create the zip archive such that it uses UTF-8 file names.
@@ -804,7 +804,7 @@ All string values must be enclosed in quotes as shown in the example below.
804804

805805
The lastTestedNVDAVersion field in particular is used to ensure that users can be confident about installing an add-on.
806806
It allows the add-on author to make an assurance that the add-on will not cause instability, or break the users system.
807-
When this is not provided, or is less than the current version of NVDA (ignoring minor point updates EG 2018.3.1) then the user will be warned not to install the add-on.
807+
When this is not provided, or is less than the current version of NVDA (ignoring minor point updates e.g. 2018.3.1) then the user will be warned not to install the add-on.
808808

809809
+++ An Example Manifest File +++
810810
```
@@ -947,3 +947,103 @@ There are some special functions:
947947
- snap(): Takes a snapshot of the current state of NVDA and saves it in the [snapshot variables #PythonConsoleSnapshotVariables].
948948
- rmSnap(): Removes all snapshot variables.
949949
-
950+
951+
+ Extension Points +[ExtensionPoints]
952+
NVDA's ``extensionPoints`` module, allows code in different parts of NVDA, or in add-ons, to perform tasks such as:
953+
- Be notified when an action occurs or a state is changed.
954+
- Receive, as part of being notified, variables related to the action or changed state.
955+
- Cancel or alter an action NVDA was going to take, based upon certain conditions.
956+
- Modify data that NVDA is using (such as changing speech sequences or braille, before they are spoken or brailled).
957+
- Delay something NVDA is doing, while intervening operations are performed.
958+
-
959+
960+
There are five kinds of extension point:
961+
962+
|| Type | Purpose |
963+
| ``Action`` | Allows some code to find out what other code is doing. For example, an add-on can be notified before or after a config profile changes. |
964+
| ``Filter`` | Edits data. A filter registered in the speech module, might allow changing speech strings before they are spoken. |
965+
| ``Decider`` | Runs each registered handler until one of them returns ``False``. If one does, it can be used to prevent the invoking code from running. |
966+
| ``AccumulatingDecider`` | Like ``Decider``, but always runs all of its registered handlers, and only decides if one of them failed at the end. The default decision is ``True`` by default, but can be set to ``False``. |
967+
| ``Chain`` | Allows registering handlers that return iterables (mainly generators). Calling ``iter`` on the ``Chain`` returns a generator that iterates over all the handlers. |
968+
969+
The sections below provide the list of currently defined extension points in NVDA, along with brief descriptions for them.
970+
Please see code documentation in the associated files, or the code itself, for further explanation.
971+
The section titles below represent the package or module in which the listed extension points are defined.
972+
973+
For examples of how to define and use new extension points, please see the code documentation of the ``extensionPoints`` module.
974+
975+
++ braille ++[brailleExtPts]
976+
|| Type | Extension Point | Description |
977+
| ``Filter`` | ``filter_displaySize`` | Allows components or add-ons to change the display size used for braille output. |
978+
| Action | displaySizeChanged | Notifies of display size changes. |
979+
| Action | pre_writeCells | Notifies when cells are about to be written to a braille display |
980+
| Action | displayChanged | Notifies of braille display changes. |
981+
| Decider | decide_enabled | Allows deciding whether the braille handler should be forcefully disabled. |
982+
983+
++ appModuleHandler ++[appModuleHandlerExtPts]
984+
|| Type | Extension Point | Description |
985+
| Action | post_appSwitch | Triggered when the foreground application changes |
986+
987+
++ addonHandler ++[addonHandlerExtPts]
988+
|| Type | Extension Point | Description |
989+
| Accumulating Decider | isCLIParamKnown | Allows adding NVDA commandline parameters which apply to plugins. See [this section of the Dev Guide #PluginCLIArgs] for more information. |
990+
991+
++ brailleViewer ++[brailleViewerExtPts]
992+
|| Type | Extension Point | Description |
993+
| Action | postBrailleViewerToolToggledAction | Triggered every time the Braille Viewer is created / shown or hidden / destroyed. |
994+
995+
++ config ++[configExtPts]
996+
|| Type | Extension Point | Description |
997+
| Action | post_configProfileSwitch | Notifies after the configuration profile has been switched. |
998+
| Action | pre_configSave | Notifies before NVDA's configuration is saved to disk. |
999+
| Action | post_configSave | Notifies after NVDA's configuration has been saved to disk. |
1000+
| Action | pre_configReset | Notifies before configuration is reloaded from disk or factory defaults are applied. |
1001+
| Action | post_configReset | Notifies after configuration has been reloaded from disk or factory defaults were applied. |
1002+
1003+
++ core ++[coreExtPts]
1004+
|| Type | Extension Point | Description |
1005+
| ``Action`` | ``postNvdaStartup`` | Notifies after NVDA has finished starting up. |
1006+
1007+
++ inputCore ++[inputCoreExtPts]
1008+
|| Type | Extension Point | Description |
1009+
| Decider | decide_executeGesture | Notifies when a gesture is about to be executed, allowing other code to decide if it should be. |
1010+
1011+
++ nvwave ++[nvwaveExtPts]
1012+
|| Type | Extension Point | Description |
1013+
| Decider | decide_playWaveFile | Notifies when a wave file is about to be played, allowing other code to decide if it should be. |
1014+
1015+
++ synthDriverHandler ++[synthDriverHandlerExtPts]
1016+
|| Type | Extension Point | Description |
1017+
| Action | synthIndexReached | Notifies when a synthesizer reaches an index during speech. |
1018+
| Action | synthDoneSpeaking | Notifies when a synthesizer finishes speaking. |
1019+
| Action | synthChanged | Notifies of synthesizer changes. |
1020+
1021+
++ tones ++[tonesExtPts]
1022+
|| Type | Extension Point | Description |
1023+
| Decider | decide_beep | Notifies when a beep is about to be generated and played, allowing a consumer to decide whether it should be. |
1024+
1025+
++ utils.security ++[utils_securityExtPts]
1026+
|| Type | Extension Point | Description |
1027+
| Action | post_sessionLockStateChanged | Notifies when a session lock or unlock event occurs. |
1028+
1029+
++ winAPI.messageWindow ++[winAPI_messageWindowExtPts]
1030+
|| Type | Extension Point | Description |
1031+
| Action | pre_handleWindowMessage | Notifies when NVDA receives a window message, allowing components to perform an action when certain system events occur. |
1032+
1033+
++ bdDetect ++[bdDetectExtPts]
1034+
|| Type | Extension Point | Description |
1035+
| Chain | scanForDevices | Can be iterated to scan for braille devices. |
1036+
1037+
++ vision.visionHandlerExtensionPoints.EventExtensionPoints ++[visionExtPts]
1038+
These extension points are expected to be used and registered to differently than other extension points.
1039+
Please see the ``EventExtensionPoints`` class documentation for more information, and detailed descriptions.
1040+
1041+
|| Type | Extension Point | Notifies a vision enhancement provider when … |
1042+
| Action | post_objectUpdate | an object property has changed. |
1043+
| Action | post_focusChange | the focused NVDAObject has changed. |
1044+
| Action | post_foregroundChange | the foreground NVDAObject has changed. |
1045+
| Action | post_caretMove | a physical caret has moved. |
1046+
| Action | post_browseModeMove | a virtual caret has moved. |
1047+
| Action | post_reviewMove | the position of the review cursor has changed. |
1048+
| Action | post_mouseMove | the mouse has moved. |
1049+
| Action | post_coreCycle | the end of each core cycle has been reached. |

‎source/extensionPoints/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ class AccumulatingDecider(HandlerRegistrar[Callable[..., bool]]):
178178
which are unknown to NVDA, but this extension point can be used to pass each unknown parameter
179179
to all add-ons since one of them may want to process some command line arguments.
180180
181-
First, a AccumulatingDecider is created with a default decision :
181+
First, an AccumulatingDecider is created with a default decision :
182182
183183
>>> doSomething = AccumulatingDecider(defaultDecision=True)
184184

0 commit comments

Comments
 (0)