Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

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

Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Joseph Lee

Dear NVDA community,

 

First, a huge thanks to NV Access and other presenters at NVDACon 2017, as well as those who organized and participated in this event. As the founder of NVDACon, I’m proud of what Derek Riemer and his friends have accomplished in organizing this successful gathering. To organizers of the 2018 gathering, I wish you the best of luck.

 

To the matter at hand:

 

Many of you may have heard about the end of sales for Window-Eyes screen reader. In the early 2000’s, Window-Eyes was considered a good alternative to JAWS for Windows when it came to using Microsoft Windows with screen readers. With the acquisition of GW Micro by AI Squared, which in turn was acquired by VFO last year, many analysts predicted the end of life for this screen reader, which occurred on May 15, 2017.

 

This news has huge implications for the global NVDA community, as well as opening opportunities for us. As many Window-Eyes users are eligible to upgrade to JAWS 18, some would choose to switch to NVDA. At the moment several individuals are producing tutorials aimed at helping Window-Eyes users transition to NVDA with ease. But users aren’t the only members of the Window-Eyes community: with the end of sales for Window-Eyes, many scripts (or apps) for Window-Eyes became unsupported, and it won’t be matter of time before they become part of history.

 

In hopes of inviting Window-Eyes users and developers to join the NVDA ecosystem (provided they are willing), I’d like to propose a community-wide initiative under the umbrella of Project Contact Lenses. Although this project may take different forms, the overall aim is to educate Window-Eyes community that NVDA is a viable option for many people, and a chance for writers of Window-Eyes apps to port their code to the add-ons infrastructure. Other activities may include equipping some Window-Eyes app developers to contribute code to NVDA Core, producing promotional materials, organizing online seminars and so on. Although the bulk of this project is aimed at Window-Eyes users, the ultimate goal is to embrace users of other screen readers to taste NVDA.

 

Some of the activities I plan to do include:

 

  • An online seminar or an intensive lab on creating add-ons and/or getting started with contributing code to NVDA Core.
  • Talking to Window-Eyes app writers about possibility of open-sourcing their code and helping them port apps to the add-ons infrastructure.

 

Some of the things the global community can do include:

 

  • Producing transition materials.
  • Contacting Window-Eyes distributors in your local community and inviting them to try NVDA.
  • Contacting script writers regarding apps and proposing add-ons.
  • Holding seminars aimed at users of other screen readers 9mostly Window-Eyes users) on how to master various NVDA concepts such as object navigation, browse mode and others.

 

As for the duration of this initiative, I don’t know, but I expect this to be at least several months or more.

 

Comments are appreciated.

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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Brian's Mail list account BY
Hi, I'd personally suggest looking up thecontact points of organisations who
advise blind people like RNIB in the UK for example. also there has to be a
list of window Eyes distributors somewhere.

Mailing lists as well.



Brian

[hidden email]
Sent via blueyonder.
Please address personal email to:-
[hidden email], putting 'Brian Gaff'
in the display name field.
----- Original Message -----
From: "Joseph Lee" <[hidden email]>
To: "'NVDA screen reader development'" <[hidden email]>
Sent: Sunday, May 28, 2017 2:19 AM
Subject: [Nvda-devel] Project Contact Lenses: a community initiative
proposal to invite more people to NVDA ecosystem


> Dear NVDA community,
>
>
>
> First, a huge thanks to NV Access and other presenters at NVDACon 2017, as
> well as those who organized and participated in this event. As the founder
> of NVDACon, I'm proud of what Derek Riemer and his friends have
> accomplished
> in organizing this successful gathering. To organizers of the 2018
> gathering, I wish you the best of luck.
>
>
>
> To the matter at hand:
>
>
>
> Many of you may have heard about the end of sales for Window-Eyes screen
> reader. In the early 2000's, Window-Eyes was considered a good alternative
> to JAWS for Windows when it came to using Microsoft Windows with screen
> readers. With the acquisition of GW Micro by AI Squared, which in turn was
> acquired by VFO last year, many analysts predicted the end of life for
> this
> screen reader, which occurred on May 15, 2017.
>
>
>
> This news has huge implications for the global NVDA community, as well as
> opening opportunities for us. As many Window-Eyes users are eligible to
> upgrade to JAWS 18, some would choose to switch to NVDA. At the moment
> several individuals are producing tutorials aimed at helping Window-Eyes
> users transition to NVDA with ease. But users aren't the only members of
> the
> Window-Eyes community: with the end of sales for Window-Eyes, many scripts
> (or apps) for Window-Eyes became unsupported, and it won't be matter of
> time
> before they become part of history.
>
>
>
> In hopes of inviting Window-Eyes users and developers to join the NVDA
> ecosystem (provided they are willing), I'd like to propose a
> community-wide
> initiative under the umbrella of Project Contact Lenses. Although this
> project may take different forms, the overall aim is to educate
> Window-Eyes
> community that NVDA is a viable option for many people, and a chance for
> writers of Window-Eyes apps to port their code to the add-ons
> infrastructure. Other activities may include equipping some Window-Eyes
> app
> developers to contribute code to NVDA Core, producing promotional
> materials,
> organizing online seminars and so on. Although the bulk of this project is
> aimed at Window-Eyes users, the ultimate goal is to embrace users of other
> screen readers to taste NVDA.
>
>
>
> Some of the activities I plan to do include:
>
>
>
> * An online seminar or an intensive lab on creating add-ons and/or
> getting started with contributing code to NVDA Core.
> * Talking to Window-Eyes app writers about possibility of
> open-sourcing their code and helping them port apps to the add-ons
> infrastructure.
>
>
>
> Some of the things the global community can do include:
>
>
>
> * Producing transition materials.
> * Contacting Window-Eyes distributors in your local community and
> inviting them to try NVDA.
> * Contacting script writers regarding apps and proposing add-ons.
> * Holding seminars aimed at users of other screen readers 9mostly
> Window-Eyes users) on how to master various NVDA concepts such as object
> navigation, browse mode and others.
>
>
>
> As for the duration of this initiative, I don't know, but I expect this to
> be at least several months or more.
>
>
>
> Comments are appreciated.
>
> 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
>


------------------------------------------------------------------------------
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Marlon Brandão de Sousa
In reply to this post by Joseph Lee

Joseph,


I was among the analysts who predicted the unfortunate end of Window Eyes.

The VFO fusion worries me a lot while a NVDA user because historically they have been extremely aggressive in legal terms against their main concurrents, and they main concurrents were the products that they have just acquired on the several fusions ... and now there remains only one concurrent and that's exactly NVDA.

Having the money and the power they do have I sincerely fear a lot about what might happen to the NVDA project but this is another question.

As for scripting, and I might very well cause some folks here to get a little uncomfortable, we do have a long way to go.

I am a somewhat experienced JAWS Scripter and also do have a basic knowledge of Window Eyes scripting and the one thing those products did in terms of scripting api is they separated the screen reading logic from the scripting api logic.

I understand that NVDA also does that, but in my opinion there should somehow be a more high level api.

As an example, in order to create a very basic addom I had to download the NVDA Source code and dig around several source files to try to find my way on the stuff I needed to use.
This is a signal that something is clearly wrong: a scripter should be able to accomplish everything provided by the core of the screen reader without having even to think how it is implemented.

JAWS scripting language, while having its failures, allowed several scripters to automate tasks that they would never be able to if they had to dig deep in c++ files (asusming the thing is written in c++ ) to find what and how they could use it.

Window-eyes has followed a similar path in the sense that its vb api is very high level and documented, meaning that one would be able to use a simpler interface to perform the tasks.

Now, I am not blaming or accusing nvda, I understand that this is the way the screen reader is coded, but I am instead asking if we couldn't somehow build a more high level api in order to welcome new scripters and users.

Thanks in advance and sorry if I offended someone..
Marlon


On 27/05/2017 22:19, Joseph Lee wrote:

Dear NVDA community,

 

First, a huge thanks to NV Access and other presenters at NVDACon 2017, as well as those who organized and participated in this event. As the founder of NVDACon, I’m proud of what Derek Riemer and his friends have accomplished in organizing this successful gathering. To organizers of the 2018 gathering, I wish you the best of luck.

 

To the matter at hand:

 

Many of you may have heard about the end of sales for Window-Eyes screen reader. In the early 2000’s, Window-Eyes was considered a good alternative to JAWS for Windows when it came to using Microsoft Windows with screen readers. With the acquisition of GW Micro by AI Squared, which in turn was acquired by VFO last year, many analysts predicted the end of life for this screen reader, which occurred on May 15, 2017.

 

This news has huge implications for the global NVDA community, as well as opening opportunities for us. As many Window-Eyes users are eligible to upgrade to JAWS 18, some would choose to switch to NVDA. At the moment several individuals are producing tutorials aimed at helping Window-Eyes users transition to NVDA with ease. But users aren’t the only members of the Window-Eyes community: with the end of sales for Window-Eyes, many scripts (or apps) for Window-Eyes became unsupported, and it won’t be matter of time before they become part of history.

 

In hopes of inviting Window-Eyes users and developers to join the NVDA ecosystem (provided they are willing), I’d like to propose a community-wide initiative under the umbrella of Project Contact Lenses. Although this project may take different forms, the overall aim is to educate Window-Eyes community that NVDA is a viable option for many people, and a chance for writers of Window-Eyes apps to port their code to the add-ons infrastructure. Other activities may include equipping some Window-Eyes app developers to contribute code to NVDA Core, producing promotional materials, organizing online seminars and so on. Although the bulk of this project is aimed at Window-Eyes users, the ultimate goal is to embrace users of other screen readers to taste NVDA.

 

Some of the activities I plan to do include:

 

  • An online seminar or an intensive lab on creating add-ons and/or getting started with contributing code to NVDA Core.
  • Talking to Window-Eyes app writers about possibility of open-sourcing their code and helping them port apps to the add-ons infrastructure.

 

Some of the things the global community can do include:

 

  • Producing transition materials.
  • Contacting Window-Eyes distributors in your local community and inviting them to try NVDA.
  • Contacting script writers regarding apps and proposing add-ons.
  • Holding seminars aimed at users of other screen readers 9mostly Window-Eyes users) on how to master various NVDA concepts such as object navigation, browse mode and others.

 

As for the duration of this initiative, I don’t know, but I expect this to be at least several months or more.

 

Comments are appreciated.

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


------------------------------------------------------------------------------
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Joseph Lee

Hi,

NVDA does expose various screen reading and navigation API’s such as obtaining focused control, working with text fields and what not. One thing that we could try is working on a more comprehensive API documentation (a bit more comprehensive than my add-on development guide) and make it available somewhere (the API docs can be generated easily; the issue is where to host it). I think the best we can try right now is host the complete NVDA module docs somewhere, and as soon as NVDA 2017.2 comes out, I’ll create a section on my site to host it.

Cheers,

Joseph

 

From: Marlon Brandão de Sousa [mailto:[hidden email]]
Sent: Sunday, May 28, 2017 10:25 AM
To: NVDA screen reader development <[hidden email]>
Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

 

Joseph,

 

I was among the analysts who predicted the unfortunate end of Window Eyes.

The VFO fusion worries me a lot while a NVDA user because historically they have been extremely aggressive in legal terms against their main concurrents, and they main concurrents were the products that they have just acquired on the several fusions ... and now there remains only one concurrent and that's exactly NVDA.

Having the money and the power they do have I sincerely fear a lot about what might happen to the NVDA project but this is another question.

As for scripting, and I might very well cause some folks here to get a little uncomfortable, we do have a long way to go.

I am a somewhat experienced JAWS Scripter and also do have a basic knowledge of Window Eyes scripting and the one thing those products did in terms of scripting api is they separated the screen reading logic from the scripting api logic.

I understand that NVDA also does that, but in my opinion there should somehow be a more high level api.

As an example, in order to create a very basic addom I had to download the NVDA Source code and dig around several source files to try to find my way on the stuff I needed to use.
This is a signal that something is clearly wrong: a scripter should be able to accomplish everything provided by the core of the screen reader without having even to think how it is implemented.

JAWS scripting language, while having its failures, allowed several scripters to automate tasks that they would never be able to if they had to dig deep in c++ files (asusming the thing is written in c++ ) to find what and how they could use it.

Window-eyes has followed a similar path in the sense that its vb api is very high level and documented, meaning that one would be able to use a simpler interface to perform the tasks.

Now, I am not blaming or accusing nvda, I understand that this is the way the screen reader is coded, but I am instead asking if we couldn't somehow build a more high level api in order to welcome new scripters and users.

Thanks in advance and sorry if I offended someone..
Marlon

On 27/05/2017 22:19, Joseph Lee wrote:

Dear NVDA community,

 

First, a huge thanks to NV Access and other presenters at NVDACon 2017, as well as those who organized and participated in this event. As the founder of NVDACon, I’m proud of what Derek Riemer and his friends have accomplished in organizing this successful gathering. To organizers of the 2018 gathering, I wish you the best of luck.

 

To the matter at hand:

 

Many of you may have heard about the end of sales for Window-Eyes screen reader. In the early 2000’s, Window-Eyes was considered a good alternative to JAWS for Windows when it came to using Microsoft Windows with screen readers. With the acquisition of GW Micro by AI Squared, which in turn was acquired by VFO last year, many analysts predicted the end of life for this screen reader, which occurred on May 15, 2017.

 

This news has huge implications for the global NVDA community, as well as opening opportunities for us. As many Window-Eyes users are eligible to upgrade to JAWS 18, some would choose to switch to NVDA. At the moment several individuals are producing tutorials aimed at helping Window-Eyes users transition to NVDA with ease. But users aren’t the only members of the Window-Eyes community: with the end of sales for Window-Eyes, many scripts (or apps) for Window-Eyes became unsupported, and it won’t be matter of time before they become part of history.

 

In hopes of inviting Window-Eyes users and developers to join the NVDA ecosystem (provided they are willing), I’d like to propose a community-wide initiative under the umbrella of Project Contact Lenses. Although this project may take different forms, the overall aim is to educate Window-Eyes community that NVDA is a viable option for many people, and a chance for writers of Window-Eyes apps to port their code to the add-ons infrastructure. Other activities may include equipping some Window-Eyes app developers to contribute code to NVDA Core, producing promotional materials, organizing online seminars and so on. Although the bulk of this project is aimed at Window-Eyes users, the ultimate goal is to embrace users of other screen readers to taste NVDA.

 

Some of the activities I plan to do include:

 

  • An online seminar or an intensive lab on creating add-ons and/or getting started with contributing code to NVDA Core.
  • Talking to Window-Eyes app writers about possibility of open-sourcing their code and helping them port apps to the add-ons infrastructure.

 

Some of the things the global community can do include:

 

  • Producing transition materials.
  • Contacting Window-Eyes distributors in your local community and inviting them to try NVDA.
  • Contacting script writers regarding apps and proposing add-ons.
  • Holding seminars aimed at users of other screen readers 9mostly Window-Eyes users) on how to master various NVDA concepts such as object navigation, browse mode and others.

 

As for the duration of this initiative, I don’t know, but I expect this to be at least several months or more.

 

Comments are appreciated.

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

 


------------------------------------------------------------------------------
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Marlon Brandão de Sousa

Joseph,


I tried to ask myself a simple question: where is the full list of events that can be handled e.e focusChanged, NewText, and such by NVDA?

And the response is I still do not know the complete list of events that I can handle. This would be exposed by JAWS on the function list on the script editor two clicks or one keystroke away from everyone trying to script.

I know that NVDA exposes several apis, but the thing is that a scripter with limited time and worried only with the tasks they have got to do in order to make some app more accessible would be in a hard situation trying to find quickly what they need to achieve their goal ...

We definitely should have better documentation. Can't we host it on github where everything else is being hosted?

What is the main barrier in order to host it? Infrastructure? Platform? Money? I ask because this is extremely needed now that NVDA is the only alternative to JAWS and that we need the new users and if we know the problem we might be able to think together in answers.

Marlon


On 28/05/2017 14:37, Joseph Lee wrote:

Hi,

NVDA does expose various screen reading and navigation API’s such as obtaining focused control, working with text fields and what not. One thing that we could try is working on a more comprehensive API documentation (a bit more comprehensive than my add-on development guide) and make it available somewhere (the API docs can be generated easily; the issue is where to host it). I think the best we can try right now is host the complete NVDA module docs somewhere, and as soon as NVDA 2017.2 comes out, I’ll create a section on my site to host it.

Cheers,

Joseph

 

From: Marlon Brandão de Sousa [[hidden email]]
Sent: Sunday, May 28, 2017 10:25 AM
To: NVDA screen reader development [hidden email]
Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

 

Joseph,

 

I was among the analysts who predicted the unfortunate end of Window Eyes.

The VFO fusion worries me a lot while a NVDA user because historically they have been extremely aggressive in legal terms against their main concurrents, and they main concurrents were the products that they have just acquired on the several fusions ... and now there remains only one concurrent and that's exactly NVDA.

Having the money and the power they do have I sincerely fear a lot about what might happen to the NVDA project but this is another question.

As for scripting, and I might very well cause some folks here to get a little uncomfortable, we do have a long way to go.

I am a somewhat experienced JAWS Scripter and also do have a basic knowledge of Window Eyes scripting and the one thing those products did in terms of scripting api is they separated the screen reading logic from the scripting api logic.

I understand that NVDA also does that, but in my opinion there should somehow be a more high level api.

As an example, in order to create a very basic addom I had to download the NVDA Source code and dig around several source files to try to find my way on the stuff I needed to use.
This is a signal that something is clearly wrong: a scripter should be able to accomplish everything provided by the core of the screen reader without having even to think how it is implemented.

JAWS scripting language, while having its failures, allowed several scripters to automate tasks that they would never be able to if they had to dig deep in c++ files (asusming the thing is written in c++ ) to find what and how they could use it.

Window-eyes has followed a similar path in the sense that its vb api is very high level and documented, meaning that one would be able to use a simpler interface to perform the tasks.

Now, I am not blaming or accusing nvda, I understand that this is the way the screen reader is coded, but I am instead asking if we couldn't somehow build a more high level api in order to welcome new scripters and users.

Thanks in advance and sorry if I offended someone..
Marlon

On 27/05/2017 22:19, Joseph Lee wrote:

Dear NVDA community,

 

First, a huge thanks to NV Access and other presenters at NVDACon 2017, as well as those who organized and participated in this event. As the founder of NVDACon, I’m proud of what Derek Riemer and his friends have accomplished in organizing this successful gathering. To organizers of the 2018 gathering, I wish you the best of luck.

 

To the matter at hand:

 

Many of you may have heard about the end of sales for Window-Eyes screen reader. In the early 2000’s, Window-Eyes was considered a good alternative to JAWS for Windows when it came to using Microsoft Windows with screen readers. With the acquisition of GW Micro by AI Squared, which in turn was acquired by VFO last year, many analysts predicted the end of life for this screen reader, which occurred on May 15, 2017.

 

This news has huge implications for the global NVDA community, as well as opening opportunities for us. As many Window-Eyes users are eligible to upgrade to JAWS 18, some would choose to switch to NVDA. At the moment several individuals are producing tutorials aimed at helping Window-Eyes users transition to NVDA with ease. But users aren’t the only members of the Window-Eyes community: with the end of sales for Window-Eyes, many scripts (or apps) for Window-Eyes became unsupported, and it won’t be matter of time before they become part of history.

 

In hopes of inviting Window-Eyes users and developers to join the NVDA ecosystem (provided they are willing), I’d like to propose a community-wide initiative under the umbrella of Project Contact Lenses. Although this project may take different forms, the overall aim is to educate Window-Eyes community that NVDA is a viable option for many people, and a chance for writers of Window-Eyes apps to port their code to the add-ons infrastructure. Other activities may include equipping some Window-Eyes app developers to contribute code to NVDA Core, producing promotional materials, organizing online seminars and so on. Although the bulk of this project is aimed at Window-Eyes users, the ultimate goal is to embrace users of other screen readers to taste NVDA.

 

Some of the activities I plan to do include:

 

  • An online seminar or an intensive lab on creating add-ons and/or getting started with contributing code to NVDA Core.
  • Talking to Window-Eyes app writers about possibility of open-sourcing their code and helping them port apps to the add-ons infrastructure.

 

Some of the things the global community can do include:

 

  • Producing transition materials.
  • Contacting Window-Eyes distributors in your local community and inviting them to try NVDA.
  • Contacting script writers regarding apps and proposing add-ons.
  • Holding seminars aimed at users of other screen readers 9mostly Window-Eyes users) on how to master various NVDA concepts such as object navigation, browse mode and others.

 

As for the duration of this initiative, I don’t know, but I expect this to be at least several months or more.

 

Comments are appreciated.

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

 



------------------------------------------------------------------------------
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
Reply | Threaded
Open this post in threaded view
|

Re: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Joseph Lee

Hi,

Take a look at the following guide:

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

As for hosting the API docs, it comes down to where to host. The ideal location is NV Access web server, as the resulting docs is placed in a self-contained folder.

 

As for events, a typical event uses the following syntax:

def event_eventName(self, obj, nextHandler)

A call to nextHandler function is necessary so other parts of NVDA (such as global plugins) can handle specific events from specific objects.

 

For reference, some of the most frequently handled events are:

  • gainFocus: called when a control receives focus.
  • loseFocus: focus moves away from a control.
  • nameChange: the name of an object has changed.
  • valueChange: value for controls such as combo boxes, edit fields and what not has changed.
  • stateChange: change of state such as checking checkboxes.

 

The following are used in specific modules:

  • NVDAObject_init: used in app modules to let you provide instructions on how an object should look like, as in changing names, roles and what not.
  • appModule_gainFocus: used to perform some actions when users switch to a specific app for which an app module is written for.
  • appModule_loseFocus: opposite of appModule_gainFocus.

 

API-specific:

  • UIA_controllerFor: used to respond to situations where auto-suggestions appear and disappear (under active testing in next branch).
  • UIA_windowOpened: respond to window opened event fired by UIA controls such as toasts in recent Windows 10 releases.

 

Internal NVDA events:

  • becomeNavigatorObject: this is used when a control becomes an object of interest to users, such as when moving through controls via object navigation. I just released a public preview of an add-on (called Object Location Tones) that handles this event and plays a tone to indicate object coordinates, and I wrote a more concrete implementation as part of NVDA Core ticket 2559.
  • documentLoadComplete: this is encountered on browse mode documents such as webpages where NVDA may wish to do something when the document is ready for reading.
  • suggestionsOpened: handles appearance of suggestions in various controls such as search box in Start menu in Windows 10. This is applicable in places such as appearance of auto-completion in Notepad++, InteliSense in Visual Studio code editor and others. I created this event as part of handling UIA controller for event in NVDA Core ticket 6241 and is under active testing.
  • suggestionsClosed: handles disappearance of suggestions, same story as suggestionsOpened event.

 

There are other internal (and external accessibility API-based events) out there, but the ones listed above are the ones frequently encountered in add-ons and other code.

Cheers,

Joseph

 

From: Marlon Brandão de Sousa [mailto:[hidden email]]
Sent: Sunday, May 28, 2017 11:17 AM
To: NVDA screen reader development <[hidden email]>
Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

 

Joseph,

 

I tried to ask myself a simple question: where is the full list of events that can be handled e.e focusChanged, NewText, and such by NVDA?

And the response is I still do not know the complete list of events that I can handle. This would be exposed by JAWS on the function list on the script editor two clicks or one keystroke away from everyone trying to script.

I know that NVDA exposes several apis, but the thing is that a scripter with limited time and worried only with the tasks they have got to do in order to make some app more accessible would be in a hard situation trying to find quickly what they need to achieve their goal ...

We definitely should have better documentation. Can't we host it on github where everything else is being hosted?

What is the main barrier in order to host it? Infrastructure? Platform? Money? I ask because this is extremely needed now that NVDA is the only alternative to JAWS and that we need the new users and if we know the problem we might be able to think together in answers.

Marlon

On 28/05/2017 14:37, Joseph Lee wrote:

Hi,

NVDA does expose various screen reading and navigation API’s such as obtaining focused control, working with text fields and what not. One thing that we could try is working on a more comprehensive API documentation (a bit more comprehensive than my add-on development guide) and make it available somewhere (the API docs can be generated easily; the issue is where to host it). I think the best we can try right now is host the complete NVDA module docs somewhere, and as soon as NVDA 2017.2 comes out, I’ll create a section on my site to host it.

Cheers,

Joseph

 

From: Marlon Brandão de Sousa [[hidden email]]
Sent: Sunday, May 28, 2017 10:25 AM
To: NVDA screen reader development [hidden email]
Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

 

Joseph,

 

I was among the analysts who predicted the unfortunate end of Window Eyes.

The VFO fusion worries me a lot while a NVDA user because historically they have been extremely aggressive in legal terms against their main concurrents, and they main concurrents were the products that they have just acquired on the several fusions ... and now there remains only one concurrent and that's exactly NVDA.

Having the money and the power they do have I sincerely fear a lot about what might happen to the NVDA project but this is another question.

As for scripting, and I might very well cause some folks here to get a little uncomfortable, we do have a long way to go.

I am a somewhat experienced JAWS Scripter and also do have a basic knowledge of Window Eyes scripting and the one thing those products did in terms of scripting api is they separated the screen reading logic from the scripting api logic.

I understand that NVDA also does that, but in my opinion there should somehow be a more high level api.

