[Nvda-dev] app modules

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

[Nvda-dev] app modules

Josh Kennedy
Hi

Also documentation explaining all nvda functions to make writing app
modules easier would be good as well. if we had such documentation more
people may be able to write app modules for windows xp speech
recognition, windows 7 speech recognition, and ms-office.

Josh

--
Josh Kennedy [hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

James Teh
On 27/06/2010 10:34 PM, Josh wrote:
> Also documentation explaining all nvda functions to make writing app
> modules easier would be good as well.
There's already quite a bit of documentation in the code. More is being
added as time goes on.

Jamie

--
James Teh
Vice President
NV Access Inc, ABN 61773362390
Email: [hidden email]
Web site: http://www.nvaccess.org/


Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

mk360
    Ok, thats true, but what happen if I'm not a great programmer and I'm
only interested in doing some functions with modules, like scripts in other
screen readers? actually, this implies that I need to download all the
source code of NVDA and start reading it to understand how it work and what
functions can I use. As you can imagine, this is a problem for new users,
and one thing that makes NVDA to progres most slow (note that I like the
progres in NVDA).

    Many users use some functions of programs and do basic configurations,
and they can give some support if they have the documentation, but end users
probably will not read source code to create functions to do two or three
task. For example, when I use emule with JAWS I only need a script to move
the cursor to the results list (RouteInvisibletopc() findString("resultados
de la búsqueda") nextLine() nextline() RoutePCToInvisible().

    With NVDA if I don't use a module the same task implies NVDA 8 two
times, NVDA 4, NVDA 2 two times and left or right click if you need.
Obviously, using a module is the best way to automatice this task, but I'll
not read all the source code to do it if I'm not a programer.

    NVDA is growing fast, and now I think is time to think in end users.

    Regards,
    mk.
----- Original Message -----
From: "James Teh" <[hidden email]>
To: "News and discussion for NVDA (NonVisual Desktop Access),a free and open
source screen reader for Microsoft Windows" <[hidden email]>
Sent: Sunday, June 27, 2010 6:29 PM
Subject: Re: [Nvda-dev] app modules


> On 27/06/2010 10:34 PM, Josh wrote:
>> Also documentation explaining all nvda functions to make writing app
>> modules easier would be good as well.
> There's already quite a bit of documentation in the code. More is being
> added as time goes on.
>
> Jamie
>
> --
> James Teh
> Vice President
> NV Access Inc, ABN 61773362390
> Email: [hidden email]
> Web site: http://www.nvaccess.org/
>
> _______________________________________________
> Nvda-dev mailing list
> [hidden email]
> http://lists.nvaccess.org/listinfo/nvda-dev 



Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

James Teh
On 28/06/2010 9:03 AM, mk360 wrote:
>   Ok, thats true, but what happen if I'm not a great programmer and I'm
> only interested in doing some functions with modules, like scripts in
> other screen readers? actually, this implies that I need to download all
> the source code of NVDA and start reading it to understand how it work
> and what functions can I use.
You can browse the source code online. See the Development section of
the web site. Also, once i get it automated, there will be code
documentation in HTML format as extracted from the code.

> Many users use some functions of programs and do basic configurations,
> and they can give some support if they have the documentation, but end
> users probably will not read source code to create functions to do two
> or three task.
By that definition, I'd argue end users don't script at all. Scripting
inherently requires some basic understanding of programming.

> Obviously, using a module is the best way to automatice this task, but
> I'll not read all the source code to do it if I'm not a programer.
The big question is: how did you learn it with JAWS? There is literally
no way we can document every function you have at your disposal with
NVDA. App modules in NVDA are incredibly powerful and flexible because
they have the entire power of Python behind them, including much of the
standard library, but that obviously requires at least some knowledge of
Python. Also, NVDA is very much object oriented programming. New
programmers often find object oriented programming hard to grasp. You
need to understand that before you can really understand how to code
with NVDA.

When it comes to extending an application, there are two possibilities.
You can use an existing language or you can write your own. Using an
existing language means you get all the power of that language and
people don't need to learn a custom language just for one application.
Writing your own means you probably have a very limited language, plus
the number of people who know your language is going to be less. Both
have advantages and disadvantages, but ultimately, the former gives you
more power and flexibility.

Finally, remember that there are only two people working full time on
this project. We have to choose where to devote our time. Right now, the
focus is on improving the product as much as possible. Obviously, we
want good developer documentation, but that is actually a lot harder
than it seems. Most people can't seem to give us much of an idea of what
they need in terms of developer documentation. We just get a general
sense of "we need more documentation," which isn't particularly helpful.

Jamie

--
James Teh
Vice President
NV Access Inc, ABN 61773362390
Email: [hidden email]
Web site: http://www.nvaccess.org/


Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

mk360

----- Original Message -----
From: "James Teh" <[hidden email]>
To: "News and discussion for NVDA (NonVisual Desktop Access),a free and open
source screen reader for Microsoft Windows" <[hidden email]>
Sent: Sunday, June 27, 2010 7:23 PM
Subject: Re: [Nvda-dev] app modules


> On 28/06/2010 9:03 AM, mk360 wrote:
> (...)
>> Many users use some functions of programs and do basic configurations,
>> and they can give some support if they have the documentation, but end
>> users probably will not read source code to create functions to do two
>> or three task.
> By that definition, I'd argue end users don't script at all. Scripting
> inherently requires some basic understanding of programming.

    Hmmmm, if the user can do two or three tasks with basic instructions why
not? the scripting / modules system is not necesarily only for complex
tasks, you can increase some things and end users don't need to know
programing to move cursors or read text on the screen. Obviously, that user
will not create complex modules, but on the example, he will can use emule
without moving the cursor too many times.


>> Obviously, using a module is the best way to automatice this task, but
>> I'll not read all the source code to do it if I'm not a programer.
> The big question is: how did you learn it with JAWS?

    Well, probably the people can understand these things reading
documentation (in JAWS the scripting manual, in NVDA this can be a python
manual like dive into python) but when one understand these things only need
to read the specific documentation to the function, not all the program.

> There is literally no way we can document every function you have at your
> disposal with NVDA. App modules in NVDA are incredibly powerful and
> flexible because they have the entire power of Python behind them,
> including much of the standard library, but that obviously requires at
> least some knowledge of Python. Also, NVDA is very much object oriented
> programming. New

    Ok, and it is good becouse if you learn python you can program on other
projects like orca or whatever project youre interested. But this is not my
point... I never speak about the power of modules on NVDA, I'm only speaking
about some documentation about what functions exist on NVDA to use with
appModules (not all functions, I understand is imposible to document all,
but for example, one explanation about how users can move the review cursors
or read contents on the screen can be useful).

> programmers often find object oriented programming hard to grasp. You need
> to understand that before you can really understand how to code with NVDA.

Yes, I know. I'm not a programer, but I like programing and POO was a
problem for me on the past (inform was my first point to object oriented...
wow, I learned some things becouse interactive fiction :P).

>
> When it comes to extending an application, there are two possibilities.
> You can use an existing language or you can write your own. Using an
> existing language means you get all the power of that language and people
> don't need to learn a custom language just for one application. Writing
> your own means you probably have a very limited language, plus the number
> of people who know your language is going to be less. Both have advantages
> and disadvantages, but ultimately, the former gives you more power and
> flexibility.

    Well, I prefer to use an existing language, but again, I'm not thinking
on my interests becouse I'm using pcs in about ten years and I love pcs.

> Finally, remember that there are only two people working full time on this
> project. We have to choose where to devote our time. Right now, the focus
> is on improving the product as much as possible. Obviously, we want good
> developer documentation, but that is actually a lot harder than it seems.
> Most people can't seem to give us much of an idea of what they need in
> terms of developer documentation. We just get a general sense of "we need
> more documentation," which isn't particularly helpful.

    Ok, and I think all opinions on this list are suggestions, not
impositions ;) I and many other users love NVDA, and personally I prefer
that NVDA progres in other things, for example chrome, but this is a thing
to consider and a posibility that can give more users contributing to NVDA,
for example some users can know how orca work with some modules and what
functions can do with simple explanations like the orca-customizations.py of
storm dragon
(http://live.gnome.org/Orca/FrequentlyAskedQuestions/CustomizingOrca) this
script was modified in other comunities.

    Regards,
    mk.



Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

James Teh
On 28/06/2010 10:19 AM, mk360 wrote:
> Hmmmm, if the user can do two or three tasks with basic instructions why
> not? the scripting / modules system is not necesarily only for complex
> tasks, you can increase some things and end users don't need to know
> programing to move cursors or read text on the screen.
True, though you have to understand the syntax to an extent; e.g.
knowing where to put brackets, etc. I guess you can just copy and paste
bits of code and change it a bit, and maybe this is all you mean. In
that case, though, there are plenty of example app modules to use as a base.

> Well, probably the people can understand these things reading
> documentation (in JAWS the scripting manual, in NVDA this can be a
> python manual like dive into python) but when one understand these
> things only need to read the specific documentation to the function, not
> all the program.
Sure. So the automatic online code documentation I mentioned will help
this. I'll let people know once it's set up.

>> Finally, remember that there are only two people working full time on
>> this project. We have to choose where to devote our time. ...
> Ok, and I think all opinions on this list are suggestions, not
> impositions ;) I and many other users love NVDA, and personally I prefer
> that NVDA progres in other things, for example chrome, but this is a
> thing to consider and a posibility that can give more users contributing
> to NVDA
Fair enough. I don't mean to suggest that this is a bad suggestion. It's
just that it is very difficult to know where to start and what people
want. For example, to explain how to move the object navigator
programmatically, I need to find a program which I can use as an example
which is not too complex, yet inaccessible enough that there is actually
a point to explaining it. :)

> for example some users can know how orca work with some modules
> and what functions can do with simple explanations like the
> orca-customizations.py of storm dragon
> (http://live.gnome.org/Orca/FrequentlyAskedQuestions/CustomizingOrca)
Thanks for the link. This might give me somewhere to start.

The problem is largely that Mick and I know the NVDA code so well that
it is very hard for us to figure out where ot start in terms fo
documentation for new developers. It would help if someone with a bit of
understanding could point out what they missed and how they found the
info they needed in the end. It's a bit of a catch 22: we don't have
many new developers because we don't have enough documentation, but we
don't have enough documentation because we're not sure how new users
will start. With a screen reader, there are just far too many
possibilities as to what people might want to do.

Jamie

--
James Teh
Vice President
NV Access Inc, ABN 61773362390
Email: [hidden email]
Web site: http://www.nvaccess.org/


Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

Geoff Shang
In reply to this post by James Teh
On Mon, 28 Jun 2010, James Teh wrote:

> By that definition, I'd argue end users don't script at all. Scripting
> inherently requires some basic understanding of programming.

Yes indeed.  But a person shouldn't need to be a fully-fledged Python
programmer in order to write a short app module to get NVDa to speak
something whena certain key is pressed, for example.

> The big question is: how did you learn it with JAWS? There is literally no
> way we can document every function you have at your disposal with NVDA. App
> modules in NVDA are incredibly powerful and flexible because they have the
> entire power of Python behind them, including much of the standard library,
> but that obviously requires at least some knowledge of Python.

*some* knowledge of Python, yes.  I have some knowledge of Python, but
can't immediately see how I would write an app module or extend an
existing one.

> When it comes to extending an application, there are two possibilities. You
> can use an existing language or you can write your own. Using an existing
> language means you get all the power of that language and people don't need
> to learn a custom language just for one application. Writing your own means
> you probably have a very limited language, plus the number of people who know
> your language is going to be less. Both have advantages and disadvantages,
> but ultimately, the former gives you more power and flexibility.

It also means you don't have the burdan of maintaining the language as
well as the screen reader.

> Finally, remember that there are only two people working full time on this
> project. We have to choose where to devote our time. Right now, the focus is
> on improving the product as much as possible. Obviously, we want good
> developer documentation, but that is actually a lot harder than it seems.
> Most people can't seem to give us much of an idea of what they need in terms
> of developer documentation. We just get a general sense of "we need more
> documentation," which isn't particularly helpful.

I think maybe you need to think of it from the other direction.  Perhaps
think about the kinds of things that users are likely to want to do, maybe
even ask them, and then provide documentation on how this would be done.

In another message, you rightly talked about looking at existing code to
get an idea of what can be done and how.  The problem is that there's no
documentation for this code that explains what is being done or how.

Lets look at a small example.  The MPlayer Classic app module is the
smallest module (in my admitedly old copy of the NVDA sources) that
actually does something other than tell NVDA that the application is
self-voicing or that NVDA should use another application's app module.
The copy I have says the following:

import _default
import controlTypes

class AppModule(_default.AppModule):

         def event_NVDAObject_init(self,obj):
                 if obj.windowClassName=="#32770" and obj.windowControlID==10021:
                         obj.role = controlTypes.ROLE_STATUSBAR

Now it's pretty easy to see that this is telling NVDA that a particular
object is the status bar, presumably because NVDA doesn't identify it as
such.  But it's not easy to see *how* you did this.  For example, where
do these numbers come from and how would a developer get them?

In more complicated examples, you can see that something is being done to
override NVDA's default behaviour, but it's not clear to the uninitiated
what the consequences of this are.  For example, a bit of code lifted from
the iTunes app module:

                 if windowClassName=="iTunesSources" and role==controlTypes.ROLE_TREEVIEWITEM:
                         self.overlayCustomNVDAObjectClass(obj,ITunesItem,outerMost=True)
                 elif windowClassName=="iTunesTrackList" and role==controlTypes.ROLE_LISTITEM:
                         self.overlayCustomNVDAObjectClass(obj,ITunesItem,outerMost=True)

And in the Winamp app module , while it's clear some gymnastics are needed
for the playlist editor, it's not at all clear how the list items there
are being retrieved.

I know we've talked about providing a couple of simple worked examples
before.  I think there would be real value in this.  A fully commented
example along with a tutorial as to how one would start with an
application and a problem and progress through to solving the problem
would I think be helpful. Like I said, focuson the kinds of things people
are likely to want to do, rather than documenting all of NVDA's internals.

The other thing that might be useful is some kind of API reference for
useful NVDA functions.  Obviously documenting all Python functions would
be tedious and redundant.  But while looking at the various app modules,
I've seen references to functions such as speech.speakText(),
speech.speakMessage(), speech.speakObject and
speech.speakObjectProperties().  Now while someone could go and look at
speech.py and see what these functions do, this is an intimidating bit of
code, containing almost a thousand lines.  And it's overkill for someone
who simply wants to know how to get NVDA to say a specific thing when
programming an app module.  I'm sure there are other NVDA functions that
also fall into this category.

Geoff.



Reply | Threaded
Open this post in threaded view
|

[Nvda-dev] app modules

Britta Offergeld
In reply to this post by Josh Kennedy

You asked where control Information comes from?  Have you tried a program like WindowSpy (http://www.softpedia.com/get/System/System-Miscellaneous/WindowSpy.shtml) ? It’s a Windows UI tool that gives you info on ControlIDs and window handles on mouse over.

 

>Lets look at a small example.  The MPlayer Classic app module is the smallest module (in my admitedly old copy of the NVDA sources) that

>actually does something other than tell NVDA that the application is self-voicing or that NVDA should use another application's app module.

>The copy I have says the following:

 

>import _default

>import controlTypes

 

>class AppModule(_default.AppModule):

 

  >       def event_NVDAObject_init(self,obj):

    >             if obj.windowClassName=="#32770" and obj.windowControlID==10021:

      >                   obj.role = controlTypes.ROLE_STATUSBAR

 

>Now it's pretty easy to see that this is telling NVDA that a particular object is the status bar, presumably because NVDA doesn't identify it as

>such.  But it's not easy to see *how* you did this.  For example, where do these numbers come from and how would a developer get them?

 

 

 

Britta

 

“The best and most beautiful things in the world cannot be seen or even touched. They must be felt with the heart.”   – Helen Keller  

The Royal New Zealand Foundation of the Blind thanks all the wonderful volunteers for sharing our vision.
Celebrating Volunteer Awareness Week (20 - 26 June)


This email, including any attachments, is intended solely for the addressee(s).  It is confidential and may be legally privileged.  If you are not the intended recipient, you must not copy, disclose, distribute or otherwise use it or the information in it.  Please notify the sender at once and delete it from your system immediately.  Any views or opinions expressed are solely those of the author and do not necessarily represent those of the Royal New Zealand Foundation of the Blind.  The Foundation does not accept responsibility for any viruses or other malicious code that may be transmitted with this email.


Please consider the environment before printing this e-mail

Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

James Teh
In reply to this post by Geoff Shang
On 28/06/2010 11:32 PM, Geoff Shang wrote:
> I think maybe you need to think of it from the other direction. Perhaps
> think about the kinds of things that users are likely to want to do,
> maybe even ask them, and then provide documentation on how this would be
> done.
The problem is that the possibilities are almost limitless and it's
often very different depending on the control in question. That is, "I
want to remap this control to be an editable text control" just isn't
good enough. You have to know what API it uses, and if none, then you
have to make it use the display model. As you say, we need an idea of
what scripters want ot be able to do, but this has ot be better than "I
want to make this control act like an edit control".

> In another message, you rightly talked about looking at existing code to
> get an idea of what can be done and how. The problem is that there's no
> documentation for this code that explains what is being done or how.
Most of the important functions are documented in the code. Once we have
the automatic epydoc documentation, you will be able to browse all of
the code documentation.

> if obj.windowClassName=="#32770" and obj.windowControlID==10021:
> obj.role = controlTypes.ROLE_STATUSBAR
> Now it's pretty easy to see that this is telling NVDA that a particular
> object is the status bar, presumably because NVDA doesn't identify it as
> such. But it's not easy to see *how* you did this. For example, where do
> these numbers come from and how would a developer get them?
The property used there is windowClassName, so this is the piece of
information we're comparing against. How to get it is another matter.
However, again, windowClassName is a property of the Window NVDAObject
class, which will show up in the code documentation.

My point is that there are so many possibilities for what a user might
need to compare against. windowClassName might not be enough, if it is
useful at all. If you look at explorer, we even have to go so far as
comparing the position of the object relative to other objects. It is
impossible to document all of these possibilities, yet windowClassName
alone might not be enough for 50% of cases.

> self.overlayCustomNVDAObjectClass(obj,ITunesItem,outerMost=True)
overlaycustomNVDAObjectClass is documented in the code as well. Btw,
this has been removed post 2010.1; we now do this another way.

> And in the Winamp app module , while it's clear some gymnastics are
> needed for the playlist editor, it's not at all clear how the list items
> there are being retrieved.
Winamp is probably a bad example, as it is relatively complicated to
retrieve info from it. We have to do a lot of ugly stuff with window
messages and cross-process memory allocation.

> I know we've talked about providing a couple of simple worked examples
> before. I think there would be real value in this.
I totally agree. It's just difficult to find a simple example that
actually does something useful.

> A fully commented
> example along with a tutorial as to how one would start with an
> application and a problem and progress through to solving the problem
> would I think be helpful.
This is just the point, though. There is no single way of making an
application accessible. It all depends on the way in which the
application is inaccessible and what you can use to uniquely identify
the problematic control.

Unfortunately, as i said before, it's highly possible that I am just not
good at documenting this stuff or too close to the code to see a
starting point. I strongly agree that we need more developer
documentation; that was never in question. I just can't even se e
astarting point at this stage. There often isn't really a common
solution to a user's desire to "make a control accessible". For example,
a user might say "this control is unnamed and i want NVDA to see the
name", but there is no one way to find the label for an unlabelled
control. It could be a matter of using an API, using display
information, getting the next object to the parent object or, if all
else fails, labelling it manually in the code. How do you explain so
many wildly differing possibilities to a user in a simple document?

Jamie

--
James Teh
Vice President
NV Access Inc, ABN 61773362390
Email: [hidden email]
Web site: http://www.nvaccess.org/


Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

Soronel Haetir
Jemes Teh,

I'm sorry, but saying "look at the existing modules" for documentation
purposes is extremely shortsighted.  Even if the doc strings
extraction process worked that would still be lacking as anything
other than a minimalistic reference.

I could understand if your attitude were more "we have too much going
on, it's on the list but not a high priority" but you in fact seem
dismissive toward the very idea of proper documentation.

I also understand documentation is both hard and not very sexy, but it
is also critical if you actually hope to get people on board for more
than the one small slice they wish worked.


On 6/28/10, James Teh <[hidden email]> wrote:

> On 28/06/2010 11:32 PM, Geoff Shang wrote:
>> I think maybe you need to think of it from the other direction. Perhaps
>> think about the kinds of things that users are likely to want to do,
>> maybe even ask them, and then provide documentation on how this would be
>> done.
> The problem is that the possibilities are almost limitless and it's
> often very different depending on the control in question. That is, "I
> want to remap this control to be an editable text control" just isn't
> good enough. You have to know what API it uses, and if none, then you
> have to make it use the display model. As you say, we need an idea of
> what scripters want ot be able to do, but this has ot be better than "I
> want to make this control act like an edit control".
>
>> In another message, you rightly talked about looking at existing code to
>> get an idea of what can be done and how. The problem is that there's no
>> documentation for this code that explains what is being done or how.
> Most of the important functions are documented in the code. Once we have
> the automatic epydoc documentation, you will be able to browse all of
> the code documentation.
>
>> if obj.windowClassName=="#32770" and obj.windowControlID==10021:
>> obj.role = controlTypes.ROLE_STATUSBAR
>> Now it's pretty easy to see that this is telling NVDA that a particular
>> object is the status bar, presumably because NVDA doesn't identify it as
>> such. But it's not easy to see *how* you did this. For example, where do
>> these numbers come from and how would a developer get them?
> The property used there is windowClassName, so this is the piece of
> information we're comparing against. How to get it is another matter.
> However, again, windowClassName is a property of the Window NVDAObject
> class, which will show up in the code documentation.
>
> My point is that there are so many possibilities for what a user might
> need to compare against. windowClassName might not be enough, if it is
> useful at all. If you look at explorer, we even have to go so far as
> comparing the position of the object relative to other objects. It is
> impossible to document all of these possibilities, yet windowClassName
> alone might not be enough for 50% of cases.
>
>> self.overlayCustomNVDAObjectClass(obj,ITunesItem,outerMost=True)
> overlaycustomNVDAObjectClass is documented in the code as well. Btw,
> this has been removed post 2010.1; we now do this another way.
>
>> And in the Winamp app module , while it's clear some gymnastics are
>> needed for the playlist editor, it's not at all clear how the list items
>> there are being retrieved.
> Winamp is probably a bad example, as it is relatively complicated to
> retrieve info from it. We have to do a lot of ugly stuff with window
> messages and cross-process memory allocation.
>
>> I know we've talked about providing a couple of simple worked examples
>> before. I think there would be real value in this.
> I totally agree. It's just difficult to find a simple example that
> actually does something useful.
>
>> A fully commented
>> example along with a tutorial as to how one would start with an
>> application and a problem and progress through to solving the problem
>> would I think be helpful.
> This is just the point, though. There is no single way of making an
> application accessible. It all depends on the way in which the
> application is inaccessible and what you can use to uniquely identify
> the problematic control.
>
> Unfortunately, as i said before, it's highly possible that I am just not
> good at documenting this stuff or too close to the code to see a
> starting point. I strongly agree that we need more developer
> documentation; that was never in question. I just can't even se e
> astarting point at this stage. There often isn't really a common
> solution to a user's desire to "make a control accessible". For example,
> a user might say "this control is unnamed and i want NVDA to see the
> name", but there is no one way to find the label for an unlabelled
> control. It could be a matter of using an API, using display
> information, getting the next object to the parent object or, if all
> else fails, labelling it manually in the code. How do you explain so
> many wildly differing possibilities to a user in a simple document?
>
> Jamie
>
> --
> James Teh
> Vice President
> NV Access Inc, ABN 61773362390
> Email: [hidden email]
> Web site: http://www.nvaccess.org/
>
> _______________________________________________
> Nvda-dev mailing list
> [hidden email]
> http://lists.nvaccess.org/listinfo/nvda-dev
>


--
Soronel Haetir
[hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

James Teh
On 3/07/2010 8:49 AM, Soronel Haetir wrote:
> I'm sorry, but saying "look at the existing modules" for documentation
> purposes is extremely shortsighted.
 > I could understand if your attitude were more "we have too much going
 > on, it's on the list but not a high priority" but you in fact seem
 > dismissive toward the very idea of proper documentation.
Then you clearly didn't read my message properly. Quoting the message to
which you replied:

> Unfortunately, as i said before, it's highly possible that I am just not
> good at documenting this stuff or too close to the code to see a
> starting point. I strongly agree that we need more developer
> documentation; that was never in question. I just can't even se e
> astarting point at this stage. There often isn't really a common
> solution to a user's desire to "make a control accessible". For example,
> a user might say "this control is unnamed and i want NVDA to see the
> name", but there is no one way to find the label for an unlabelled
> control. It could be a matter of using an API, using display
> information, getting the next object to the parent object or, if all
> else fails, labelling it manually in the code. How do you explain so
> many wildly differing possibilities to a user in a simple document?

Addressing another of your points:
> Even if the doc strings
> extraction process worked that would still be lacking as anything
> other than a minimalistic reference.
If you want a reference of the functions you can use, the code
documentation is the place to go. NVDA is not alone in this. Getting
started is another matter entirely, and that's where we need documentation.

Jamie

--
James Teh
Vice President
NV Access Inc, ABN 61773362390
Email: [hidden email]
Web site: http://www.nvaccess.org/


Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

Soronel Haetir
In response to your specific example problem area I would say take the
most basic solution, which would probably be simply assigning a name
based on identifying information.

You are absolutely right that NVDA documentation need not cover win32
or even python (very much), what the documentation needs to do is
explain NVDA itself.

By providing even a minimal example of naming a control you free the
potential developer from hunting through the code trying to find an
example of that task being done.  More importantly it frees the
potential developer from incorrect guesses about where to start.
Multiply that one small task by a basic sample of how numerous other
parts of NVDA work and the undertaking is suddenly something of
immense value to someone trying to get started.

On 7/2/10, James Teh <[hidden email]> wrote:

> On 3/07/2010 8:49 AM, Soronel Haetir wrote:
>> I'm sorry, but saying "look at the existing modules" for documentation
>> purposes is extremely shortsighted.
>  > I could understand if your attitude were more "we have too much going
>  > on, it's on the list but not a high priority" but you in fact seem
>  > dismissive toward the very idea of proper documentation.
> Then you clearly didn't read my message properly. Quoting the message to
> which you replied:
>> Unfortunately, as i said before, it's highly possible that I am just not
>> good at documenting this stuff or too close to the code to see a
>> starting point. I strongly agree that we need more developer
>> documentation; that was never in question. I just can't even se e
>> astarting point at this stage. There often isn't really a common
>> solution to a user's desire to "make a control accessible". For example,
>> a user might say "this control is unnamed and i want NVDA to see the
>> name", but there is no one way to find the label for an unlabelled
>> control. It could be a matter of using an API, using display
>> information, getting the next object to the parent object or, if all
>> else fails, labelling it manually in the code. How do you explain so
>> many wildly differing possibilities to a user in a simple document?
>
> Addressing another of your points:
>> Even if the doc strings
>> extraction process worked that would still be lacking as anything
>> other than a minimalistic reference.
> If you want a reference of the functions you can use, the code
> documentation is the place to go. NVDA is not alone in this. Getting
> started is another matter entirely, and that's where we need documentation.
>
> Jamie
>
> --
> James Teh
> Vice President
> NV Access Inc, ABN 61773362390
> Email: [hidden email]
> Web site: http://www.nvaccess.org/
>
> _______________________________________________
> Nvda-dev mailing list
> [hidden email]
> http://lists.nvaccess.org/listinfo/nvda-dev
>


--
Soronel Haetir
[hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

Brian Gaff Lineone downstairs
You only need to look at the two completely different ways that Dolphin
screenreaders have to help to get some users to be able to  get access for
themselves on difficult apps. They initially thought that the map process
with its property sheets was the way to go, but the various choices
mushroomed so nobody could actually work out the best way to do things in
amongst all the differnt sheets. So now they put in scripting as well. I'd
imagine that most users are now completely confused at the conceptual
differencies between scripts, and maps.

As has been said, there is no one way, or probably one right way to get
access to programs that are difficult.
 How on earth do you go about teaching people the differences between the
methods nvda uses to look at the content and decide what to  speak or
braille at a given point in procedings without talking about the  minutii of
how windows works.

 I suppose a 'simple' graphic labeling system, like Dolphisns can be of use,
but they themselves admit its very simplistic and probably won't always
work.


I suppose a few commented demo app modules  might be a nice idea though.

 Brian
----- Original Message -----
From: "Soronel Haetir" <[hidden email]>
To: "News and discussion for NVDA (NonVisual Desktop Access),a free and open
source screen reader for Microsoft Windows" <[hidden email]>
Sent: Saturday, July 03, 2010 5:13 PM
Subject: Re: [Nvda-dev] app modules


> In response to your specific example problem area I would say take the
> most basic solution, which would probably be simply assigning a name
> based on identifying information.
>
> You are absolutely right that NVDA documentation need not cover win32
> or even python (very much), what the documentation needs to do is
> explain NVDA itself.
>
> By providing even a minimal example of naming a control you free the
> potential developer from hunting through the code trying to find an
> example of that task being done.  More importantly it frees the
> potential developer from incorrect guesses about where to start.
> Multiply that one small task by a basic sample of how numerous other
> parts of NVDA work and the undertaking is suddenly something of
> immense value to someone trying to get started.
>
> On 7/2/10, James Teh <[hidden email]> wrote:
>> On 3/07/2010 8:49 AM, Soronel Haetir wrote:
>>> I'm sorry, but saying "look at the existing modules" for documentation
>>> purposes is extremely shortsighted.
>>  > I could understand if your attitude were more "we have too much going
>>  > on, it's on the list but not a high priority" but you in fact seem
>>  > dismissive toward the very idea of proper documentation.
>> Then you clearly didn't read my message properly. Quoting the message to
>> which you replied:
>>> Unfortunately, as i said before, it's highly possible that I am just not
>>> good at documenting this stuff or too close to the code to see a
>>> starting point. I strongly agree that we need more developer
>>> documentation; that was never in question. I just can't even se e
>>> astarting point at this stage. There often isn't really a common
>>> solution to a user's desire to "make a control accessible". For example,
>>> a user might say "this control is unnamed and i want NVDA to see the
>>> name", but there is no one way to find the label for an unlabelled
>>> control. It could be a matter of using an API, using display
>>> information, getting the next object to the parent object or, if all
>>> else fails, labelling it manually in the code. How do you explain so
>>> many wildly differing possibilities to a user in a simple document?
>>
>> Addressing another of your points:
>>> Even if the doc strings
>>> extraction process worked that would still be lacking as anything
>>> other than a minimalistic reference.
>> If you want a reference of the functions you can use, the code
>> documentation is the place to go. NVDA is not alone in this. Getting
>> started is another matter entirely, and that's where we need
>> documentation.
>>
>> Jamie
>>
>> --
>> James Teh
>> Vice President
>> NV Access Inc, ABN 61773362390
>> Email: [hidden email]
>> Web site: http://www.nvaccess.org/
>>
>> _______________________________________________
>> Nvda-dev mailing list
>> [hidden email]
>> http://lists.nvaccess.org/listinfo/nvda-dev
>>
>
>
> --
> Soronel Haetir
> [hidden email]
>
> _______________________________________________
> Nvda-dev mailing list
> [hidden email]
> http://lists.nvaccess.org/listinfo/nvda-dev
>




Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

Soronel Haetir
As I said, providing documentation for windows or python is not the
job of anyone involved with NVDA.  Only items that belong to NVDA need
be documented by anyone on the project.

Per your Dolphin example, the job would be to document the two
different interfaces, perhaps with a basic outline of when each is
preferred or even a statement that one is deprecated.

Something close to what I think is needed is the freedom scientific
developer network file.  It documents the API available from the
product but does not document the exposed windows APIs other than in
cursory fashion and even then mostly to describe the limitations of
what the FS products can not do that the native functions can.
Extracting doc strings would be a reasonable start toward this, but by
no means complete.

On 7/3/10, Brian Gaff Lineone downstairs <[hidden email]> wrote:

> You only need to look at the two completely different ways that Dolphin
> screenreaders have to help to get some users to be able to  get access for
> themselves on difficult apps. They initially thought that the map process
> with its property sheets was the way to go, but the various choices
> mushroomed so nobody could actually work out the best way to do things in
> amongst all the differnt sheets. So now they put in scripting as well. I'd
> imagine that most users are now completely confused at the conceptual
> differencies between scripts, and maps.
>
> As has been said, there is no one way, or probably one right way to get
> access to programs that are difficult.
>  How on earth do you go about teaching people the differences between the
> methods nvda uses to look at the content and decide what to  speak or
> braille at a given point in procedings without talking about the  minutii of
> how windows works.
>
>  I suppose a 'simple' graphic labeling system, like Dolphisns can be of use,
> but they themselves admit its very simplistic and probably won't always
> work.
>
>
> I suppose a few commented demo app modules  might be a nice idea though.
>
>  Brian
> ----- Original Message -----
> From: "Soronel Haetir" <[hidden email]>
> To: "News and discussion for NVDA (NonVisual Desktop Access),a free and open
> source screen reader for Microsoft Windows" <[hidden email]>
> Sent: Saturday, July 03, 2010 5:13 PM
> Subject: Re: [Nvda-dev] app modules
>
>
>> In response to your specific example problem area I would say take the
>> most basic solution, which would probably be simply assigning a name
>> based on identifying information.
>>
>> You are absolutely right that NVDA documentation need not cover win32
>> or even python (very much), what the documentation needs to do is
>> explain NVDA itself.
>>
>> By providing even a minimal example of naming a control you free the
>> potential developer from hunting through the code trying to find an
>> example of that task being done.  More importantly it frees the
>> potential developer from incorrect guesses about where to start.
>> Multiply that one small task by a basic sample of how numerous other
>> parts of NVDA work and the undertaking is suddenly something of
>> immense value to someone trying to get started.
>>
>> On 7/2/10, James Teh <[hidden email]> wrote:
>>> On 3/07/2010 8:49 AM, Soronel Haetir wrote:
>>>> I'm sorry, but saying "look at the existing modules" for documentation
>>>> purposes is extremely shortsighted.
>>>  > I could understand if your attitude were more "we have too much going
>>>  > on, it's on the list but not a high priority" but you in fact seem
>>>  > dismissive toward the very idea of proper documentation.
>>> Then you clearly didn't read my message properly. Quoting the message to
>>> which you replied:
>>>> Unfortunately, as i said before, it's highly possible that I am just not
>>>> good at documenting this stuff or too close to the code to see a
>>>> starting point. I strongly agree that we need more developer
>>>> documentation; that was never in question. I just can't even se e
>>>> astarting point at this stage. There often isn't really a common
>>>> solution to a user's desire to "make a control accessible". For example,
>>>> a user might say "this control is unnamed and i want NVDA to see the
>>>> name", but there is no one way to find the label for an unlabelled
>>>> control. It could be a matter of using an API, using display
>>>> information, getting the next object to the parent object or, if all
>>>> else fails, labelling it manually in the code. How do you explain so
>>>> many wildly differing possibilities to a user in a simple document?
>>>
>>> Addressing another of your points:
>>>> Even if the doc strings
>>>> extraction process worked that would still be lacking as anything
>>>> other than a minimalistic reference.
>>> If you want a reference of the functions you can use, the code
>>> documentation is the place to go. NVDA is not alone in this. Getting
>>> started is another matter entirely, and that's where we need
>>> documentation.
>>>
>>> Jamie
>>>
>>> --
>>> James Teh
>>> Vice President
>>> NV Access Inc, ABN 61773362390
>>> Email: [hidden email]
>>> Web site: http://www.nvaccess.org/
>>>
>>> _______________________________________________
>>> Nvda-dev mailing list
>>> [hidden email]
>>> http://lists.nvaccess.org/listinfo/nvda-dev
>>>
>>
>>
>> --
>> Soronel Haetir
>> [hidden email]
>>
>> _______________________________________________
>> Nvda-dev mailing list
>> [hidden email]
>> http://lists.nvaccess.org/listinfo/nvda-dev
>>
>
>
>
> _______________________________________________
> Nvda-dev mailing list
> [hidden email]
> http://lists.nvaccess.org/listinfo/nvda-dev
>


--
Soronel Haetir
[hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: [Nvda-dev] app modules

Manish Agrawal
One possible starting point could be to document the lifecycle of the app
Module, if you will.
- When is the app module initialized
- What methods and events are called on init
- What methods/events can be implemented/overridden in an app module that
will be called in some specific order.

Currently, when I look at an existing app module, I see several methods that
seem to have specific names and semantics of being called in some specific
unknown order by a controlling routine (if I am completely off the mark
here, then it just goes to show that without documentation, one can be
completely mislead).
A step-by-step walkthrough of implementing a single app module will be of
immense value even though there may be a "million ways" of getting the
relevant data from a specific app. What we are trying to teach here is the
NVDA specific stuff and not the app specific (as a side benefit, the
documentation may showcase one or two of the most common of the "million
ways" as well).


-Manish

-----Original Message-----
From: [hidden email]
[mailto:[hidden email]] On Behalf Of Soronel Haetir
Sent: Saturday, July 03, 2010 11:37 PM
To: News and discussion for NVDA (NonVisual Desktop Access), a free and open
source screen reader for Microsoft Windows
Subject: Re: [Nvda-dev] app modules

As I said, providing documentation for windows or python is not the
job of anyone involved with NVDA.  Only items that belong to NVDA need
be documented by anyone on the project.

Per your Dolphin example, the job would be to document the two
different interfaces, perhaps with a basic outline of when each is
preferred or even a statement that one is deprecated.

Something close to what I think is needed is the freedom scientific
developer network file.  It documents the API available from the
product but does not document the exposed windows APIs other than in
cursory fashion and even then mostly to describe the limitations of
what the FS products can not do that the native functions can.
Extracting doc strings would be a reasonable start toward this, but by
no means complete.

On 7/3/10, Brian Gaff Lineone downstairs <[hidden email]> wrote:

> You only need to look at the two completely different ways that Dolphin
> screenreaders have to help to get some users to be able to  get access for
> themselves on difficult apps. They initially thought that the map process
> with its property sheets was the way to go, but the various choices
> mushroomed so nobody could actually work out the best way to do things in
> amongst all the differnt sheets. So now they put in scripting as well. I'd
> imagine that most users are now completely confused at the conceptual
> differencies between scripts, and maps.
>
> As has been said, there is no one way, or probably one right way to get
> access to programs that are difficult.
>  How on earth do you go about teaching people the differences between the
> methods nvda uses to look at the content and decide what to  speak or
> braille at a given point in procedings without talking about the  minutii
of
> how windows works.
>
>  I suppose a 'simple' graphic labeling system, like Dolphisns can be of
use,

> but they themselves admit its very simplistic and probably won't always
> work.
>
>
> I suppose a few commented demo app modules  might be a nice idea though.
>
>  Brian
> ----- Original Message -----
> From: "Soronel Haetir" <[hidden email]>
> To: "News and discussion for NVDA (NonVisual Desktop Access),a free and
open

> source screen reader for Microsoft Windows" <[hidden email]>
> Sent: Saturday, July 03, 2010 5:13 PM
> Subject: Re: [Nvda-dev] app modules
>
>
>> In response to your specific example problem area I would say take the
>> most basic solution, which would probably be simply assigning a name
>> based on identifying information.
>>
>> You are absolutely right that NVDA documentation need not cover win32
>> or even python (very much), what the documentation needs to do is
>> explain NVDA itself.
>>
>> By providing even a minimal example of naming a control you free the
>> potential developer from hunting through the code trying to find an
>> example of that task being done.  More importantly it frees the
>> potential developer from incorrect guesses about where to start.
>> Multiply that one small task by a basic sample of how numerous other
>> parts of NVDA work and the undertaking is suddenly something of
>> immense value to someone trying to get started.
>>
>> On 7/2/10, James Teh <[hidden email]> wrote:
>>> On 3/07/2010 8:49 AM, Soronel Haetir wrote:
>>>> I'm sorry, but saying "look at the existing modules" for documentation
>>>> purposes is extremely shortsighted.
>>>  > I could understand if your attitude were more "we have too much going
>>>  > on, it's on the list but not a high priority" but you in fact seem
>>>  > dismissive toward the very idea of proper documentation.
>>> Then you clearly didn't read my message properly. Quoting the message to
>>> which you replied:
>>>> Unfortunately, as i said before, it's highly possible that I am just
not
>>>> good at documenting this stuff or too close to the code to see a
>>>> starting point. I strongly agree that we need more developer
>>>> documentation; that was never in question. I just can't even se e
>>>> astarting point at this stage. There often isn't really a common
>>>> solution to a user's desire to "make a control accessible". For
example,

>>>> a user might say "this control is unnamed and i want NVDA to see the
>>>> name", but there is no one way to find the label for an unlabelled
>>>> control. It could be a matter of using an API, using display
>>>> information, getting the next object to the parent object or, if all
>>>> else fails, labelling it manually in the code. How do you explain so
>>>> many wildly differing possibilities to a user in a simple document?
>>>
>>> Addressing another of your points:
>>>> Even if the doc strings
>>>> extraction process worked that would still be lacking as anything
>>>> other than a minimalistic reference.
>>> If you want a reference of the functions you can use, the code
>>> documentation is the place to go. NVDA is not alone in this. Getting
>>> started is another matter entirely, and that's where we need
>>> documentation.
>>>
>>> Jamie
>>>
>>> --
>>> James Teh
>>> Vice President
>>> NV Access Inc, ABN 61773362390
>>> Email: [hidden email]
>>> Web site: http://www.nvaccess.org/
>>>
>>> _______________________________________________
>>> Nvda-dev mailing list
>>> [hidden email]
>>> http://lists.nvaccess.org/listinfo/nvda-dev
>>>
>>
>>
>> --
>> Soronel Haetir
>> [hidden email]
>>
>> _______________________________________________
>> Nvda-dev mailing list
>> [hidden email]
>> http://lists.nvaccess.org/listinfo/nvda-dev
>>
>
>
>
> _______________________________________________
> Nvda-dev mailing list
> [hidden email]
> http://lists.nvaccess.org/listinfo/nvda-dev
>


--
Soronel Haetir
[hidden email]

_______________________________________________
Nvda-dev mailing list
[hidden email]
http://lists.nvaccess.org/listinfo/nvda-dev