Hi Joanie, What would you expect this UI to look Like?  As we move forward with future planning it would be helpful to have as much community feedback as possible on what the user expectation is here.  Perhaps a table of all the possible attributes?  Each attribute could either be checked or unchecked and the table could be reordered?   

Well I'm not Joanie, but here's how I think it should look. 8-)

There would be two parts (the first one having a higher priority than
the second).

1/ The ability to specify which default text attributes you want spoken,
   the order they are spoken in, and their default values (i.e. if the value
   is the default value, it's not spoken).

2/ The ability to set text attributes on an application specific basis.
   As !1 above, but settable per app (i.e. in the appropriate file under
   the ~/.orca/app-settings directory.

For the default text attribute settings, I suggest a table. 
The first column is the name of the text attribute. Each entry would 
have a checkbox that if ticked, means that we want to hear this attribute
(assuming the application handles it).
 
The second column is the default value (editable) for that attribute.
The user can adjust this as thesy see fit.

For getting the order, I suggest four buttons. You would select the 
attribute you wanted to move, then press the appropriate button

^^ - move the selected attribute to the top (first position).

^  - move the selected attribute up one place (nearer the front of the list).

v  - move the selected attribute down one place (nearer the back of the list).

vv - move the selected attribute to the end (last place).

Comments?

Mike, Joanie could you start thinking about how you would like this
spec'ed please? Thanks.

Oops, seems I failed to notice this.... Twice.... Sorry guys!! :-(

I like your suggestions Rich.  However, I'm not sure I follow what you mean by:

> the first one having a higher priority than the second

Or perhaps I do, and I just think it should be the opposite. ;-)  So to be sure we're on the same page:  Let's say I have decided that by default I care about every last attribute under the sun, but in Evolution I just want to know the alignment and color.  Having established my huge list of interesting attributes for default use and my short list for Evolution, I would expect in Evolution to only hear about alignment and color.  In other words, the second one should have a higher priority than the first.  If I'm totally missing your point, I'm sorry.

I like the table you described.  I assume the buttons would be labeled in such a way that Orca would speak their function rather than the punctuation displayed. 

Given the large number of attributes, at least in some apps, I'd like to propose the addition of buttons to check/tick all and to uncheck/untick all.

In terms of setting the default attributes versus app-specific attributes, I can see a couple of possibilities:

1. One keystroke to get into the default-related dialog (say, Insert + Whatever-Key) and a similar one to get into the dialog pertaining to the attributes for the app whose window has focus (Insert + Shift + Whatever-Key).  The resulting dialogs wouldn't be different, other than the title bar.

2. One keystroke period.  The dialog would have two radio buttons:  Default and Application.  (Or perhaps a single push button:  Default if you're working with app-specific attributes and Application if you're working with default attributes).  Regardless, pressing such a button would re-populate the tree if need be, and should probably give a visual/verbal/braille indication of which group the user is currently working with. 

Other things worth considering:  

1. When working with app-specific attribute settings, is the tree going to self-populate with only those attributes that are available/exposed by that app (as opposed to a pre-defined list that we come up with)?  I think doing so would be cool.

2.  With both the default and the app-specific settings, the first time the user
gets into the dialog, the tree will be populated by us/the app's reported default values (right?).  Subsequently, however, it will be populated by  whatever the user established.  It would be nice to have a way to restore the tree contents to the original, pre-customized, "factory default" list.

Okay, "Comments?" back at ya. ;-)

Thanks Joanie.

> I like your suggestions Rich.  However, I'm not sure I follow what you mean by:
>
>> the first one having a higher priority than the second

I actually meant implementation wise rather than preference order when
deciding whether the text attribute was application. Application specific
settings should always trump default settings.

>I like the table you described.  I assume the buttons would be labeled in such
> a way that Orca would speak their function rather than the punctuation
> displayed.

Right. 

> Given the large number of attributes, at least in some apps, I'd like to
> propose the addition of buttons to check/tick all and to uncheck/untick all.

Okay.

> In terms of setting the default attributes versus app-specific attributes, I
> can see a couple of possibilities:

I prefer your suggested choice #1.

> Other things worth considering:  
>
> 1. When working with app-specific attribute settings, is the tree going to
> self-populate with only those attributes that are available/exposed by that app
> (as opposed to a pre-defined list that we come up with)?  I think doing so
> would be cool.

I hadn't thought that far, but it should be doable (and nice).

> 2.  With both the default and the app-specific settings, the first time the
> user
> gets into the dialog, the tree will be populated by us/the app's reported
> default values (right?). 

Yes.

> Subsequently, however, it will be populated by 
> whatever the user established.  It would be nice to have a way to restore the
> tree contents to the original, pre-customized, "factory default" list.

Ah. Good point. That should be there too.

Okay, this is starting to gel. Mike, it would be nice to see your input.

Thanks!

Mike accidentally put this comment in the wrong bug. Here it is:

"I think what we really need here is the ability to alter the attributes spoken
by insert+f either by modifying the default or via the app specific settings. 
I'd like to propose a new "text attributes" tab for the orca prefs dialog. 
This page would be laid out as follows.  
The first control on this page would be a list of the attributes which will be
spoken.  This list will be in speaking order.  
This list will be followed by 3 buttons.  remove, move up, and move down which
will apply to the first list.
Following these three buttons we will have another list containing all possible
attributes excluding those in the first list.  
Following this list will be an add button which will add the selected attribute
to the bottom of the first list.  
Following the add button will simply be the normal OK cancel and apply buttons. 
If the user presses remove on an attribute in the first list it should be put
back in the second."

Created attachment 89506 [details]
Glade prototype.

Mike, to try to avoid implementing this half a dozen times, I'd
like to come to a concensus on what the GUI should like 
like if possible.

I've created and attached a simple Glade project that 
implements my understanding of what Mike wants for the GUI
in comment #6. It's not part of a tabbed page. There are no
OK , Canel and Apply buttons. Think of it as the filler in
the actual pane.

Here's how to try it:

1/ Save the attachment as project1.tar.gz

2/ In a terminal window, unpack with:

  % gzip -dc project1.tar.gz | tar -xvf -

3/ In a terminal window, change directories to "project1" and type:

  % autogen.sh
  % make

4/ In a terminal window, changes directories to "src" and type:

  % ./project1

I haven't created any callbacks yet or populated the two lists.
This protype is just to get agreement on how the GUI should look.
Don't fixate on component positioning either. I'm looking for
feedback on component labelling and whether we need other new
components. Should there be any frames (panels) to help clarify
what buttons apply to what lists?

From previous experience and from trying this out, I believe
we still have work to do.

What about if I'd like to remove all the attributes I've
currently got in the first list and start all over again. 
With the existing proposal, this could be a painful process
if I've already added several and have to remove them one
at a time (or make a multiple item selection). I suggest we 
also need a "Remove all" button.

In a similar vein, what if I want all (or nearly all) the
available attributes. It's painful to move them all up one
at a time (or have to select them all first). I suggest we 
also add a "Add all" button in the bottom row.

One other approach we might want to consider is that the second
line contains the text attributes that aren't in the first list.
In other words, when you "Add" an attribute from this second list,
it gets put in the first list and removed from the second. The
label for the second list would then be something like 
"Other attributes:".

Finally, where should this new tab go in the Orca preferences
dialog? What position?

I like the prototype here.  I think it would be a good idea to put each section into a panel.  Would it be possible to make the two lists multi-select.  This would be nice for performing operations on multiple items.  > 
> What about if I'd like to remove all the attributes I've
> currently got in the first list and start all over again. 
> With the existing proposal, this could be a painful process
> if I've already added several and have to remove them one
> at a time (or make a multiple item selection). I suggest we 
> also need a "Remove all" button.
I'm afraid a "remove all" would cause a mess for users.  I think beginning type users would make a real mess with there list of attributes.  I think my multi-select list above would be a better option.
> 
> In a similar vein, what if I want all (or nearly all) the
> available attributes. It's painful to move them all up one
> at a time (or have to select them all first). I suggest we 
> also add a "Add all" button in the bottom row.
Once again I prefer the multiselect option.  
> 
> One other approach we might want to consider is that the second
> line contains the text attributes that aren't in the first list.
> In other words, when you "Add" an attribute from this second list,
> it gets put in the first list and removed from the second. The
> label for the second list would then be something like 
> "Other attributes:".
I aggree 
> 
> Finally, where should this new tab go in the Orca preferences
> dialog? What position?
At the far right end even after the app specific settings if there are any.  If this isn't possible just before the app specific settings is OK. 
> 

> I think it would be a good idea to put each section into a panel.

What would you want the labels on those four panels to be?

>  Would it be possible to make the two lists multi-select. 

Sure.

> At the far right end even after the app specific settings if there 
> are any.  If this isn't possible just before the app specific settings 
> is OK.

I'll put it just before the app-specific settings tab (if any).

Thanks.

Adding "[mike]" back as there is a new unanswered question.

Mike, I'm curious about your decision to use two lists rather than a single list of items which can be checked/unchecked.

Looking at this from the perspective of high-magnification users who employ speech but tend to rely upon vision, I think the single-list approach is preferable:  It communicates the maximum amount of information in the smallest amount of space, and it enables the user to change settings within the list (i.e. without having to go find the Add or the Remove button) -- both of which reduce the need to shift the magnified view.  Such an approach would also make this new addition to the Preferences dialog have a look and feel consistent with what we already have in place on the Keybindings page.

Just a thought....

I'm with Joanie on this (see comments 2-4 above). Let me generate
another prototype tomorrow for you to play around with. Thanks.

Sorry, make that comments 2,4 and 5 above.

(In reply to comment #11)
> Mike, I'm curious about your decision to use two lists rather than a single
> list of items which can be checked/unchecked.
> 
> Looking at this from the perspective of high-magnification users who employ
> speech but tend to rely upon vision, I think the single-list approach is
> preferable:  It communicates the maximum amount of information in the smallest
> amount of space, and it enables the user to change settings within the list
> (i.e. without having to go find the Add or the Remove button) -- both of which
> reduce the need to shift the magnified view.  Such an approach would also make
> this new addition to the Preferences dialog have a look and feel consistent
> with what we already have in place on the Keybindings page.
Thanks for the thought.  I actually thought about this when I was specing this out.  The reason I discarded this idea whas that I thought it made the whole concept of reordering the list of chosen attributes a lot more confusing.  I didn't like the idea of presenting "move up" and "move down" buttons for items that weren't checked.  I realize that you could grey the buttons in this case but still thought it was a bit confusing.  
> 
> Just a thought....
> 

> Thanks for the thought.  I actually thought about this when I was specing this
> out.  The reason I discarded this idea whas that I thought it made the whole
> concept of reordering the list of chosen attributes a lot more confusing.  I
> didn't like the idea of presenting "move up" and "move down" buttons for items
> that weren't checked.  I realize that you could grey the buttons in this case
> but still thought it was a bit confusing.  

Fair enough.  I hope you'll permit one last plea for consideration. <grin>

To play devil's advocate:  What if I want to be able to reorder items that are not checked? :-) Just because I'm not interested in knowing the paragraph style for this document doesn't mean that I am not interested in the paragraph style's position relative to the other attributes.  On those occasions when I do want to know the paragraph style, I'd like to be able to quickly check it.  I don't want to then have to move it where it belongs (after first having had to move it into the "I care about it" list).

To play advocate:  The ironic thing timing-wize is that when you called me this evening to discuss this bug and I indicated that office hours was running late, it was because I was still working with one of my students with low vision and she required a *considerable* amount of time to locate things on the screen visually. 

For a user using full screen magnification, at magnification level M only 1/M^2 of the original display can fit on the screen at any given time.  The woman in question uses 6x magnification.  Thus only 1/36th of the display could be accessed at a time -- assuming no field loss, of course.  That's less than 3% of the screen contents.  The other 97% is out there.... somewhere.... and often needs to be found.  I really think we need to do what we can to minimize the need to go hunting for things.  Placing a checkbox to the left of the attribute name and using one list instead of two helps in that regard.

Created attachment 89564 [details]
Second Glade prototype.

Here's a second prototype using an approach similar to
what was suggested in comments 2-5 above.

Here's how to try it:

1/ Save the attachment as project3.tar.gz

2/ In a terminal window, unpack with:

  % gzip -dc project3.tar.gz | tar -xvf -

3/ In a terminal window, change directories to "project3" and type:

  % autogen.sh
  % make

4/ In a terminal window, changes directories to "src" and type:

  % ./project3

Note that it's not a full blown implementation, but I
took it a little further than the previous prototype.

* The text attribute list is populated. The initial
  items are the ones that are spoken by default. The 
  other (unchecked) ones are initially in alphabetical 
  order below.

* The buttons have mnemonics.

* There are skeleton callback entries for the buttons
  that currently don't do anything apart from print a 
  debug message to stderr.

* I put in a skeleton callback for a KeyPress event when
  focus is in the text attribute list. The planned 
  implementation here would be to allow you to type in 
  enough (and press Return) to immediately get to the 
  row you are interested in.

Questions to ask here are:

1/ Are the labels for the two frames (panels) what you would like?
   A follow-on question to this is what should the Orca Preferences 
   dialog page tab for this page be? Should it be "Text"
   or "Text Attributes"? My thought was on the former as there 
   might be other text related preferences that we'd want to 
   add to that panel over time. And that it's shorter.
   We need to decide.

2/ Are the labels of the buttons what you would like?

Thanks.

A couple more thoughts here:

1/ When a text attribute list item is checked, it could
   be automatically moved up to just below the other checked
   items. That would make it much easier to move into it's
   final desired position.

2/ When an item is unchecked in the list, it could be automatically 
   moved to its alphabetical position in the unchecked items
   at the bottom of the list.

I also note that the Home key takes you to the top of the list.

I personally much prefer the first example but you both seem to be pretty in love with this way so I'm fine with it.  I'd personally lose the add all and remove all buttons as I think users will use them and then get confused by the drastic change but that's just me.  

Okay, I'll go ahead and start implementing this second approach
in the Orca preferences dialog. Thanks.

Mike, what do you want the label on the tab called? "Text"?
"Text Attributes"? Or something else?

I also assume that you are happy with the labels for the two
frames (panels) and the various buttons?


B.t.w. here's where I think something like the "Remove all" button
can really help, assuming we adopt my two other extra suggestions 
from comment #17.

Say for a particular application, you just wanted to have
the "family-name", "size" and "style" attributes spoken.
Here's how you could do it.

1/ Startup that application.

2/ Insert-Control-Space to bring up the application-specific
   settings dialog.

3/ End to get to the Text attributes pane.

4/ Alt-u to remove all the currently checked attributes.

5/ Shift Tab, Shift Tab to get focus back to the attribute list.

6/ "fa", Return, Space to move focus to the "family-name" text
   attribute and to then automatically move that checked attribute 
   to the top of the list.

7/ "si", Return, Space to move and check the "size" attribute to second in
   the list.

8/ "sty", Return, Space to move and check the "style" attribute to third place
   in the list.

9/ Then press OK and those text attributes are set to be spoken for 
   that application.

This seems very straight forward to me.

I think "style and attributes" is more descriptive.  Or perhaps text attributes.  Which ever fits best is fine with me.

Another thing to decide:  What should be spoken when using the various move functions?  The item's new position within the list?  Something else?

One of the things that hasn't been spec'ed at the moment is
whether we are going to allow the users to adjust the "default"
settings for the spoken attributes. In other words, currently
we only speak these settings when the value is different from
the default.

We've only done this for a few attributes so far. These are:

weight:400; 
indent:0; 
underline:none; 
strikethrough:false; 
justification:left; 
style:normal

If we are going to allow this, then the text attribute field on the
pane is going to have to be editable.

We are also going to have to determine what the "default"
setting is for each of the attributes.

Here's the list of all attributes:

    "bg-color",
    "bg-full-height",
    "bg-stipple",
    "direction",
    "editable",
    "family-name",
    "fg-color",
    "fg-stipple",
    "indent",
    "invisible",
    "justification",
    "language",
    "left-margin",
    "pixels-above-lines",
    "pixels-below-lines",
    "pixels-inside-wrap",
    "right-margin",
    "rise",
    "scale",
    "size",
    "stretch",
    "strikethrough",
    "style",
    "underline",
    "variant",
    "weight",
    "wrap-mode",

What should there "default" values be?
How do we show the user what possible values are allowed for each attribute?

This is starting to get ugly.

My own personal opinion is that we should adjust the way that text
attributes are spoken. If the user has checked a particular text
attribute, then it will always be spoken.

Comments?

> My own personal opinion is that we should adjust the way that text
> attributes are spoken. If the user has checked a particular text
> attribute, then it will always be spoken.

For some attributes I think that makes sense; for others I'm not so sure.  My guess is that if a user selects things like weight, underline, and strikethrough they will only want to have it spoken if it's different from the norm.

If we don't want the complexity of a multi-columned, editable tree, what about this:  If the attribute is not None or False or, in the case of weight, 400 speak it? 

> If we don't want the complexity of a multi-columned, editable tree, what about
> this:  If the attribute is not None or False or, in the case of weight, 400
> speak it? 

Don't forget "0" or "left" or "normal".

Or more generically, if the attribute name field end with ":<whatever>"
then use that as the default value and don't speak it unless it's different.
We should also show those values in the tree view list.
We can also probably make those fields editable so the user can change them.

If we want the user to be able to change the "default" value for all
attributes, then we are back to my two questions:

What should their "default" values be?
How do we show the user what possible values are allowed for each attribute?

> Don't forget "0" or "left" or "normal".

I'm not.  :-)   I looked at your suggestion of always speaking the checked attributes and asked myself when that would bug me.  :-)  I concluded that for items that had a numeric value (margins, indents, etc.) hearing the 0 wouldn't bother me.  Same thing for left justification.  I was somewhat torn on "normal".... 

Put another way, I'm cool with your proposal from comment #22 with the modification that we only do it if it has a value (i.e. is not None or False).  Weight is the exception because from a practical point of view it means "bold" but it seems to only be "set" if it's greater than 400.

If we want to go with only speak it if it's not the default then we do indeed need to answer your questions.

> We should also show those values in the tree view list.

Yup.

> We can also probably make those fields editable so the user can change them.

Yup.  Can we do it similar to what we do on the keybindings page, and make it a separate column?  Perhaps the "speak unless" column? :-)

> What should their "default" values be?

Hmmmm.... If we could ask the app for that, I'd say that's what we should do.  But as I recall, what we get out of OOo Writer for getDefaultAttributes() is based on the current character.  I'd have to go back and double check that, however.  If we can't count on getDefaultAttributes() as a general rule, could we use it in a "clean" document to obtain those values?

> How do we show the user what possible values are allowed for each attribute?

Do we need to, or can we assume that a user who has this advanced need can do some figuring out?  That said....

The more I think about it, the more I like your original proposal with my modification.  :-)  That would certainly meet most users' needs, and as you pointed out earlier, "this is starting to get ugly." ;-) ;-)

Created attachment 89760 [details] [review]
First cut at a patch to implement this feature.

Joanie and I tag teamed over the weekend and wrestled The Patch into
submission. Here's a first cut ready to be tested. There is one known
problem. When you go to edit one of the values in the "Spoken unless"
column, the following message is displayed in the terminal window where
Orca was started:

/usr/lib/python2.5/site-packages/orca/braillegenerator.py:1540: GtkWarning: gtk_list_store_get_path: assertion `iter->stamp == GTK_LIST_STORE (tree_model)->stamp' failed
  desc = parent.table.getRowDescription(row)

Will gave me a couple goggled pointers to what this might mean, but I
haven't solved it yet. I'll investigate this in parallel with it being tested.

Two other things to note.

1/ We have enabled multiple row selections. We found that 
  checking/unchecking a particular text attribute in
  combination with using one of the keyboard accelerators 
  to move it around right away worked quite effectively. 
  This can easily be adjusted if others find this not to 
  be the case.

2/ We did not implement the check-then-move-to-top,
   uncheck-then-move-to-bottom suggestion in comment #17. 
   It's trival to just remember to use the move commands as you 
   adjust the current attribute.

Created attachment 89831 [details] [review]
Revised version of patch.

Revised patch ("Speak all" and "Speak none" buttons hidden). 
Patch committed. Please test.

This looks good to me.  We might want to leave it in pending for a couple days though just until the community has a bit more time to pound on it.  

Lets call this one good. 

Closing as FIXED.

Created attachment 90913 [details] [review]
slight tweak

Rich and I found that the current implementation will generate errors if ~/.orca is not present.  The attached should solve that and is also consistent with what we're doing with keybindings.

Rich please review.

This works great Joanie. I'd just say leave it as is for now
(and not move defScript to one of the init routines as we discussed).
Please commit. Thanks!

Done.  Thanks Rich!