As an example, in order to create a very basic addom I had to download the NVDA Source code and dig around several source files to try to find my way on the stuff I needed to use.
This is a signal that something is clearly wrong: a scripter should be able to accomplish everything provided by the core of the screen reader without having even to think how it is implemented.

JAWS scripting language, while having its failures, allowed several scripters to automate tasks that they would never be able to if they had to dig deep in c++ files (asusming the thing is written in c++ ) to find what and how they could use it.

Window-eyes has followed a similar path in the sense that its vb api is very high level and documented, meaning that one would be able to use a simpler interface to perform the tasks.

Now, I am not blaming or accusing nvda, I understand that this is the way the screen reader is coded, but I am instead asking if we couldn't somehow build a more high level api in order to welcome new scripters and users.

Thanks in advance and sorry if I offended someone..
Marlon


On 27/05/2017 22:19, Joseph Lee wrote:

Dear NVDA community,

 

First, a huge thanks to NV Access and other presenters at NVDACon 2017, as well as those who organized and participated in this event. As the founder of NVDACon, I’m proud of what Derek Riemer and his friends have accomplished in organizing this successful gathering. To organizers of the 2018 gathering, I wish you the best of luck.

 

To the matter at hand:

 

Many of you may have heard about the end of sales for Window-Eyes screen reader. In the early 2000’s, Window-Eyes was considered a good alternative to JAWS for Windows when it came to using Microsoft Windows with screen readers. With the acquisition of GW Micro by AI Squared, which in turn was acquired by VFO last year, many analysts predicted the end of life for this screen reader, which occurred on May 15, 2017.

 

This news has huge implications for the global NVDA community, as well as opening opportunities for us. As many Window-Eyes users are eligible to upgrade to JAWS 18, some would choose to switch to NVDA. At the moment several individuals are producing tutorials aimed at helping Window-Eyes users transition to NVDA with ease. But users aren’t the only members of the Window-Eyes community: with the end of sales for Window-Eyes, many scripts (or apps) for Window-Eyes became unsupported, and it won’t be matter of time before they become part of history.

 

In hopes of inviting Window-Eyes users and developers to join the NVDA ecosystem (provided they are willing), I’d like to propose a community-wide initiative under the umbrella of Project Contact Lenses. Although this project may take different forms, the overall aim is to educate Window-Eyes community that NVDA is a viable option for many people, and a chance for writers of Window-Eyes apps to port their code to the add-ons infrastructure. Other activities may include equipping some Window-Eyes app developers to contribute code to NVDA Core, producing promotional materials, organizing online seminars and so on. Although the bulk of this project is aimed at Window-Eyes users, the ultimate goal is to embrace users of other screen readers to taste NVDA.

 

Some of the activities I plan to do include:

 

  • An online seminar or an intensive lab on creating add-ons and/or getting started with contributing code to NVDA Core.
  • Talking to Window-Eyes app writers about possibility of open-sourcing their code and helping them port apps to the add-ons infrastructure.

 

Some of the things the global community can do include:

 

  • Producing transition materials.
  • Contacting Window-Eyes distributors in your local community and inviting them to try NVDA.
  • Contacting script writers regarding apps and proposing add-ons.
  • Holding seminars aimed at users of other screen readers 9mostly Window-Eyes users) on how to master various NVDA concepts such as object navigation, browse mode and others.

 

As for the duration of this initiative, I don’t know, but I expect this to be at least several months or more.

 

Comments are appreciated.

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

 




------------------------------------------------------------------------------
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
Reply | Threaded
Open this post in threaded view
|

Re: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

James Scholes
In reply to this post by Joseph Lee
Joseph Lee wrote:
> NVDA does expose various screen reading and navigation API’s such as
> obtaining focused control, working with text fields and what not.

It's not really about what capabilities NVDA provides.  Rather, what
Marlon is refering to is the difference between the scripting services
provided by various screen readers and how they are implemented.  In
both JAWS and Window-Eyes, an interface is provided for developers to
script against, and they never have any direct access to the internals
of the program.

Naturally, this is not only due to their compiled nature, but also
because they are closed source.  Other programs which provide a plug-in
development SDK such as Winamp, foobar2000, Kodi etc. operate in a
similar way.  A developer wishing to add functionality to the product
only has access to the interfaces which have explicitly been made
available to them.

Contrast this approach to that taken by NVDA, which simply loads Python
code into the same operating environment as the screen reader itself,
allowing an add-on writer to not only access the program's internals but
also modify them.  Granted, in theory this allows add-ons to be as
powerful as they need to be, but if you're launching a project to get
people interested in developing NVDA add-ons who have previously worked
with closed systems like JAWS and Window-Eyes, this is an important
difference and one that people often struggle to get used to.

When you're writing a JAWS script and have forgotten a function name or
are not quite sure how to do something, you can browse through the
functions on offer and find what you need.  Naturally, if you don't find
it, you can call out to COM objects and whatever else.  But generally
speaking there is a defined set of behaviour which makes it relatively
easy to learn how to do things, combined with the JAWS Script Editor and
documentation which helps you along the way.

On the other hand, when you're not sure how to do something beyond the
basics in NVDA, your only port of call is the NVDA codebase itself.  I
speak from experience when I say that this can be daunting, to say the
least.

I don't write any of this to criticise NVAccess or anyone involved with
the NVDA ecosystem.  In fact it could be argued that, due to the
project's free and open source nature, the responsibility to lower the
barrier of entry to add-on development doesn't lie with NVAccess at all.
  Especially when you consider that all NVDA's code, including built-in
app modules is available to browse and experiment with.  But this
proposed community project is all about introducing new people to the
NVDA way, and it won't be successful if you:

A) Assume that everyone has the necessary level of experience of working
with Python and a large codebase to port their existing scripts; or
B) Fail to recognise that there are very real hurdles to jump over in
order to become familiar with developing for NVDA.

Regards.
--
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Rui Fontes
In reply to this post by Joseph Lee
Joseph

I have only some knowledge of BASIC programming language...
With Jaws script language, I have modified, and even createed some small
scripts, much more easily than I can in NVDA...
As Marlon said, we have access to majority, or all, Jaws functions and
events available...
And, in some cases, with simple if-then routines and simulation of key
presses and mouse mouvements, we make some apps or dialogs more usable...

I have already tried to enhance the NVDA support to Windows Live Mail, but
even with the help of an addon  I grabbed from the Net, I didn't managed
anything...

Rui

-----Mensagem Original-----
De: Joseph Lee
Data: 28 de maio de 2017 19:36
Para: 'NVDA screen reader development'
Assunto: Re: [Nvda-devel] Project Contact Lenses: a community initiative
proposal to invite more people to NVDA ecosystem



Hi,

Take a look at the following guide:

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

As for hosting the API docs, it comes down to where to host. The ideal
location is NV Access web server, as the resulting docs is placed in a
self-contained folder.



As for events, a typical event uses the following syntax:

def event_eventName(self, obj, nextHandler)

A call to nextHandler function is necessary so other parts of NVDA (such as
global plugins) can handle specific events from specific objects.



For reference, some of the most frequently handled events are:

gainFocus: called when a control receives focus.
loseFocus: focus moves away from a control.
nameChange: the name of an object has changed.
valueChange: value for controls such as combo boxes, edit fields and what
not has changed.
stateChange: change of state such as checking checkboxes.



The following are used in specific modules:

NVDAObject_init: used in app modules to let you provide instructions on how
an object should look like, as in changing names, roles and what not.
appModule_gainFocus: used to perform some actions when users switch to a
specific app for which an app module is written for.
appModule_loseFocus: opposite of appModule_gainFocus.



API-specific:

UIA_controllerFor: used to respond to situations where auto-suggestions
appear and disappear (under active testing in next branch).
UIA_windowOpened: respond to window opened event fired by UIA controls such
as toasts in recent Windows 10 releases.



Internal NVDA events:

becomeNavigatorObject: this is used when a control becomes an object of
interest to users, such as when moving through controls via object
navigation. I just released a public preview of an add-on (called Object
Location Tones) that handles this event and plays a tone to indicate object
coordinates, and I wrote a more concrete implementation as part of NVDA Core
ticket 2559.
documentLoadComplete: this is encountered on browse mode documents such as
webpages where NVDA may wish to do something when the document is ready for
reading.
suggestionsOpened: handles appearance of suggestions in various controls
such as search box in Start menu in Windows 10. This is applicable in places
such as appearance of auto-completion in Notepad++, InteliSense in Visual
Studio code editor and others. I created this event as part of handling UIA
controller for event in NVDA Core ticket 6241 and is under active testing.
suggestionsClosed: handles disappearance of suggestions, same story as
suggestionsOpened event.



There are other internal (and external accessibility API-based events) out
there, but the ones listed above are the ones frequently encountered in
add-ons and other code.

Cheers,

Joseph





From: Marlon Brandão de Sousa [mailto:[hidden email]]
Sent: Sunday, May 28, 2017 11:17 AM
To: NVDA screen reader development <[hidden email]>
Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative
proposal to invite more people to NVDA ecosystem





Joseph,



I tried to ask myself a simple question: where is the full list of events
that can be handled e.e focusChanged, NewText, and such by NVDA?

And the response is I still do not know the complete list of events that I
can handle. This would be exposed by JAWS on the function list on the script
editor two clicks or one keystroke away from everyone trying to script.

I know that NVDA exposes several apis, but the thing is that a scripter with
limited time and worried only with the tasks they have got to do in order to
make some app more accessible would be in a hard situation trying to find
quickly what they need to achieve their goal ...

We definitely should have better documentation. Can't we host it on github
where everything else is being hosted?

What is the main barrier in order to host it? Infrastructure? Platform?
Money? I ask because this is extremely needed now that NVDA is the only
alternative to JAWS and that we need the new users and if we know the
problem we might be able to think together in answers.

Marlon





On 28/05/2017 14:37, Joseph Lee wrote:



Hi,

NVDA does expose various screen reading and navigation API’s such as
obtaining focused control, working with text fields and what not. One thing
that we could try is working on a more comprehensive API documentation (a
bit more comprehensive than my add-on development guide) and make it
available somewhere (the API docs can be generated easily; the issue is
where to host it). I think the best we can try right now is host the
complete NVDA module docs somewhere, and as soon as NVDA 2017.2 comes out, I’ll
create a section on my site to host it.

Cheers,

Joseph





From: Marlon Brandão de Sousa [mailto:[hidden email]]
Sent: Sunday, May 28, 2017 10:25 AM
To: NVDA screen reader development mailto:[hidden email]
Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative
proposal to invite more people to NVDA ecosystem





Joseph,



I was among the analysts who predicted the unfortunate end of Window Eyes.

The VFO fusion worries me a lot while a NVDA user because historically they
have been extremely aggressive in legal terms against their main
concurrents, and they main concurrents were the products that they have just
acquired on the several fusions ... and now there remains only one
concurrent and that's exactly NVDA.

Having the money and the power they do have I sincerely fear a lot about
what might happen to the NVDA project but this is another question.

As for scripting, and I might very well cause some folks here to get a
little uncomfortable, we do have a long way to go.

I am a somewhat experienced JAWS Scripter and also do have a basic knowledge
of Window Eyes scripting and the one thing those products did in terms of
scripting api is they separated the screen reading logic from the scripting
api logic.

I understand that NVDA also does that, but in my opinion there should
somehow be a more high level api.

As an example, in order to create a very basic addom I had to download the
NVDA Source code and dig around several source files to try to find my way
on the stuff I needed to use.
This is a signal that something is clearly wrong: a scripter should be able
to accomplish everything provided by the core of the screen reader without
having even to think how it is implemented.

JAWS scripting language, while having its failures, allowed several
scripters to automate tasks that they would never be able to if they had to
dig deep in c++ files (asusming the thing is written in c++ ) to find what
and how they could use it.

Window-eyes has followed a similar path in the sense that its vb api is very
high level and documented, meaning that one would be able to use a simpler
interface to perform the tasks.

Now, I am not blaming or accusing nvda, I understand that this is the way
the screen reader is coded, but I am instead asking if we couldn't somehow
build a more high level api in order to welcome new scripters and users.

Thanks in advance and sorry if I offended someone..
Marlon






On 27/05/2017 22:19, Joseph Lee wrote:



Dear NVDA community,



First, a huge thanks to NV Access and other presenters at NVDACon 2017, as
well as those who organized and participated in this event. As the founder
of NVDACon, I’m proud of what Derek Riemer and his friends have accomplished
in organizing this successful gathering. To organizers of the 2018
gathering, I wish you the best of luck.



To the matter at hand:



Many of you may have heard about the end of sales for Window-Eyes screen
reader. In the early 2000’s, Window-Eyes was considered a good alternative
to JAWS for Windows when it came to using Microsoft Windows with screen
readers. With the acquisition of GW Micro by AI Squared, which in turn was
acquired by VFO last year, many analysts predicted the end of life for this
screen reader, which occurred on May 15, 2017.



This news has huge implications for the global NVDA community, as well as
opening opportunities for us. As many Window-Eyes users are eligible to
upgrade to JAWS 18, some would choose to switch to NVDA. At the moment
several individuals are producing tutorials aimed at helping Window-Eyes
users transition to NVDA with ease. But users aren’t the only members of the
Window-Eyes community: with the end of sales for Window-Eyes, many scripts
(or apps) for Window-Eyes became unsupported, and it won’t be matter of time
before they become part of history.



In hopes of inviting Window-Eyes users and developers to join the NVDA
ecosystem (provided they are willing), I’d like to propose a community-wide
initiative under the umbrella of Project Contact Lenses. Although this
project may take different forms, the overall aim is to educate Window-Eyes
community that NVDA is a viable option for many people, and a chance for
writers of Window-Eyes apps to port their code to the add-ons
infrastructure. Other activities may include equipping some Window-Eyes app
developers to contribute code to NVDA Core, producing promotional materials,
organizing online seminars and so on. Although the bulk of this project is
aimed at Window-Eyes users, the ultimate goal is to embrace users of other
screen readers to taste NVDA.



Some of the activities I plan to do include:



An online seminar or an intensive lab on creating add-ons and/or getting
started with contributing code to NVDA Core.
Talking to Window-Eyes app writers about possibility of open-sourcing their
code and helping them port apps to the add-ons infrastructure.



Some of the things the global community can do include:



Producing transition materials.
Contacting Window-Eyes distributors in your local community and inviting
them to try NVDA.
Contacting script writers regarding apps and proposing add-ons.
Holding seminars aimed at users of other screen readers 9mostly Window-Eyes
users) on how to master various NVDA concepts such as object navigation,
browse mode and others.



As for the duration of this initiative, I don’t know, but I expect this to
be at least several months or more.



Comments are appreciated.

Cheers,

Joseph







------------------------------------------------------------------------------Check
out the vibrant tech community on one of the world's mostengaging tech
sites, Slashdot.org! http://sdm.link/slashdot







_______________________________________________Nvda-devel mailing
[hidden email]://lists.sourceforge.net/lists/listinfo/nvda-devel








------------------------------------------------------------------------------Check
out the vibrant tech community on one of the world's mostengaging tech
sites, Slashdot.org! http://sdm.link/slashdot






_______________________________________________Nvda-devel mailing
[hidden email]://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 


------------------------------------------------------------------------------
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Noelia
Hi, just to say that I agree with James scholes opinions. In the other
hand, as a personal experience, I wrote Jaws scripts when I used that
screen reader, and now sometimes contribute add-ons and personally,
reading the developer guide and studying some parts of source code or
other specs, I find more interesting add-ons that JAWS scripts, and I
don't find this a very hard experience, though in fact they are two very
different ways to work.
Hope this project can continue.
Cheers.

El 28/05/2017 a las 21:02, Rui Fontes escribió:

> Joseph
>
> I have only some knowledge of BASIC programming language...
> With Jaws script language, I have modified, and even createed some small
> scripts, much more easily than I can in NVDA...
> As Marlon said, we have access to majority, or all, Jaws functions and
> events available...
> And, in some cases, with simple if-then routines and simulation of key
> presses and mouse mouvements, we make some apps or dialogs more usable...
>
> I have already tried to enhance the NVDA support to Windows Live Mail,
> but even with the help of an addon  I grabbed from the Net, I didn't
> managed anything...
>
> Rui
>
> -----Mensagem Original----- De: Joseph Lee
> Data: 28 de maio de 2017 19:36
> Para: 'NVDA screen reader development'
> Assunto: Re: [Nvda-devel] Project Contact Lenses: a community initiative
> proposal to invite more people to NVDA ecosystem
>
>
>
> Hi,
>
> Take a look at the following guide:
>
> https://github.com/nvdaaddons/devguide/wiki/NVDA%20Add-on%20Development%20Guide
>
>
> As for hosting the API docs, it comes down to where to host. The ideal
> location is NV Access web server, as the resulting docs is placed in a
> self-contained folder.
>
>
>
> As for events, a typical event uses the following syntax:
>
> def event_eventName(self, obj, nextHandler)
>
> A call to nextHandler function is necessary so other parts of NVDA (such
> as global plugins) can handle specific events from specific objects.
>
>
>
> For reference, some of the most frequently handled events are:
>
> gainFocus: called when a control receives focus.
> loseFocus: focus moves away from a control.
> nameChange: the name of an object has changed.
> valueChange: value for controls such as combo boxes, edit fields and
> what not has changed.
> stateChange: change of state such as checking checkboxes.
>
>
>
> The following are used in specific modules:
>
> NVDAObject_init: used in app modules to let you provide instructions on
> how an object should look like, as in changing names, roles and what not.
> appModule_gainFocus: used to perform some actions when users switch to a
> specific app for which an app module is written for.
> appModule_loseFocus: opposite of appModule_gainFocus.
>
>
>
> API-specific:
>
> UIA_controllerFor: used to respond to situations where auto-suggestions
> appear and disappear (under active testing in next branch).
> UIA_windowOpened: respond to window opened event fired by UIA controls
> such as toasts in recent Windows 10 releases.
>
>
>
> Internal NVDA events:
>
> becomeNavigatorObject: this is used when a control becomes an object of
> interest to users, such as when moving through controls via object
> navigation. I just released a public preview of an add-on (called Object
> Location Tones) that handles this event and plays a tone to indicate
> object coordinates, and I wrote a more concrete implementation as part
> of NVDA Core ticket 2559.
> documentLoadComplete: this is encountered on browse mode documents such
> as webpages where NVDA may wish to do something when the document is
> ready for reading.
> suggestionsOpened: handles appearance of suggestions in various controls
> such as search box in Start menu in Windows 10. This is applicable in
> places such as appearance of auto-completion in Notepad++, InteliSense
> in Visual Studio code editor and others. I created this event as part of
> handling UIA controller for event in NVDA Core ticket 6241 and is under
> active testing.
> suggestionsClosed: handles disappearance of suggestions, same story as
> suggestionsOpened event.
>
>
>
> There are other internal (and external accessibility API-based events)
> out there, but the ones listed above are the ones frequently encountered
> in add-ons and other code.
>
> Cheers,
>
> Joseph
>
>
>
>
>
> From: Marlon Brandão de Sousa [mailto:[hidden email]]
> Sent: Sunday, May 28, 2017 11:17 AM
> To: NVDA screen reader development <[hidden email]>
> Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative
> proposal to invite more people to NVDA ecosystem
>
>
>
>
>
> Joseph,
>
>
>
> I tried to ask myself a simple question: where is the full list of
> events that can be handled e.e focusChanged, NewText, and such by NVDA?
>
> And the response is I still do not know the complete list of events that
> I can handle. This would be exposed by JAWS on the function list on the
> script editor two clicks or one keystroke away from everyone trying to
> script.
>
> I know that NVDA exposes several apis, but the thing is that a scripter
> with limited time and worried only with the tasks they have got to do in
> order to make some app more accessible would be in a hard situation
> trying to find quickly what they need to achieve their goal ...
>
> We definitely should have better documentation. Can't we host it on
> github where everything else is being hosted?
>
> What is the main barrier in order to host it? Infrastructure? Platform?
> Money? I ask because this is extremely needed now that NVDA is the only
> alternative to JAWS and that we need the new users and if we know the
> problem we might be able to think together in answers.
>
> Marlon
>
>
>
>
>
> On 28/05/2017 14:37, Joseph Lee wrote:
>
>
>
> Hi,
>
> NVDA does expose various screen reading and navigation API’s such as
> obtaining focused control, working with text fields and what not. One
> thing that we could try is working on a more comprehensive API
> documentation (a bit more comprehensive than my add-on development
> guide) and make it available somewhere (the API docs can be generated
> easily; the issue is where to host it). I think the best we can try
> right now is host the complete NVDA module docs somewhere, and as soon
> as NVDA 2017.2 comes out, I’ll create a section on my site to host it.
>
> Cheers,
>
> Joseph
>
>
>
>
>
> From: Marlon Brandão de Sousa [mailto:[hidden email]]
> Sent: Sunday, May 28, 2017 10:25 AM
> To: NVDA screen reader development mailto:[hidden email]
> Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative
> proposal to invite more people to NVDA ecosystem
>
>
>
>
>
> Joseph,
>
>
>
> I was among the analysts who predicted the unfortunate end of Window Eyes.
>
> The VFO fusion worries me a lot while a NVDA user because historically
> they have been extremely aggressive in legal terms against their main
> concurrents, and they main concurrents were the products that they have
> just acquired on the several fusions ... and now there remains only one
> concurrent and that's exactly NVDA.
>
> Having the money and the power they do have I sincerely fear a lot about
> what might happen to the NVDA project but this is another question.
>
> As for scripting, and I might very well cause some folks here to get a
> little uncomfortable, we do have a long way to go.
>
> I am a somewhat experienced JAWS Scripter and also do have a basic
> knowledge of Window Eyes scripting and the one thing those products did
> in terms of scripting api is they separated the screen reading logic
> from the scripting api logic.
>
> I understand that NVDA also does that, but in my opinion there should
> somehow be a more high level api.
>
> As an example, in order to create a very basic addom I had to download
> the NVDA Source code and dig around several source files to try to find
> my way on the stuff I needed to use.
> This is a signal that something is clearly wrong: a scripter should be
> able to accomplish everything provided by the core of the screen reader
> without having even to think how it is implemented.
>
> JAWS scripting language, while having its failures, allowed several
> scripters to automate tasks that they would never be able to if they had
> to dig deep in c++ files (asusming the thing is written in c++ ) to find
> what and how they could use it.
>
> Window-eyes has followed a similar path in the sense that its vb api is
> very high level and documented, meaning that one would be able to use a
> simpler interface to perform the tasks.
>
> Now, I am not blaming or accusing nvda, I understand that this is the
> way the screen reader is coded, but I am instead asking if we couldn't
> somehow build a more high level api in order to welcome new scripters
> and users.
>
> Thanks in advance and sorry if I offended someone..
> Marlon
>
>
>
>
>
>
> On 27/05/2017 22:19, Joseph Lee wrote:
>
>
>
> Dear NVDA community,
>
>
>
> First, a huge thanks to NV Access and other presenters at NVDACon 2017,
> as well as those who organized and participated in this event. As the
> founder of NVDACon, I’m proud of what Derek Riemer and his friends have
> accomplished in organizing this successful gathering. To organizers of
> the 2018 gathering, I wish you the best of luck.
>
>
>
> To the matter at hand:
>
>
>
> Many of you may have heard about the end of sales for Window-Eyes screen
> reader. In the early 2000’s, Window-Eyes was considered a good
> alternative to JAWS for Windows when it came to using Microsoft Windows
> with screen readers. With the acquisition of GW Micro by AI Squared,
> which in turn was acquired by VFO last year, many analysts predicted the
> end of life for this screen reader, which occurred on May 15, 2017.
>
>
>
> This news has huge implications for the global NVDA community, as well
> as opening opportunities for us. As many Window-Eyes users are eligible
> to upgrade to JAWS 18, some would choose to switch to NVDA. At the
> moment several individuals are producing tutorials aimed at helping
> Window-Eyes users transition to NVDA with ease. But users aren’t the
> only members of the Window-Eyes community: with the end of sales for
> Window-Eyes, many scripts (or apps) for Window-Eyes became unsupported,
> and it won’t be matter of time before they become part of history.
>
>
>
> In hopes of inviting Window-Eyes users and developers to join the NVDA
> ecosystem (provided they are willing), I’d like to propose a
> community-wide initiative under the umbrella of Project Contact Lenses.
> Although this project may take different forms, the overall aim is to
> educate Window-Eyes community that NVDA is a viable option for many
> people, and a chance for writers of Window-Eyes apps to port their code
> to the add-ons infrastructure. Other activities may include equipping
> some Window-Eyes app developers to contribute code to NVDA Core,
> producing promotional materials, organizing online seminars and so on.
> Although the bulk of this project is aimed at Window-Eyes users, the
> ultimate goal is to embrace users of other screen readers to taste NVDA.
>
>
>
> Some of the activities I plan to do include:
>
>
>
> An online seminar or an intensive lab on creating add-ons and/or getting
> started with contributing code to NVDA Core.
> Talking to Window-Eyes app writers about possibility of open-sourcing
> their code and helping them port apps to the add-ons infrastructure.
>
>
>
> Some of the things the global community can do include:
>
>
>
> Producing transition materials.
> Contacting Window-Eyes distributors in your local community and inviting
> them to try NVDA.
> Contacting script writers regarding apps and proposing add-ons.
> Holding seminars aimed at users of other screen readers 9mostly
> Window-Eyes users) on how to master various NVDA concepts such as object
> navigation, browse mode and others.
>
>
>
> As for the duration of this initiative, I don’t know, but I expect this
> to be at least several months or more.
>
>
>
> Comments are appreciated.
>
> Cheers,
>
> Joseph
>
>
>
>
>
>
>
> ------------------------------------------------------------------------------Check
> out the vibrant tech community on one of the world's mostengaging tech
> sites, Slashdot.org! http://sdm.link/slashdot
>
>
>
>
>
>
>
> _______________________________________________Nvda-devel mailing
> [hidden email]://lists.sourceforge.net/lists/listinfo/nvda-devel
>
>
>
>
>
>
>
>
>
> ------------------------------------------------------------------------------Check
> out the vibrant tech community on one of the world's mostengaging tech
> sites, Slashdot.org! http://sdm.link/slashdot
>
>
>
>
>
>
> _______________________________________________Nvda-devel mailing
> [hidden email]://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
>
> ------------------------------------------------------------------------------
>
> 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
Reply | Threaded
Open this post in threaded view
|

