Add-on development guide: June 2017 revision is ready

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Add-on development guide: June 2017 revision is ready

Joseph Lee

Hi everyone,

 

June 2017 edition of the popular NVDA Add-on Development Guide is now up:

https://github.com/nvdaaddons/devguide/wiki/NVDA%20Add-on%20Development%20Guide

 

What’s new and changed:

  • Added ui.browsableMessage function.
  • Greatly expanded NVDA modules chapter to include various examples.
  • Added paragraphs on text infos and math presentation layer (mathPres). Mick Curran from NV Access provided an easy to follow explanation of text infos, which is a way to look at text in a widget via offsets and ranges.
  • Expanded Drivers chapter and added information on essential components of drivers for speech synthesizers and braille displays. I need to come up with an interesting driver example for folks to read.
  • Added several appendices, more on that below.
  • Ready for contributions from the wider community, including from scripters of other screen readers.

 

New in June 2017 edition is a set of appendices (two written, two in the works). These include:

  • Appendix A: definitions of terms used during add-on development and ones used by the add-ons community.
  • Appendix B: Python and programming concepts add-on writers will need to know.
  • Appendix C (coming soon): a table summarizing differences between various add-on types.
  • Appendix D (coming soon): references for scripters of other screen readers, a table that summarizes how to perform tasks via NVDA/Python that you were used to doing with other screen readers. This appendix is my contribution to Project Contact Lenses, and I’d like to request help from scripters in making sure this appendix is thorough and well done.

 

Thanks, and enjoy the documentation.

Cheers,

Joseph


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel
Reply | Threaded
Open this post in threaded view
|

Re: Add-on development guide: June 2017 revision is ready

Travis Roth

Hi,

Thanks for this work, it is starting to look quite useful.

I am listing out a few observations and suggestions from my first read of today’s version for consideration. I hope this helps.

 

Example 3: Announce the automation ID of a UIA object:

the code appears on one line, it appears it is not in a <pre> tag?

 

Examples of overlay classes and modified roles:

The first example of modifying a Delphi window does not indicate where the constant ROLE_WINDOW comes from. I realize it was covered earlier to import from controltypes but this seems it'd be helpful to include for completeness.

 

Input and output: scripts and UI messages:

a) It would be helpful somewhere in this section to note what modifiers are available to be used as shortcuts, e.g., NVDA and Control. Any that do not work, e.g., Windows?

b) Also a slight explanation of the __gestures dictionary could help? When looking at "Example 2: A basic script dictionary and message output" the question that jumped at me was: is __gestures case sensitive? I noticed both "control" and "Control" being used, normally Python is case sensitive, so is this a problem?

c) A common question that I've seen come up is what happens to the gesture at the point the script receives it? And if NVDA uses it, how can I pass the keystroke on to the application as well? I assume by default NVDA uses the keystroke and does not pass it along which I think is normal for most screen readers, however, confirming this fact for the script writer would be nice.

 

Travis

 

From: Joseph Lee [mailto:[hidden email]]
Sent: Wednesday, June 21, 2017 3:04 PM
To: 'NVDA screen reader development' <[hidden email]>
Subject: [Nvda-devel] Add-on development guide: June 2017 revision is ready

 

Hi everyone,

 

June 2017 edition of the popular NVDA Add-on Development Guide is now up:

https://github.com/nvdaaddons/devguide/wiki/NVDA%20Add-on%20Development%20Guide

 

What’s new and changed:

  • Added ui.browsableMessage function.
  • Greatly expanded NVDA modules chapter to include various examples.
  • Added paragraphs on text infos and math presentation layer (mathPres). Mick Curran from NV Access provided an easy to follow explanation of text infos, which is a way to look at text in a widget via offsets and ranges.
  • Expanded Drivers chapter and added information on essential components of drivers for speech synthesizers and braille displays. I need to come up with an interesting driver example for folks to read.
  • Added several appendices, more on that below.
  • Ready for contributions from the wider community, including from scripters of other screen readers.

 

New in June 2017 edition is a set of appendices (two written, two in the works). These include:

  • Appendix A: definitions of terms used during add-on development and ones used by the add-ons community.
  • Appendix B: Python and programming concepts add-on writers will need to know.
  • Appendix C (coming soon): a table summarizing differences between various add-on types.
  • Appendix D (coming soon): references for scripters of other screen readers, a table that summarizes how to perform tasks via NVDA/Python that you were used to doing with other screen readers. This appendix is my contribution to Project Contact Lenses, and I’d like to request help from scripters in making sure this appendix is thorough and well done.

 

Thanks, and enjoy the documentation.

Cheers,

Joseph


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel
Reply | Threaded
Open this post in threaded view
|

Re: Add-on development guide: June 2017 revision is ready

Joseph Lee

Hi,

Gestures and scripts: once a script receives a gesture, it can do whatever it wishes, including sending it to the active application (this works best for keyboard input). I’ll add an example of this in the scripts section.

Modifiers: basically, any key combo can be used (except for Control+Alt+Delete and friends). Until a few years ago, it wasn’t possible to assign NVDA commands to gestures that involved Alt and Windows key. This was fixed not long ago. I’ll document possible modifiers (or add a sentence about them) in the input section.

Control types for Delphi example: I’ll clarify where the window role came from.

Gestures dictionary: yes, __gestures is case sensitive. Because it has double underscores as a prefix, Python will mangle this name.

I’ll publish the above edits later this week.

Cheers,

Joseph

 

From: Travis Roth [mailto:[hidden email]]
Sent: Thursday, June 22, 2017 8:52 AM
To: 'NVDA screen reader development' <[hidden email]>
Subject: Re: [Nvda-devel] Add-on development guide: June 2017 revision is ready

 

