Hi, Gotcha - sending it again since the original message came just to me. Mick and Jamie: would it be possible to integrate our add-on dev guide and WinAPI guide docs into the main developer guide file in the end? Cheers, Joseph -----Original Message----- From: nvda-addons-bounce@xxxxxxxxxxxxx [mailto:nvda-addons-bounce@xxxxxxxxxxxxx] On Behalf Of Mesar Hameed Sent: Tuesday, December 30, 2014 12:13 PM To: nvda-addons@xxxxxxxxxxxxx Subject: [nvda-addons] Re: commit/devGuide: josephsl: Added WinAPI file from Greg Z. Hi, In my opinion all of this good work should be integrated into the developer documentation for NVDA. This would mean: 1. Less duplication of information. 2. One central place for best practise. 3. Group maintenance The question is who has the time/the good english required. Alternatively instead of one major change, submit several patches, get them accepted and move on to the next one. thanks, Mesar On Tue 30/12/14,11:51, Joseph Lee wrote: > Hi all, > NVDA Add-on Developer Guide 2015 is now available. New in this edition > include: > * Defining constructors for app modules. > * Defining and warning on terminate method for add-ons. > * ConfigObj. > * A new link to a document on using Windows API in your add-on (credit: > Greg). > Thanks. > Cheers, > Joseph > > > -----Original Message----- > From: nvda-addons-commits-bounce@xxxxxxxxxxxxx > [mailto:nvda-addons-commits-bounce@xxxxxxxxxxxxx] On Behalf Of > commits-noreply@xxxxxxxxxxxxx > Sent: Tuesday, December 30, 2014 11:44 AM > To: nvda-addons-commits@xxxxxxxxxxxxx > Subject: commit/devGuide: josephsl: Added WinAPI file from Greg Z. > > 1 new commit in devGuide: > > https://bitbucket.org/nvdaaddonteam/devguide/commits/f6f5da409a6b/ > Changeset: f6f5da409a6b > Branch: master > User: josephsl > Date: 2014-12-30 19:43:35+00:00 > Summary: Added WinAPI file from Greg Z. > > Affected #: 1 file > > diff --git a/readme.md b/readme.md > index b3ba1c0..22eef6e 100644 > --- a/readme.md > +++ b/readme.md > @@ -3,7 +3,7 @@ > # NVDA Add-on Development Guide > > Author: Joseph Lee and contributors > -Latest version: October 2014 > +Latest version: January 2015 > > Welcome to NVDA Add-on Development Guide. This is the one-stop guide > on how NVDA add-ons are developed, as well as explaining some useful > code segments from NVDA core source code useful when writing add-ons. > > @@ -240,7 +240,8 @@ The following lists available NVDA core modules > and some useful methods found in > * Keyboard input (keyboardHandler.py): Supports entering commands > from the keyboard. > * Logging facility (logHandler.py): Allows a module to write logs to > be viewed by a developer or a user via Log Viewer. > * Mouse support (mouseHandler.py): Supports mouse commands. > -* NVDA objects collection (NVDAObjects): A collection of NVDA objects > or controls used in many applications and standards such as UIA (User > Interface Automation). > +* NVDA objects collection (NVDAObjects): A collection of NVDA objects > +or > controls used in many applications and standards such as UIA (User > Interface Automation). Some objects require special actions to be > performed, and these are specified in behaviors module in NvDA objects package. > +* Review facility (review.py): assists with working with review cursor. > * Scripts support (scriptHandler.py): Handles scripts, methods > executed due to the user pressing keyboard commands and other input. > * Speech output (speech.py): Controls speech output. > * Synthesizer driver support (synthDriverHandler.py): This is the > core module needed for speech synthesizer add-ons. > @@ -251,7 +252,7 @@ The following lists available NVDA core modules > and some useful methods found in > * UIA support (UIAHandler.py, UIA objects): Used for supporting UIA > (User Interface Automation) controls. > * Virtual buffers (virtualBuffers): Handles virtual buffer documents > such as websites. > > -The modules without .py extension are directories, containing > specialist modules. > +The modules without .py extension are directories, containing > +specialist > modules. In addition, NVDA provides wrappers for Windows libraries > (DLL's) such as Windows User (user32.dll wrapped in winUser.py), > Windows Kernel (kernel32.dll wrapped in winKernel.py) and so on used > in some specialist situation when using Windows API is a must (such as > sending messages back and forth in an app module). > > ### Useful methods ### > > @@ -550,7 +551,7 @@ Besides objects, scripts and events, you can add > other components in your add-on > > If you wish to store settings for your add-on, use ConfigObj to store > configuration files and settings. > > -Finally, you can ask NVDA to perform some routines while the add-on > is loading. This is done by defining `__init__` method for the add-on. > Depending on the plugin type, use: > +Finally, you can ask NVDA to perform some routines while the add-on > +is > loading or being terminated. This is done by defining `__init__` and > `terminate` method for the add-on. Depending on the plugin type, use: > > * For global plugin: > def __init__(self): > @@ -561,6 +562,11 @@ Finally, you can ask NVDA to perform some > routines while the add-on is loading. > super(AppModule, self).__init__(*args, **kwargs) > # What NvDA should do when the app module loads. > > +* For terminating, regardless of the add-on type: > + def terminate(self): > + # Do something when the add-on terminates. > + # Warning! Never initialize ANY core module such as GUI in > terminate method as doing so will prevent NVDA from exiting properly. > + > ### Let's build an add-on ### > > Now we have a basic overview of components of add-ons, we're ready to > build some simple add-ons. But first, let's go over the actual add-on > development process, debugging tips, do's and don'ts and other tips. > @@ -600,7 +606,7 @@ Q. The command for my app module does not work in > my app module; instead, NVDA d Check if a global plugin which uses > the command is installed. First, remove the global plugin and try again. > > Q. How can I use Win32 API in my add-on or object? > -There is a document written by an add-on developer which talks about > using > Win32 API in your add-on. > +There is a document written by an add-on developer which talks about > +using > Win32 API in your add-on. Select [this link][4] to view this document. > > Q. How can I create dialogs in my add-on? > You need to import two modules: GUI (import gui) and WXPython (import wx). > @@ -614,6 +620,9 @@ Yes. You'll need to use ConfigObj library > (configObj) to manage configuration. S Q. I have a script which calls > a function that runs for a long time, and I cannot run NVDA commands when my script runs. > One way to fix this is using threads (separate, independent > operations in a program) via Python's threading module. In order to do > this, create a method which you know will run for a long time, then > from the script which calls this method, create a new thread (see > Python's threading module > documentation) that'll be in charge of running this method. This way > other NVDA commands can be performed while the add-on method does its > work (see Google Speech Recognition module for an example code). > > +Q. I would like to port a module written in Python 3 syntax for use > +as an > NVDA add-on. > +This cannot be done easily. One handy module for this purpose is six, > +which > allows running Python 2 and 3 code. NvDA itself uses Python 2 as > WXPython uses Python 2, and until WXPython is rewritten to support > Python 3, you cannot run Python 3 code in NVDA. > + > We did not include programming or Python-related FAQ's, as there are > sites which answers questions about Python such as coding style. > Consult these documents if you have issues with Python code. > > Now that we have covered basic add-on components, let's learn about > how to package what you know in your add-on modules themselves: global > plugins, app modules and drivers. > @@ -676,7 +685,7 @@ The global plugin, named brailleWrite.py, would > look like this: > brlentry = False # Braille entry is not active. > > def script_toggleBrailleEntry(self, gesture): > - self.brlentry = True if self.brlentry == False else > False # Toggle braille entry mode. > + self.brlentry = True if not self.brlentry else False > # Toggle braille entry mode. > script_toggleBrailleEntry.__doc__="Toggles braille entry on or > off." > __gestures={ > "kb:NVDA+X":"toggleBrailleEntry" > @@ -717,7 +726,7 @@ A typical app module is developed thus: > > As you write app modules, try these tips: > > -1. Use objects to represent parts of a program. This is done in two steps: > define the control for parts of a program via objects (inheriting from > some object such as IAccessible), then use > `chooseNVDAObjectOverlayClasses` routine to tell NVDA to work with > your custom object when working with that control. > +1. Use objects to represent parts of a program. This is done in two steps: > define the control for parts of a program via objects (inheriting from > some object such as IAccessible), then use > `chooseNVDAObjectOverlayClasses` routine to tell NVDA to work with > your custom object when working with that control. See overlay classes section for tips. > 2. If possible, test your app module using two or more versions of > the program to make sure your app module works with those versions. > 3. You should not incorporate all desired features in version 1.0 - > leave some of them for a future release. > > @@ -735,7 +744,7 @@ The app module for Notepad would look like this: > class AppModule(appModuleHandler.AppModule): > def script_sayLineNumber(self, gesture): > # Suppose line number is in the form " ln 1". > - lineNumList = api.getStatusBar().name.split(" ") > + lineNumList = api.getStatusBar().name.split() > lineNum = lineNumLisst[2]+linenumList[3] > ui.message(lineNum) > > @@ -773,6 +782,7 @@ And other properties. Type dir(obj.appModule) from > Python Console for the comple Here are other remarks regarding app modules: > > * If you find that different versions of the program are laid out > differently e.g. locations for controls are different, then you can > write code which can handle these cases. There are a number of options > you can choose from: adding some constants in your app module to > handle different object locations, writing code for these controls > (one per version) in custom objects which will be chosen in overlay class method and so on. > +* If possible, try working with services that the app provides, such > +as COM > (Component Object Model) methods (for example, Outlook app module), > API's the app provides (such as Winamp) and so on. > * To support an application that works the same as another program > (especially if you're writing app module for a 64-bit version of a > 32-bit program for which you wrote an app module for), use the > following code > fragment: > from appName import * > where appName is the name of the app module and * (asterisk or star) > means import everything. For an example of this, look at NVDA's app > modules for > Miranda32 and Miranda64. > @@ -852,3 +862,4 @@ A chapter devoted to driver development. > [1]: http://community.nvda-project.org/wiki/Development > [2]: > http://community.nvda-project.org/documentation/developerGuide.html > [3]: https://bitbucket.org/nvdaaddonteam/addontemplate/get/master.zip > +[4]: http://www.zlotowicz.pl/nvda/winapi.mdwn > > Repository URL: https://bitbucket.org/nvdaaddonteam/devguide/ > > -- > > This is a commit notification from bitbucket.org. You are receiving > this because you have the service enabled, addressing the recipient of > this email. > > ---------------------------------------------------------------- > NVDA add-ons: A list to discuss add-on code enhancements and for reporting bugs. > > Community addons are available from: http://addons.nvda-project.org To > send a message to the list: nvda-addons@xxxxxxxxxxxxx To change your > list settings/unsubscribe: //www.freelists.org/list/nvda-addons > To contact list moderators: nvda-addons-moderators@xxxxxxxxxxxxx ---------------------------------------------------------------- NVDA add-ons: A list to discuss add-on code enhancements and for reporting bugs. Community addons are available from: http://addons.nvda-project.org To send a message to the list: nvda-addons@xxxxxxxxxxxxx To change your list settings/unsubscribe: //www.freelists.org/list/nvda-addons To contact list moderators: nvda-addons-moderators@xxxxxxxxxxxxx ---------------------------------------------------------------- NVDA add-ons: A list to discuss add-on code enhancements and for reporting bugs. Community addons are available from: http://addons.nvda-project.org To send a message to the list: nvda-addons@xxxxxxxxxxxxx To change your list settings/unsubscribe: //www.freelists.org/list/nvda-addons To contact list moderators: nvda-addons-moderators@xxxxxxxxxxxxx