Re: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Cory Samaha-2
In reply to this post by James Scholes
James,

I think your message below expresses how many of us feel.  I will say that I was a Window-Eyes scripter.  When I began using NVDA a while back.  I subscribed to this list in hopes that I could figure out how to develop add-ons for NVDA as well.  I continued to point out on this list that the documentation is very much lacking for add-on development.  Indeed, NVAccess has a development guide, which describes the log viewer, the python console etc. and describes how to write some example scripts.  But if you want more information you need to hunt around through different documents that users have written.  I appreciate that users have taken the time to put together these documents and tutorials, but have you seen the Window-Eyes scripting manual?  It is a CHM file with all of the objects in a tree view.  You can then expand that tree view to see which events and methods belong to that object.  I appreciate that NVDA is much more powerful due to the fact that it is open source, but not having a document with some type of organization similar to the Window-Eyes scripting manual is going to turn people away very quickly, as it did for me.  Not to mention, there are some people who are not so much interested with the internals of NVDA, and simply want to learn the objects that are common in scripting an application.  This is especially true when you have people like Jamie, the head of NVAccess being very dismissive of my comments that better documentation is needed, and needs to stay updated with each release of NVDA.  This is currently not the case.  I disagree that this is not the responsibility of NVAccess.  I was able to learn how to operate NVDA very quickly due to its very simple and well-written manual.  But when I bring up documentation for NVDA add-on development on this list I feel that I am banging my head against a wall.  I apologize if this is a harsh tone to take, but you cannot continue to dismiss script developers of other screen readers who would like to switch to NVDA full time, but cannot do so because there is not one cohesive document which brings all of the add-on concepts together.  This is probably my biggest criticism of NVDA.

Regards,
Cory

> On May 28, 2017, at 2:44 PM, James Scholes <[hidden email]> wrote:
>
> Joseph Lee wrote:
>> NVDA does expose various screen reading and navigation API’s such as obtaining focused control, working with text fields and what not.
>
> It's not really about what capabilities NVDA provides.  Rather, what Marlon is refering to is the difference between the scripting services provided by various screen readers and how they are implemented.  In both JAWS and Window-Eyes, an interface is provided for developers to script against, and they never have any direct access to the internals of the program.
>
> Naturally, this is not only due to their compiled nature, but also because they are closed source.  Other programs which provide a plug-in development SDK such as Winamp, foobar2000, Kodi etc. operate in a similar way.  A developer wishing to add functionality to the product only has access to the interfaces which have explicitly been made available to them.
>
> Contrast this approach to that taken by NVDA, which simply loads Python code into the same operating environment as the screen reader itself, allowing an add-on writer to not only access the program's internals but also modify them.  Granted, in theory this allows add-ons to be as powerful as they need to be, but if you're launching a project to get people interested in developing NVDA add-ons who have previously worked with closed systems like JAWS and Window-Eyes, this is an important difference and one that people often struggle to get used to.
>
> When you're writing a JAWS script and have forgotten a function name or are not quite sure how to do something, you can browse through the functions on offer and find what you need.  Naturally, if you don't find it, you can call out to COM objects and whatever else.  But generally speaking there is a defined set of behaviour which makes it relatively easy to learn how to do things, combined with the JAWS Script Editor and documentation which helps you along the way.
>
> On the other hand, when you're not sure how to do something beyond the basics in NVDA, your only port of call is the NVDA codebase itself.  I speak from experience when I say that this can be daunting, to say the least.
>
> I don't write any of this to criticise NVAccess or anyone involved with the NVDA ecosystem.  In fact it could be argued that, due to the project's free and open source nature, the responsibility to lower the barrier of entry to add-on development doesn't lie with NVAccess at all.  Especially when you consider that all NVDA's code, including built-in app modules is available to browse and experiment with.  But this proposed community project is all about introducing new people to the NVDA way, and it won't be successful if you:
>
> A) Assume that everyone has the necessary level of experience of working with Python and a large codebase to port their existing scripts; or
> B) Fail to recognise that there are very real hurdles to jump over in order to become familiar with developing for NVDA.
>
> Regards.
> --
> 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
Reply | Threaded
Open this post in threaded view
|

Re: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Marlon Brandão de Sousa
In reply to this post by James Scholes
James said exactly what I think.


When we come to new people specially when we try to introduce NVDA usage
to the more comercial world where folks pay for scripters to make
corporation specific apps more usable, we have to acknowledge that
scripters must be able to make the majority of common tasks as fast as
they can knowing as little about the screen reader internals as they can.


Remember that scripts might have to extend the screen reader internals
but also in majority of cases they just have to automate stuff to
improve the user's productivity in an app he or she is using on its job
in order to be more productive.


If we want to introduce NVDA to more scriipters we should think in
providing a scripting service interface with common tasks.


For example, Josepj:


You said:


For reference, some of the most frequently handled events are:


I said:


I am a desperate scripter trying to make some functionalities of a given
software usable. I am running out of time and have no support from
developers so I decide to hook a window on every possible events or at
least based on a list of all events the reader can handle start to try
the most likely ones to be helpful.


I do not need to know that some of the events bla bla bla I need to know
the full complete list of events available to experiment with.


I have read your guide and I am extremely thankful for that, since I
would not have any where to start learning weren't by it but, again,
taking NVDA to a level where it is as easily customizable as other
screen readers are necessarily imposes that a scripting service api is
built.


Most part of AT consultants would not recomend a reader which imposes
scripters to know its internals for a corporation. The easier and faster
a reader can be customized either to automate stuff thus enhancing
productivity of employers or to extend itself providing access to
otherwise inaccessible software the more likely it will be recommended.


Thanks,

Marlon




On 28/05/2017 15:44, James Scholes wrote:

> Joseph Lee wrote:
>> NVDA does expose various screen reading and navigation API’s such as
>> obtaining focused control, working with text fields and what not.
>
> It's not really about what capabilities NVDA provides.  Rather, what
> Marlon is refering to is the difference between the scripting services
> provided by various screen readers and how they are implemented.  In
> both JAWS and Window-Eyes, an interface is provided for developers to
> script against, and they never have any direct access to the internals
> of the program.
>
> Naturally, this is not only due to their compiled nature, but also
> because they are closed source.  Other programs which provide a
> plug-in development SDK such as Winamp, foobar2000, Kodi etc. operate
> in a similar way.  A developer wishing to add functionality to the
> product only has access to the interfaces which have explicitly been
> made available to them.
>
> Contrast this approach to that taken by NVDA, which simply loads
> Python code into the same operating environment as the screen reader
> itself, allowing an add-on writer to not only access the program's
> internals but also modify them.  Granted, in theory this allows
> add-ons to be as powerful as they need to be, but if you're launching
> a project to get people interested in developing NVDA add-ons who have
> previously worked with closed systems like JAWS and Window-Eyes, this
> is an important difference and one that people often struggle to get
> used to.
>
> When you're writing a JAWS script and have forgotten a function name
> or are not quite sure how to do something, you can browse through the
> functions on offer and find what you need.  Naturally, if you don't
> find it, you can call out to COM objects and whatever else.  But
> generally speaking there is a defined set of behaviour which makes it
> relatively easy to learn how to do things, combined with the JAWS
> Script Editor and documentation which helps you along the way.
>
> On the other hand, when you're not sure how to do something beyond the
> basics in NVDA, your only port of call is the NVDA codebase itself.  I
> speak from experience when I say that this can be daunting, to say the
> least.
>
> I don't write any of this to criticise NVAccess or anyone involved
> with the NVDA ecosystem.  In fact it could be argued that, due to the
> project's free and open source nature, the responsibility to lower the
> barrier of entry to add-on development doesn't lie with NVAccess at
> all.  Especially when you consider that all NVDA's code, including
> built-in app modules is available to browse and experiment with.  But
> this proposed community project is all about introducing new people to
> the NVDA way, and it won't be successful if you:
>
> A) Assume that everyone has the necessary level of experience of
> working with Python and a large codebase to port their existing
> scripts; or
> B) Fail to recognise that there are very real hurdles to jump over in
> order to become familiar with developing for NVDA.
>
> Regards.


------------------------------------------------------------------------------
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Marlon Brandão de Sousa
In reply to this post by Cory Samaha-2
Agreed.


Scripters do not have to be experts on screen reader implementations. If
they had to, then the script concept itself would not apply since then
script code could be considered part of the screen reader source code
itself .. scripting necessarily means that someone more focused on
tracking the behavior of the scripted app than on the screen reader
internals must be able to provide commands to the screen reader
programatically and acquire

information to process on the behalf of the user. It is a very different
domain model than the one used by screen reader developers.

Even if one disagrees with that, this is the way things are at the
moment for window-eyes and jaws users and scripters.
On 28/05/2017 19:03, Cory Samaha wrote:

> James,
>
> I think your message below expresses how many of us feel.  I will say that I was a Window-Eyes scripter.  When I began using NVDA a while back.  I subscribed to this list in hopes that I could figure out how to develop add-ons for NVDA as well.  I continued to point out on this list that the documentation is very much lacking for add-on development.  Indeed, NVAccess has a development guide, which describes the log viewer, the python console etc. and describes how to write some example scripts.  But if you want more information you need to hunt around through different documents that users have written.  I appreciate that users have taken the time to put together these documents and tutorials, but have you seen the Window-Eyes scripting manual?  It is a CHM file with all of the objects in a tree view.  You can then expand that tree view to see which events and methods belong to that object.  I appreciate that NVDA is much more powerful due to the fact that it is open source, but not having a document with some type of organization similar to the Window-Eyes scripting manual is going to turn people away very quickly, as it did for me.  Not to mention, there are some people who are not so much interested with the internals of NVDA, and simply want to learn the objects that are common in scripting an application.  This is especially true when you have people like Jamie, the head of NVAccess being very dismissive of my comments that better documentation is needed, and needs to stay updated with each release of NVDA.  This is currently not the case.  I disagree that this is not the responsibility of NVAccess.  I was able to learn how to operate NVDA very quickly due to its very simple and well-written manual.  But when I bring up documentation for NVDA add-on development on this list I feel that I am banging my head against a wall.  I apologize if this is a harsh tone to take, but you cannot continue to dismiss script developers of other screen readers who would like to switch to NVDA full time, but cannot do so because there is not one cohesive document which brings all of the add-on concepts together.  This is probably my biggest criticism of NVDA.
>
> Regards,
> Cory
>> On May 28, 2017, at 2:44 PM, James Scholes <[hidden email]> wrote:
>>
>> Joseph Lee wrote:
>>> NVDA does expose various screen reading and navigation API’s such as obtaining focused control, working with text fields and what not.
>> It's not really about what capabilities NVDA provides.  Rather, what Marlon is refering to is the difference between the scripting services provided by various screen readers and how they are implemented.  In both JAWS and Window-Eyes, an interface is provided for developers to script against, and they never have any direct access to the internals of the program.
>>
>> Naturally, this is not only due to their compiled nature, but also because they are closed source.  Other programs which provide a plug-in development SDK such as Winamp, foobar2000, Kodi etc. operate in a similar way.  A developer wishing to add functionality to the product only has access to the interfaces which have explicitly been made available to them.
>>
>> Contrast this approach to that taken by NVDA, which simply loads Python code into the same operating environment as the screen reader itself, allowing an add-on writer to not only access the program's internals but also modify them.  Granted, in theory this allows add-ons to be as powerful as they need to be, but if you're launching a project to get people interested in developing NVDA add-ons who have previously worked with closed systems like JAWS and Window-Eyes, this is an important difference and one that people often struggle to get used to.
>>
>> When you're writing a JAWS script and have forgotten a function name or are not quite sure how to do something, you can browse through the functions on offer and find what you need.  Naturally, if you don't find it, you can call out to COM objects and whatever else.  But generally speaking there is a defined set of behaviour which makes it relatively easy to learn how to do things, combined with the JAWS Script Editor and documentation which helps you along the way.
>>
>> On the other hand, when you're not sure how to do something beyond the basics in NVDA, your only port of call is the NVDA codebase itself.  I speak from experience when I say that this can be daunting, to say the least.
>>
>> I don't write any of this to criticise NVAccess or anyone involved with the NVDA ecosystem.  In fact it could be argued that, due to the project's free and open source nature, the responsibility to lower the barrier of entry to add-on development doesn't lie with NVAccess at all.  Especially when you consider that all NVDA's code, including built-in app modules is available to browse and experiment with.  But this proposed community project is all about introducing new people to the NVDA way, and it won't be successful if you:
>>
>> A) Assume that everyone has the necessary level of experience of working with Python and a large codebase to port their existing scripts; or
>> B) Fail to recognise that there are very real hurdles to jump over in order to become familiar with developing for NVDA.
>>
>> Regards.
>> --
>> 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