Hi,

Thanks for this work, it is starting to look quite useful.

I am listing out a few observations and suggestions from my first read of today’s version for consideration. I hope this helps.

 

Example 3: Announce the automation ID of a UIA object:

the code appears on one line, it appears it is not in a <pre> tag?

 

Examples of overlay classes and modified roles:

The first example of modifying a Delphi window does not indicate where the constant ROLE_WINDOW comes from. I realize it was covered earlier to import from controltypes but this seems it'd be helpful to include for completeness.

 

Input and output: scripts and UI messages:

a) It would be helpful somewhere in this section to note what modifiers are available to be used as shortcuts, e.g., NVDA and Control. Any that do not work, e.g., Windows?

b) Also a slight explanation of the __gestures dictionary could help? When looking at "Example 2: A basic script dictionary and message output" the question that jumped at me was: is __gestures case sensitive? I noticed both "control" and "Control" being used, normally Python is case sensitive, so is this a problem?

c) A common question that I've seen come up is what happens to the gesture at the point the script receives it? And if NVDA uses it, how can I pass the keystroke on to the application as well? I assume by default NVDA uses the keystroke and does not pass it along which I think is normal for most screen readers, however, confirming this fact for the script writer would be nice.

 

Travis

 

From: Joseph Lee [[hidden email]]
Sent: Wednesday, June 21, 2017 3:04 PM
To: 'NVDA screen reader development' <[hidden email]>
Subject: [Nvda-devel] Add-on development guide: June 2017 revision is ready

 

Hi everyone,

 

June 2017 edition of the popular NVDA Add-on Development Guide is now up:

https://github.com/nvdaaddons/devguide/wiki/NVDA%20Add-on%20Development%20Guide

 

What’s new and changed:

  • Added ui.browsableMessage function.
  • Greatly expanded NVDA modules chapter to include various examples.
  • Added paragraphs on text infos and math presentation layer (mathPres). Mick Curran from NV Access provided an easy to follow explanation of text infos, which is a way to look at text in a widget via offsets and ranges.
  • Expanded Drivers chapter and added information on essential components of drivers for speech synthesizers and braille displays. I need to come up with an interesting driver example for folks to read.
  • Added several appendices, more on that below.
  • Ready for contributions from the wider community, including from scripters of other screen readers.

 

New in June 2017 edition is a set of appendices (two written, two in the works). These include:

  • Appendix A: definitions of terms used during add-on development and ones used by the add-ons community.
  • Appendix B: Python and programming concepts add-on writers will need to know.
  • Appendix C (coming soon): a table summarizing differences between various add-on types.
  • Appendix D (coming soon): references for scripters of other screen readers, a table that summarizes how to perform tasks via NVDA/Python that you were used to doing with other screen readers. This appendix is my contribution to Project Contact Lenses, and I’d like to request help from scripters in making sure this appendix is thorough and well done.

 

Thanks, and enjoy the documentation.

Cheers,

Joseph


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel
Reply | Threaded
Open this post in threaded view
|

Re: Add-on development guide: June 2017 revision is ready

James Scholes
Joseph Lee wrote:
> Gestures dictionary: yes, __gestures is case sensitive.

Travis was enquiring as to the case sensetivity of key and modifier
names when defining a gesture (rather than the name of the __gestures
attribute itself).  All gesture identifiers are ran through the
inputCore.normalizeGestureIdentifier function, which converts the string
to lower case and then sorts the key names by first character.

 >>> import inputCore
 >>> inputCore.normalizeGestureIdentifier('kb:NVDA+Shift+Control+S')
u'kb:control+nvda+s+shift'
 >>> inputCore.normalizeGestureIdentifier('kb:control+nvda+shift+s')
u'kb:control+nvda+s+shift'

As you can see, the casing and order of your keys and modifiers doesn't
matter, although for readability you probably want to include the NVDA
key at the beginning as is the custom.  This normalisation is performed
so that multiple scripts cannot be bound to the same gesture simply
because the case or order of keys was different.

Hope that helps.
--
James Scholes
http://twitter.com/JamesScholes

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel
Reply | Threaded
Open this post in threaded view
|

Re: Add-on development guide: June 2017 revision is ready

Joseph Lee
Hi,
Ah yes... I'll add a note about this in the guide (thanks for the reminder
on normalized gesture names).
Cheers,
Joseph

-----Original Message-----
From: James Scholes [mailto:[hidden email]]
Sent: Thursday, June 22, 2017 11:24 AM
To: [hidden email]
Subject: Re: [Nvda-devel] Add-on development guide: June 2017 revision is
ready

Joseph Lee wrote:
> Gestures dictionary: yes, __gestures is case sensitive.

Travis was enquiring as to the case sensetivity of key and modifier names
when defining a gesture (rather than the name of the __gestures attribute
itself).  All gesture identifiers are ran through the
inputCore.normalizeGestureIdentifier function, which converts the string to
lower case and then sorts the key names by first character.

 >>> import inputCore
 >>> inputCore.normalizeGestureIdentifier('kb:NVDA+Shift+Control+S')
u'kb:control+nvda+s+shift'
 >>> inputCore.normalizeGestureIdentifier('kb:control+nvda+shift+s')
u'kb:control+nvda+s+shift'

As you can see, the casing and order of your keys and modifiers doesn't
matter, although for readability you probably want to include the NVDA key
at the beginning as is the custom.  This normalisation is performed so that
multiple scripts cannot be bound to the same gesture simply because the case
or order of keys was different.

Hope that helps.
--
James Scholes
http://twitter.com/JamesScholes

----------------------------------------------------------------------------
--
Check out the vibrant tech community on one of the world's most engaging
tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel