Tracking.

I need more information than what's given at:

http://cvs.gnome.org/viewcvs/*checkout*/orca/docs/doc-set/orca.html#URWATCHED

in order to implement this.

Presumably, in order to add an object to the "watched" list,
you give the object you'd like to be watched focus, then hit 
a hot-key. What hotkey adds an object to the "watched" list?

What option gives the following:
"Orca will also provide an option to automatically enter 
review mode and make the watched object the object of 
interest."

What "well known command" gives the following:
"From this point, the user can use a well known command 
to go back to the object with focus, give the watched 
object focus if possible, or perform the equivalent of 
a mouse click on the watched object." 

Add accessibility keyword.  Apologies for spam.

This information is also going into the requirements docs.  

<section id="urwatched"><title>Watched Objects</title>

      <para>Orca will allow users to indicate interest in an object.
	Once interest has been given, Orca will notify the user of
	changes to that object, whether it or its window has focus or
	not.  Orca will also provide an option to automatically enter
	review mode and make the watched object the object of
	interest.  From this point, the user can use a &wkc; to go
	back to the object with focus, give the watched object focus
	if possible, or perform the equivalent of a mouse click on the
	watched object. A watched object should not be restricted to the screen.  For example, a user may want to set a particular cell in a spreadsheet as a watched object.  The user may not care if this cell is visible or not.  The user will press insert+w to move to the watched object and press numpad dash to return to the focus position keeping with the method of exiting flat review.  The user will double press insert+w to actually set a watched object. </para>

    

Okay, we have:

1/ insert+w to move to the watched object

2/ numpad dash to return to the focus position 
   keeping with the method of exiting flat review.

3/ double press insert+w to actually set a watched object

What clears a watched object?

Question for Will; if the watched object is not visible
onscreen when the user presses insert-w, what do I have to do
to make it visible? Will just setting the locus of focus work?

Calling setLocusOfFocus merely updates Orca's internal data structures, so I think you may need to do more.  You might try doing something like calling obj.component.grabFocus() on the watched object.  It might work. 

Will and I discussed this last Friday. Here are some notes
and questions (before I forget them):

We probably want to hook this into visualAppearanceChanged()
in default.py at about line 2170:

        if obj != orca_state.locusOfFocus:
            ADD WATCHED OBJECT CHECKING HERE.
            return

Now, onto several questions. Mike, could you respond please?

Q1. What exactly do you want spoken/brailled when a watched object
    has an event. Please specify.

Q2. Are we going to allow the user to be able to set a watched
    object when they are in flat review mode?

Q3. If you go to a watched object in flat review, are you still in
    flat review after you've moved?

Q4. If you are in flat review mode and you've moved to a watched
    object, what does Numpad-dash do? Exit flat-review mode or
    return you to the previous object that had focus?

Q5. Can you have more than one watched object? 

Q6. If yes, how do you cycle between them?

Q7. Can you set a non-focusable object to be a watched object?

> 
> Q1. What exactly do you want spoken/brailled when a watched object
>     has an event. Please specify.
The same thing as if the object had been given focus.
> 
> Q2. Are we going to allow the user to be able to set a watched
>     object when they are in flat review mode?
Yes
> 
> Q3. If you go to a watched object in flat review, are you still in
>     flat review after you've moved?
No
> 
> Q4. If you are in flat review mode and you've moved to a watched
>     object, what does Numpad-dash do? Exit flat-review mode or
>     return you to the previous object that had focus?
It will return you to the previus object with focus.
> 
> Q5. Can you have more than one watched object? 
No
> 
> Q6. If yes, how do you cycle between them?
> 
> Q7. Can you set a non-focusable object to be a watched object?
Yes, for example a progress bar I don't thhink can gain focus but the user might want to set it as a watched object.  
> 

Great. Thanks. Could you also please update the specification
to reflect all this. 

I'll start looking to see how to implement this.

One more question on this.

If you already have a watched object set and you do Ctrl-Insert-w
to set a different one, do you inform the user that there was already
a watched object and did you really mean to do this, or do you
automatically just set the watched object to this new object?

I think the best and least verbose thing to do here is to speak "setting watched object" when setting the new one.  As we are only going to allow one at a time the user should expect this to unset the previusly set watched object.   

Planning spam. Sorry!

what's the status of this? is any body interested? does someone have a use case for it?

The use cases are not massive, but one that springs to mind is: You're working in a spreadsheet in one area and the changes you are making are causing the results of a calculation in another cell to be updated. Rather than have to navigate back and forth between the two (or more) cells, it would be nice to have a command to present the changes to the non-focused area.

We already have code in the ballpark of this (bookmarks, live regions). As we refactor, I hope to see if we can get all this functionality combined/applied to handle "watched objects." So for now, I'd like to keep this one opened.

Obsoleting this. It will be handled as part of the bookmark rewrite.