------------------------------------------------------------------------------
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

James Teh
A few points in response to this thread:
  1. Digging into NVDA"internals" is not a requirement for most add-on tasks. For example, NVDAObjects, TextInfos, the overlay class infrastructure, etc. are all public API and are intended to be used by add-on developers. We don't see them as "internal". Changing the name or role of an object is different to just speaking or brailling something different (as is often done in, say, JAWS), but it's also a lot more versatile (if you change the name, it applies to both speech and braille, it gets reported when you query the focus, etc.).
  2. There are some advanced cases that do require digging into internals, monkey patching, etc. NVDA Remote is a good example of this; it wouldn't be possible at all without such things. That is a problem we need to fix.
  3. While a limited subset is documented in the Developer Guide, The public API I mentioned in point 1 is not easily discoverable outside of the code. This is not desirable and is something we need to fix. It is not our intent to always have add-on developers look at the code to discover the API and find its documentation.
  4. The events listed in the Developer Guide are really the only events you can rely on seeing for all objects. There are probably a couple we've missed which should be added; "show" comes to mind (though that needs some additional explanation, since it has to be selectively enabled). We should remove the statement about there being many other events, since that's heading into territory which requires knowledge of the various accessibility APIs.
  5. Having said that, there are some cases (more than I'd like) that inherently require knowledge of accessibility APIs and Win32 concepts, regardless of the screen reader you're scripting. When you're dealing with raw Win32 and COM, it makes far more sense to just call those functions directly using ctypes ro comtypes, since you can learn from MSDN when dealing with such things; they are not NVDA specific (or even specific to screen readers). JAWS allows you to get raw MSAA objects, for example. The only reason it wraps Win32 functions is that you can't access Windows dlls directly in JAWS, but they're usually a pretty thin wrapper around the corresponding Win32 function.
  6. I don't recall being "dismissive" about the need for additional documentation. On the contrary, I've always stated this was an area that needed significant improvement.
  7. With regard to creating a proper API reference, I'm starting to think we need to look at a solution other than epydoc. The problem with epydoc is that it doesn't allow us to hide some of the more obscure implementation details. For example, epydoc doesn't know that _get_name actually creates a property called name; the caller shouldn't call it as _get_name. Also, we can't easily split a class into logical sections; e.g. we might want a section for callers of a class and a section for implementers (people subclassing it).
Jamie


------------------------------------------------------------------------------
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Joseph Lee
In reply to this post by Cory Samaha-2
Hi Cory and others,
Thanks for speaking up regarding documentation, attitudes and what not.
One thing I'll promise you: within 24 hours after the release of NVDA 2017.2, I will post a link to an online version of the complete developers guide that includes module hierarchy documentation and what not. I will also hold an online seminar with scripters of other screen readers before end of summer in hopes of starting a dialogue between you and the larger NVDA community regarding what we can do better.
In regards to learning curve: yes, some adjustments must be made from both sides: scripters of other screen readers, and in the NVDA development community. I know that we the NVDA community members have been concentrating on some things to a point where we have neglected to engage with other audience members, so I'd like to apologize for not taking care of needs of external developers when we should have been better. First and foremost, as a code contributor and a community add-on reviewer, I will personally make sure that you all have one of the greatest documentation suite available. Second, I will personally make sure that needs of novice programmers are not forgotten, as you make up a sizable part of this community. Third, I will personally make sure that you are equipped to teach others in the end through opportunities to coach future novice developers.
I myself take documentation seriously. I believe that what makes a good product even greater is a good documentation suite, and as a contributor with documentation experience, I will make sure that you too have a great experience when it comes to learning more about NVDA development and as you pass on your knowledge.
To Mick and Jamie: although seasoned NVDA devs know that writing add-ons require effort and that folks will need to have some knowledge of Python, I'd like to request that we think about a need to document things and make our source code/documentation one of the finest in this industry. I'm not advocating that all functions and classes should be documented - I'm thinking more towards public functions and classes every developer will need to know (not just api.getFocusObject or ui.browsableMessage, but also things such as what UIA is and some issues we've found, app modules and what not). Yes, I'm bringing up an old topic, but I think we cannot ignore this issue of documentation anymore. If I have to, I will let #2559 slip to NVDA 2017.4 in favor of working all summer on making our source code dev docs great again for the sake of not only NV Access and existing community members, but also for external devs and future researchers.
Thanks.
Cheers,
Joseph

-----Original Message-----
From: Cory Samaha [mailto:[hidden email]]
Sent: Sunday, May 28, 2017 3:04 PM
To: NVDA screen reader development <[hidden email]>
Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

James,

I think your message below expresses how many of us feel.  I will say that I was a Window-Eyes scripter.  When I began using NVDA a while back.  I subscribed to this list in hopes that I could figure out how to develop add-ons for NVDA as well.  I continued to point out on this list that the documentation is very much lacking for add-on development.  Indeed, NVAccess has a development guide, which describes the log viewer, the python console etc. and describes how to write some example scripts.  But if you want more information you need to hunt around through different documents that users have written.  I appreciate that users have taken the time to put together these documents and tutorials, but have you seen the Window-Eyes scripting manual?  It is a CHM file with all of the objects in a tree view.  You can then expand that tree view to see which events and methods belong to that object.  I appreciate that NVDA is much more powerful due to the fact that it is open source, but not having a document with some type of organization similar to the Window-Eyes scripting manual is going to turn people away very quickly, as it did for me.  Not to mention, there are some people who are not so much interested with the internals of NVDA, and simply want to learn the objects that are common in scripting an application.  This is especially true when you have people like Jamie, the head of NVAccess being very dismissive of my comments that better documentation is needed, and needs to stay updated with each release of NVDA.  This is currently not the case.  I disagree that this is not the responsibility of NVAccess.  I was able to learn how to operate NVDA very quickly due to its very simple and well-written manual.  But when I bring up documentation for NVDA add-on development on this list I feel that I am banging my head against a wall.  I apologize if this is a harsh tone to take, but you cannot continue to dismiss script developers of other screen readers who would like to switch to NVDA full time, but cannot do so because there is not one cohesive document which brings all of the add-on concepts together.  This is probably my biggest criticism of NVDA.

Regards,
Cory

> On May 28, 2017, at 2:44 PM, James Scholes <[hidden email]> wrote:
>
> Joseph Lee wrote:
>> NVDA does expose various screen reading and navigation API’s such as obtaining focused control, working with text fields and what not.
>
> It's not really about what capabilities NVDA provides.  Rather, what Marlon is refering to is the difference between the scripting services provided by various screen readers and how they are implemented.  In both JAWS and Window-Eyes, an interface is provided for developers to script against, and they never have any direct access to the internals of the program.
>
> Naturally, this is not only due to their compiled nature, but also because they are closed source.  Other programs which provide a plug-in development SDK such as Winamp, foobar2000, Kodi etc. operate in a similar way.  A developer wishing to add functionality to the product only has access to the interfaces which have explicitly been made available to them.
>
> Contrast this approach to that taken by NVDA, which simply loads Python code into the same operating environment as the screen reader itself, allowing an add-on writer to not only access the program's internals but also modify them.  Granted, in theory this allows add-ons to be as powerful as they need to be, but if you're launching a project to get people interested in developing NVDA add-ons who have previously worked with closed systems like JAWS and Window-Eyes, this is an important difference and one that people often struggle to get used to.
>
> When you're writing a JAWS script and have forgotten a function name or are not quite sure how to do something, you can browse through the functions on offer and find what you need.  Naturally, if you don't find it, you can call out to COM objects and whatever else.  But generally speaking there is a defined set of behaviour which makes it relatively easy to learn how to do things, combined with the JAWS Script Editor and documentation which helps you along the way.
>
> On the other hand, when you're not sure how to do something beyond the basics in NVDA, your only port of call is the NVDA codebase itself.  I speak from experience when I say that this can be daunting, to say the least.
>
> I don't write any of this to criticise NVAccess or anyone involved with the NVDA ecosystem.  In fact it could be argued that, due to the project's free and open source nature, the responsibility to lower the barrier of entry to add-on development doesn't lie with NVAccess at all.  Especially when you consider that all NVDA's code, including built-in app modules is available to browse and experiment with.  But this proposed community project is all about introducing new people to the NVDA way, and it won't be successful if you:
>
> A) Assume that everyone has the necessary level of experience of
> working with Python and a large codebase to port their existing
> scripts; or
> B) Fail to recognise that there are very real hurdles to jump over in order to become familiar with developing for NVDA.
>
> Regards.
> --
> 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


------------------------------------------------------------------------------
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Joseph Lee
In reply to this post by James Teh

Hi,

I should have read this reply before posting mine…

I think what could be an improvement might be a way to insert a blurb about NVDA in index.html and providing links to various MSDN and other tech articles in our source code for reference that can be picked up by whatever documentation generator we will use.

Cheers,

Joseph

 

 

From: James Teh [mailto:[hidden email]]
Sent: Sunday, May 28, 2017 5:58 PM
To: NVDA screen reader development <[hidden email]>
Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

 

A few points in response to this thread:

  1. Digging into NVDA"internals" is not a requirement for most add-on tasks. For example, NVDAObjects, TextInfos, the overlay class infrastructure, etc. are all public API and are intended to be used by add-on developers. We don't see them as "internal". Changing the name or role of an object is different to just speaking or brailling something different (as is often done in, say, JAWS), but it's also a lot more versatile (if you change the name, it applies to both speech and braille, it gets reported when you query the focus, etc.).
  2. There are some advanced cases that do require digging into internals, monkey patching, etc. NVDA Remote is a good example of this; it wouldn't be possible at all without such things. That is a problem we need to fix.
  3. While a limited subset is documented in the Developer Guide, The public API I mentioned in point 1 is not easily discoverable outside of the code. This is not desirable and is something we need to fix. It is not our intent to always have add-on developers look at the code to discover the API and find its documentation.
  4. The events listed in the Developer Guide are really the only events you can rely on seeing for all objects. There are probably a couple we've missed which should be added; "show" comes to mind (though that needs some additional explanation, since it has to be selectively enabled). We should remove the statement about there being many other events, since that's heading into territory which requires knowledge of the various accessibility APIs.
  5. Having said that, there are some cases (more than I'd like) that inherently require knowledge of accessibility APIs and Win32 concepts, regardless of the screen reader you're scripting. When you're dealing with raw Win32 and COM, it makes far more sense to just call those functions directly using ctypes ro comtypes, since you can learn from MSDN when dealing with such things; they are not NVDA specific (or even specific to screen readers). JAWS allows you to get raw MSAA objects, for example. The only reason it wraps Win32 functions is that you can't access Windows dlls directly in JAWS, but they're usually a pretty thin wrapper around the corresponding Win32 function.
  6. I don't recall being "dismissive" about the need for additional documentation. On the contrary, I've always stated this was an area that needed significant improvement.
  7. With regard to creating a proper API reference, I'm starting to think we need to look at a solution other than epydoc. The problem with epydoc is that it doesn't allow us to hide some of the more obscure implementation details. For example, epydoc doesn't know that _get_name actually creates a property called name; the caller shouldn't call it as _get_name. Also, we can't easily split a class into logical sections; e.g. we might want a section for callers of a class and a section for implementers (people subclassing it).

Jamie

 


------------------------------------------------------------------------------
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Marlon Brandão de Sousa
In reply to this post by James Teh

James,


I am being a kind of scripters lawyer here to generate a debate.

With this in mind, find my responses below:

On 28/05/2017 21:57, James Teh wrote:
A few points in response to this thread:
  1. Digging into NVDA"internals" is not a requirement for most add-on tasks. For example, NVDAObjects, TextInfos, the overlay class infrastructure, etc. are all public API and are intended to be used by add-on developers. We don't see them as "internal". Changing the name or role of an object is different to just speaking or brailling something different (as is often done in, say, JAWS), but it's also a lot more versatile (if you change the name, it applies to both speech and braille, it gets reported when you query the focus, etc.).

Marlon: Great!We do need a doc or tutorial where this difference is made clear. I myself didn't realize that until now. Sure if I had looked at the source more carefully and with more time I would reach to this, but again scripters often shouldn't need to dig deeply to understand things, this is why they are scripts and not maintainers.

There are some advanced cases that do require digging into internals, monkey patching, etc. NVDA Remote is a good example of this; it wouldn't be possible at all without such things. That is a problem we need to fix.

Marlon: Perfect. What I really miss is an utility like the home row (talking too much about JAWS I know) but it was such a dream to walk down a structure and listen to several aspects of windows I could use to automate stuff.
When I think about scripting, at least to make most part of stuff more usable, what comes to mind is navigating and finding objects, analyzing objects stat and making the reader act accordingly either by sending the application some commands, performing some commands on the screen reader or making the screen reader speak info. This combined with hooking on events fired on some objects is usually what most part of scripts will do.

While a limited subset is documented in the Developer Guide, The public API I mentioned in point 1 is not easily discoverable outside of the code. This is not desirable and is something we need to fix. It is not our intent to always have add-on developers look at the code to discover the API and find its documentation.

Marlon: James, do you see how this point contradicts your first point saying that Digging into NVDA"internals" is not a requirement for most add-on tasks ? If it is nnnot easily discoverable outside of the code then I have to dig in the code to find it. And if I have to dig in the code to find it then digging into the code is a requirement to perform even basic addom tasks. When I say that scripters have to dig in the code I am not saying that they have to modify something deep in the code, I am ratter saying that they have to dig into the code to find what they could  use and in turn I am making a point that a scripting service api would set them free of doing that.

The events listed in the Developer Guide are really the only events you can rely on seeing for all objects. There are probably a couple we've missed which should be added; "show" comes to mind (though that needs some additional explanation, since it has to be selectively enabled). We should remove the statement about there being many other events, since that's heading into territory which requires knowledge of the various accessibility APIs.

Marlon: I do not recall the guide saying nothing about some events I consider basic for scripting. Among them I can easy list NewTextEvent and others. There might have ** and I am sure we do have ** other ways to simulate or use these events. If we expect scripters using a more high level api to come to nvda, we should document a guide which explains in easy terms how to provide equivalent functionalities to those events.
In a similar way, finding objects ** the thing similar to find Windows in other scripting languages is somewhat obscure ** and this is one of the main aspects of scripting we should address.

Having said that, there are some cases (more than I'd like) that inherently require knowledge of accessibility APIs and Win32 concepts, regardless of the screen reader you're scripting. When you're dealing with raw Win32 and COM, it makes far more sense to just call those functions directly using ctypes ro comtypes, since you can learn from MSDN when dealing with such things; they are not NVDA specific (or even specific to screen readers). JAWS allows you to get raw MSAA objects, for example. The only reason it wraps Win32 functions is that you can't access Windows dlls directly in JAWS, but they're usually a pretty thin wrapper around the corresponding Win32 function.

Marlon: See, this is true from a technical stand point of view but not exactly from an api design point of view. I do not expect a common scripter to know how to call com+ components, having to import references and then create objects. Imagine if JAWS provided a module where you could define C functions and say export a array of structures with a field of type char* containing the name of the function and another containing the function pointer to the function. JAWS could import that module, search for the function name and call the associated function pointer. The scripter then could make its scripts directly in C and call the win32 and com+ functions and objects directly. Would it be possible? Certainly it would. But would we have many scripters? The response is no, because manipulating win32 and com+ functions and components involves a very big complexity. Instead, having simple wrappers around functions makes things viable. hWnd = getFocus(getMainWindow()) solves the problem. No pointers, no includes, no structs sent by reference, no nothing. I'd say these functions are wrappers ratter that they are * only wrappers. For the scripter it makes a huge difference.


I don't recall being "dismissive" about the need for additional documentation. On the contrary, I've always stated this was an area that needed significant improvement.

Marlon: Although I did not do that claim at least for me you have always been polite. No complains over here.

With regard to creating a proper API reference, I'm starting to think we need to look at a solution other than epydoc. The problem with epydoc is that it doesn't allow us to hide some of the more obscure implementation details. For example, epydoc doesn't know that _get_name actually creates a property called name; the caller shouldn't call it as _get_name. Also, we can't easily split a class into logical sections; e.g. we might want a section for callers of a class and a section for implementers (people subclassing it).

Marlon: I would make the following: I would ask scripters of NVDA what are the most hard parts of writting scripts and how other screen readers have solved that kind of problem. This would allow us to write an effective guide to help folks to achieve common tasks that they are pretty used to solve in a couple of lines on these readers and will hopefully facilitate migration of scripts that have already been written for other products to NVDA. This is also going to help maintainers to know how to keep improving documentation to scripters and it could be very effective.

Sorry for the long e-mail and I hope some of these thoughts can help.

Jamie



------------------------------------------------------------------------------
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
Reply | Threaded
Open this post in threaded view
|

Re: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

James Teh
Hi Marlon,

Just responding to a few of your points off the top of my head. Some others will need further thought.


On Mon, May 29, 2017 at 11:42 AM, Marlon Brandão de Sousa <[hidden email]> wrote:
While a limited subset is documented in the Developer Guide, The public API I mentioned in point 1 is not easily discoverable outside of the code. This is not desirable and is something we need to fix. It is not our intent to always have add-on developers look at the code to discover the API and find its documentation.

Marlon: James, do you see how this point contradicts your first point saying that Digging into NVDA"internals" is not a requirement for most add-on tasks ?
I think we're suffering from terminology differences here. :) When the word "internals" was used, I assumed you meant actually having to read the logic of the code itself or look at private methods (as opposed to looking at the source code to know what public classes, methods, etc. exist, what arguments they take, etc.). A lot of NVDA's public classes and methods do have "docstrings" (i.e. the sorts of things that would appear in generated API documentation, not just comments). These aren't internal in the sense that they would appear in generated API documentation. We both agree that having to open the source code to find these things is not ideal.

Marlon: I do not recall the guide saying nothing about some events I consider basic for scripting. Among them I can easy list NewTextEvent and others.
In NVDA, there is no generalised new text event; that event only exists if you use the LiveText behavior. The reason for this is that you can't generalise newTextEvent. In JAWS, newTextEvent refers to text written to the screen using GDI. Once upon a time, every app did this, so it made sense. It no longer does; try using newTextEvent in a modern UWP app or browser and you'll get absolutely nothing, and you'll possibly find it's unreliable in Windows Command consoles as well (though I'm not sure about this). The way you detect new text has to be different in these situations, so NVDA splits this out into different implementations you can choose, which also means you don't incur a performance hit in monitoring for new text when you don't actually need it. To cut a long story short, it's not a core event in NVDA; it's provided by an object. That's why it's not listed as a core event.

Having said that, LiveText is probably an important thing to document in the Developer Guide for cases which do need it.

In a similar way, finding objects ** the thing similar to find Windows in other scripting languages is somewhat obscure ** and this is one of the main aspects of scripting we should address.
If I remember correctly, JAWS had findDescendantWindow and findWindow. These map to windowUtils.findDescendantWindow and winUser.FindWindow in NVDA. However, here too, finding windows is simply not enough in the modern world. Firefox, Chrome and many other modern apps are all just one window. Unfortunately, there's no "simple" way to find objects at this level.

Marlon: See, this is true from a technical stand point of view but not exactly from an api design point of view. I do not expect a common scripter to know how to call com+ components, having to import references and then create objects.
On the contrary, in JAWS, if you create a COM object or get an MSAA object, you get the COM object. JAWS doesn't document the entirety of MSAA... and it can't know what COM objects the scripter might create, so it can't document all of those either. The scripter is expected to refer to the API documentation for the object they're using. NVDA takes this a step further perhaps with Win32... but the principle is the same: if you want to use the Win32 API, look at the Win32 API reference. It's worth noting that we do wrap functions with complex pointer arguments and we also provide common Windows data structures. (We also try to avoid people having to deal with Win32 at all wherever possible by hiding those details behind NVDAObjects. This stuff should only be necessary for complex scenarios.)

Jamie


------------------------------------------------------------------------------
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Cory Samaha-2
In reply to this post by Joseph Lee
Hi Joseph and all,
I won’t beat this subject any further.  At least, I will try not to, <smile>.  I just wanted to thank you, Joseph, for the work you have put in already, and for the continued work for documentation that many like myself have wanted for such a long time.  Coming from Window-Eyes we have many different objects such as Application, the root object, Braille, Cursor, Mouse, MSAA, Keyboard, Screen, Speech, Synthesizer, Window etc.  Each of those objects have their own methods which can be invoked or events which one can monitor.  That may not be how it works in NVDA - I’m not sure, but from reading over this thread, it sounds like NVDA only has a few events in comparison and perhaps the objects are more consolidated.  I have dealt with MSAA objects from the context of Window-Eyes even where I have imported the Window-Eyes object into a C++ application.  That is not a fun process, I promise.

Finally to Jamie, I apologize that I probably misinterpreted what you have said regarding documentation as being dismissive.  It just never seemed a high priority, and the responses I got from some people on this list who glibly said “well the API reference is in the source if you download it” were a bit discouraging.  I actually did get Git up and running and did download the source.  After playing around with it for a bit however, I realized I could get done what I wanted to do faster in other screen readers.  I would love to have a public scripting object model similar to the Window-Eyes model, but I realize that there are fundamental differences in these two applications and that it may not be possible.  In any case, I’m glad this is finally being discussed.

All the Best,
Cory

> On May 28, 2017, at 9:19 PM, Joseph Lee <[hidden email]> wrote:
>
> Hi Cory and others,
> Thanks for speaking up regarding documentation, attitudes and what not.
> One thing I'll promise you: within 24 hours after the release of NVDA 2017.2, I will post a link to an online version of the complete developers guide that includes module hierarchy documentation and what not. I will also hold an online seminar with scripters of other screen readers before end of summer in hopes of starting a dialogue between you and the larger NVDA community regarding what we can do better.
> In regards to learning curve: yes, some adjustments must be made from both sides: scripters of other screen readers, and in the NVDA development community. I know that we the NVDA community members have been concentrating on some things to a point where we have neglected to engage with other audience members, so I'd like to apologize for not taking care of needs of external developers when we should have been better. First and foremost, as a code contributor and a community add-on reviewer, I will personally make sure that you all have one of the greatest documentation suite available. Second, I will personally make sure that needs of novice programmers are not forgotten, as you make up a sizable part of this community. Third, I will personally make sure that you are equipped to teach others in the end through opportunities to coach future novice developers.
> I myself take documentation seriously. I believe that what makes a good product even greater is a good documentation suite, and as a contributor with documentation experience, I will make sure that you too have a great experience when it comes to learning more about NVDA development and as you pass on your knowledge.
> To Mick and Jamie: although seasoned NVDA devs know that writing add-ons require effort and that folks will need to have some knowledge of Python, I'd like to request that we think about a need to document things and make our source code/documentation one of the finest in this industry. I'm not advocating that all functions and classes should be documented - I'm thinking more towards public functions and classes every developer will need to know (not just api.getFocusObject or ui.browsableMessage, but also things such as what UIA is and some issues we've found, app modules and what not). Yes, I'm bringing up an old topic, but I think we cannot ignore this issue of documentation anymore. If I have to, I will let #2559 slip to NVDA 2017.4 in favor of working all summer on making our source code dev docs great again for the sake of not only NV Access and existing community members, but also for external devs and future researchers.
> Thanks.
> Cheers,
> Joseph
>
> -----Original Message-----
> From: Cory Samaha [mailto:[hidden email]]
> Sent: Sunday, May 28, 2017 3:04 PM
> To: NVDA screen reader development <[hidden email]>
> Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem
>
> James,
>
> I think your message below expresses how many of us feel.  I will say that I was a Window-Eyes scripter.  When I began using NVDA a while back.  I subscribed to this list in hopes that I could figure out how to develop add-ons for NVDA as well.  I continued to point out on this list that the documentation is very much lacking for add-on development.  Indeed, NVAccess has a development guide, which describes the log viewer, the python console etc. and describes how to write some example scripts.  But if you want more information you need to hunt around through different documents that users have written.  I appreciate that users have taken the time to put together these documents and tutorials, but have you seen the Window-Eyes scripting manual?  It is a CHM file with all of the objects in a tree view.  You can then expand that tree view to see which events and methods belong to that object.  I appreciate that NVDA is much more powerful due to the fact that it is open source, but not having a document with some type of organization similar to the Window-Eyes scripting manual is going to turn people away very quickly, as it did for me.  Not to mention, there are some people who are not so much interested with the internals of NVDA, and simply want to learn the objects that are common in scripting an application.  This is especially true when you have people like Jamie, the head of NVAccess being very dismissive of my comments that better documentation is needed, and needs to stay updated with each release of NVDA.  This is currently not the case.  I disagree that this is not the responsibility of NVAccess.  I was able to learn how to operate NVDA very quickly due to its very simple and well-written manual.  But when I bring up documentation for NVDA add-on development on this list I feel that I am banging my head against a wall.  I apologize if this is a harsh tone to take, but you cannot continue to dismiss script developers of other screen readers who would like to switch to NVDA full time, but cannot do so because there is not one cohesive document which brings all of the add-on concepts together.  This is probably my biggest criticism of NVDA.
>
> Regards,
> Cory
>> On May 28, 2017, at 2:44 PM, James Scholes <[hidden email]> wrote:
>>
>> Joseph Lee wrote:
>>> NVDA does expose various screen reading and navigation API’s such as obtaining focused control, working with text fields and what not.
>>
>> It's not really about what capabilities NVDA provides.  Rather, what Marlon is refering to is the difference between the scripting services provided by various screen readers and how they are implemented.  In both JAWS and Window-Eyes, an interface is provided for developers to script against, and they never have any direct access to the internals of the program.
>>
>> Naturally, this is not only due to their compiled nature, but also because they are closed source.  Other programs which provide a plug-in development SDK such as Winamp, foobar2000, Kodi etc. operate in a similar way.  A developer wishing to add functionality to the product only has access to the interfaces which have explicitly been made available to them.
>>
>> Contrast this approach to that taken by NVDA, which simply loads Python code into the same operating environment as the screen reader itself, allowing an add-on writer to not only access the program's internals but also modify them.  Granted, in theory this allows add-ons to be as powerful as they need to be, but if you're launching a project to get people interested in developing NVDA add-ons who have previously worked with closed systems like JAWS and Window-Eyes, this is an important difference and one that people often struggle to get used to.
>>
>> When you're writing a JAWS script and have forgotten a function name or are not quite sure how to do something, you can browse through the functions on offer and find what you need.  Naturally, if you don't find it, you can call out to COM objects and whatever else.  But generally speaking there is a defined set of behaviour which makes it relatively easy to learn how to do things, combined with the JAWS Script Editor and documentation which helps you along the way.
>>
>> On the other hand, when you're not sure how to do something beyond the basics in NVDA, your only port of call is the NVDA codebase itself.  I speak from experience when I say that this can be daunting, to say the least.
>>
>> I don't write any of this to criticise NVAccess or anyone involved with the NVDA ecosystem.  In fact it could be argued that, due to the project's free and open source nature, the responsibility to lower the barrier of entry to add-on development doesn't lie with NVAccess at all.  Especially when you consider that all NVDA's code, including built-in app modules is available to browse and experiment with.  But this proposed community project is all about introducing new people to the NVDA way, and it won't be successful if you:
>>
>> A) Assume that everyone has the necessary level of experience of
>> working with Python and a large codebase to port their existing
>> scripts; or
>> B) Fail to recognise that there are very real hurdles to jump over in order to become familiar with developing for NVDA.
>>
>> Regards.
>> --
>> 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
>
>
> ------------------------------------------------------------------------------
> 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
Reply | Threaded
Open this post in threaded view
|

Re: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Joseph Lee
Hi Cory,
In a nutshell, what you've described as objects are really modules in the NVDA world. For example, if you want to cancel speech, you'd use the following:
import speech
Then:
speech.cancelSpeech()
The desktop object can be grabbed via the api module as follows:
import api
Then:
desktop = api.getDesktopObject()
Sending and receiving messages between application windows can be done by using a combination of Windows DLL's and ctypes (foreign function interface):
import ctypes
appHandle = ctypes.windll.user32.FindWindowW(str, child)
ctypes.windll.user32.SendMessageW(appHandle, messageType, wParam, lParam)
Alternatively:
From ctypes import windll
user32 = windll.user32
appHandle = user32.FindWindowW(str, child)
user32.SendMessageW(appHandle, messageType, wParam, lParam)
But this can be transformed into:
import winUser
appHandle = winUser.findWindow(str, child)
winUser.sendMessage(appHandle, messageType, wParam, lParam)
Note that the functions wrapped inside winUser module are Unicode ones (wide chars). If you need to deal with ANSI version, the ctypes method is the best known (and used).
Cheers,
Joseph

-----Original Message-----
From: Cory Samaha [mailto:[hidden email]]
Sent: Monday, May 29, 2017 9:21 AM
To: NVDA screen reader development <[hidden email]>
Subject: Re: [Nvda-devel] Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

Hi Joseph and all,
I won’t beat this subject any further.  At least, I will try not to, <smile>.  I just wanted to thank you, Joseph, for the work you have put in already, and for the continued work for documentation that many like myself have wanted for such a long time.  Coming from Window-Eyes we have many different objects such as Application, the root object, Braille, Cursor, Mouse, MSAA, Keyboard, Screen, Speech, Synthesizer, Window etc.  Each of those objects have their own methods which can be invoked or events which one can monitor.  That may not be how it works in NVDA - I’m not sure, but from reading over this thread, it sounds like NVDA only has a few events in comparison and perhaps the objects are more consolidated.  I have dealt with MSAA objects from the context of Window-Eyes even where I have imported the Window-Eyes object into a C++ application.  That is not a fun process, I promise.

Finally to Jamie, I apologize that I probably misinterpreted what you have said regarding documentation as being dismissive.  It just never seemed a high priority, and the responses I got from some people on this list who glibly said “well the API reference is in the source if you download it” were a bit discouraging.  I actually did get Git up and running and did download the source.  After playing around with it for a bit however, I realized I could get done what I wanted to do faster in other screen readers.  I would love to have a public scripting object model similar to the Window-Eyes model, but I realize that there are fundamental differences in these two applications and that it may not be possible.  In any case, I’m glad this is finally being discussed.

All the Best,
Cory

> On May 28, 2017, at 9:19 PM, Joseph Lee <[hidden email]> wrote:
>
> Hi Cory and others,
> Thanks for speaking up regarding documentation, attitudes and what not.
> One thing I'll promise you: within 24 hours after the release of NVDA 2017.2, I will post a link to an online version of the complete developers guide that includes module hierarchy documentation and what not. I will also hold an online seminar with scripters of other screen readers before end of summer in hopes of starting a dialogue between you and the larger NVDA community regarding what we can do better.
> In regards to learning curve: yes, some adjustments must be made from both sides: scripters of other screen readers, and in the NVDA development community. I know that we the NVDA community members have been concentrating on some things to a point where we have neglected to engage with other audience members, so I'd like to apologize for not taking care of needs of external developers when we should have been better. First and foremost, as a code contributor and a community add-on reviewer, I will personally make sure that you all have one of the greatest documentation suite available. Second, I will personally make sure that needs of novice programmers are not forgotten, as you make up a sizable part of this community. Third, I will personally make sure that you are equipped to teach others in the end through opportunities to coach future novice developers.
> I myself take documentation seriously. I believe that what makes a good product even greater is a good documentation suite, and as a contributor with documentation experience, I will make sure that you too have a great experience when it comes to learning more about NVDA development and as you pass on your knowledge.
> To Mick and Jamie: although seasoned NVDA devs know that writing add-ons require effort and that folks will need to have some knowledge of Python, I'd like to request that we think about a need to document things and make our source code/documentation one of the finest in this industry. I'm not advocating that all functions and classes should be documented - I'm thinking more towards public functions and classes every developer will need to know (not just api.getFocusObject or ui.browsableMessage, but also things such as what UIA is and some issues we've found, app modules and what not). Yes, I'm bringing up an old topic, but I think we cannot ignore this issue of documentation anymore. If I have to, I will let #2559 slip to NVDA 2017.4 in favor of working all summer on making our source code dev docs great again for the sake of not only NV Access and existing community members, but also for external devs and future researchers.
> Thanks.
> Cheers,
> Joseph
>
> -----Original Message-----
> From: Cory Samaha [mailto:[hidden email]]
> Sent: Sunday, May 28, 2017 3:04 PM
> To: NVDA screen reader development <[hidden email]>
> Subject: Re: [Nvda-devel] Project Contact Lenses: a community
> initiative proposal to invite more people to NVDA ecosystem
>
> James,
>
> I think your message below expresses how many of us feel.  I will say that I was a Window-Eyes scripter.  When I began using NVDA a while back.  I subscribed to this list in hopes that I could figure out how to develop add-ons for NVDA as well.  I continued to point out on this list that the documentation is very much lacking for add-on development.  Indeed, NVAccess has a development guide, which describes the log viewer, the python console etc. and describes how to write some example scripts.  But if you want more information you need to hunt around through different documents that users have written.  I appreciate that users have taken the time to put together these documents and tutorials, but have you seen the Window-Eyes scripting manual?  It is a CHM file with all of the objects in a tree view.  You can then expand that tree view to see which events and methods belong to that object.  I appreciate that NVDA is much more powerful due to the fact that it is open source, but not having a document with some type of organization similar to the Window-Eyes scripting manual is going to turn people away very quickly, as it did for me.  Not to mention, there are some people who are not so much interested with the internals of NVDA, and simply want to learn the objects that are common in scripting an application.  This is especially true when you have people like Jamie, the head of NVAccess being very dismissive of my comments that better documentation is needed, and needs to stay updated with each release of NVDA.  This is currently not the case.  I disagree that this is not the responsibility of NVAccess.  I was able to learn how to operate NVDA very quickly due to its very simple and well-written manual.  But when I bring up documentation for NVDA add-on development on this list I feel that I am banging my head against a wall.  I apologize if this is a harsh tone to take, but you cannot continue to dismiss script developers of other screen readers who would like to switch to NVDA full time, but cannot do so because there is not one cohesive document which brings all of the add-on concepts together.  This is probably my biggest criticism of NVDA.
>
> Regards,
> Cory
>> On May 28, 2017, at 2:44 PM, James Scholes <[hidden email]> wrote:
>>
>> Joseph Lee wrote:
>>> NVDA does expose various screen reading and navigation API’s such as obtaining focused control, working with text fields and what not.
>>
>> It's not really about what capabilities NVDA provides.  Rather, what Marlon is refering to is the difference between the scripting services provided by various screen readers and how they are implemented.  In both JAWS and Window-Eyes, an interface is provided for developers to script against, and they never have any direct access to the internals of the program.
>>
>> Naturally, this is not only due to their compiled nature, but also because they are closed source.  Other programs which provide a plug-in development SDK such as Winamp, foobar2000, Kodi etc. operate in a similar way.  A developer wishing to add functionality to the product only has access to the interfaces which have explicitly been made available to them.
>>
>> Contrast this approach to that taken by NVDA, which simply loads Python code into the same operating environment as the screen reader itself, allowing an add-on writer to not only access the program's internals but also modify them.  Granted, in theory this allows add-ons to be as powerful as they need to be, but if you're launching a project to get people interested in developing NVDA add-ons who have previously worked with closed systems like JAWS and Window-Eyes, this is an important difference and one that people often struggle to get used to.
>>
>> When you're writing a JAWS script and have forgotten a function name or are not quite sure how to do something, you can browse through the functions on offer and find what you need.  Naturally, if you don't find it, you can call out to COM objects and whatever else.  But generally speaking there is a defined set of behaviour which makes it relatively easy to learn how to do things, combined with the JAWS Script Editor and documentation which helps you along the way.
>>
>> On the other hand, when you're not sure how to do something beyond the basics in NVDA, your only port of call is the NVDA codebase itself.  I speak from experience when I say that this can be daunting, to say the least.
>>
>> I don't write any of this to criticise NVAccess or anyone involved with the NVDA ecosystem.  In fact it could be argued that, due to the project's free and open source nature, the responsibility to lower the barrier of entry to add-on development doesn't lie with NVAccess at all.  Especially when you consider that all NVDA's code, including built-in app modules is available to browse and experiment with.  But this proposed community project is all about introducing new people to the NVDA way, and it won't be successful if you:
>>
>> A) Assume that everyone has the necessary level of experience of
>> working with Python and a large codebase to port their existing
>> scripts; or
>> B) Fail to recognise that there are very real hurdles to jump over in order to become familiar with developing for NVDA.
>>
>> Regards.
>> --
>> 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
>
>
> ----------------------------------------------------------------------
> -------- 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


------------------------------------------------------------------------------
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: Project Contact Lenses: a community initiative proposal to invite more people to NVDA ecosystem

James Teh
Except you almost always shouldn't use ANSI functions. :)

Cory, in some ways, you're right: documentation is a lower priority for us than other work we need to do. That's not to say it isn't important, just that there is a lot of other more important work we need to do with very limited resources, and that work requires our specific expertise. Let me put it this way: if we focus our resources on a major documentation effort, users don't get features and fixes for a while... and the amount we need to do in this area is already overwhelming.

So no, I don't think the current state of things is ideal; far from it. But can we dedicate a massive amount of time to it now? No, not without detriment to the product as a whole. That doesn't mean we can't chip away at it piece by piece, though. It's just not going to happen anywhere near as fast as anyone wants.

------------------------------------------------------------------------------
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
12