[Accessibility-ia2] Explicit name

[Pete Brunet]

Hi Jamie, Picky is good - I appreciate it!  Here is the new text
assuming the method is in IAccessibleText:

HRESULT isNamePreferred([out, retval] boolean* isPreferred);

Indicates that a content author has provided ancillary text in addition
to the primary text of an object and that the server has chosen to use
that ancillary text for this object's accessible name in preference to
the object's primary text.

A true value indicates that the accessible name is different from, and
more meaningful than, the text that is returned from
IAccessibleText::text.  Typically an object's accessible name is taken
directly from the object's textual content and is equivalent to the text
from IAccessibleText::text, but a true value is returned when the server
has chosen to use ancillary text rather than the accessible's primary
textual content when generating the accessible name.

Some examples that could be seen in an IAccessible2 implementation of a
web browser are:

1) <a href="http://www.adomain.com">content</a>  In this case the
accessible name will be "content" and isPreferred will be false.

2) <a href="http://www.adomain.com" title="a title">content</a>  If the
title text is used for the accessible name, isPreferred will be true.

3) <a href="http://www.adomain.com" aria-label="a label">content</a>  If
the aria-label text is used for accessible name, isPreferred will be true.

4) <div id="label">a label</div><div role="radio"
aria-labelledby="label">content</div>  If the label text is used for the
accessible name, isPreferred will be true.

If this method returns true assistive technology may choose to present
the user with the accessible name rather than the text from
IAccessibleText::text.

Parameters:
isPreferred is true if the server prefers the use of the accessible name
over the text from IAccessibleText::text.

Return values:
S_OK


On 7/26/2011 6:45 PM, James Teh wrote:
> Sorry to be picky, but... :)
>
> On 27/07/2011 12:16 AM, Pete Brunet wrote:
>> HRESULT isNamePreferred([out, retval] boolean* isPreferred);
> I think I like this new method name.
>
>> Indicates that a content author has provided ancillary text in addition
>> to the primary text of an object and that the server has chosen to use
>> that ancillary text for this object's accessible name in preference to
>> object's primary text.
> Perhaps "in preference to *the* object's primary text" (missing "the")
>
>> Since this method is only useful when IAText is implemented I think this method belongs in IAText instead of IA2_2.  In that case I'd remove the S_FALSE return value.  Is that acceptable?
> Makes sense. In that case, this sentence:
>> This method is only useful when the IAccessibleText interface is
>> implemented and a true value indicates that the accessible name is...
> can be changed to just:
> "A true value indicates that the accessible name is..."
>
> If others disagree that this belongs in IAText, I think that sentence 
> should be changed to:
> "This method is only useful when the IAccessibleText interface is
> implemented. In this case, a true value indicates that the accessible 
> name is..."
> (Currently, it sounds like it is only useful if a true value is 
> returned. :))
>
> Jamie
>

-- 
*Pete Brunet*
                                                                
a11ysoft - Accessibility Architecture and Development
(512) 467-4706 (work), (512) 689-4155 (cell)
Skype: pete.brunet
IM: ptbrunet (AOL, Google), ptbrunet at live.com (MSN)
http://www.a11ysoft.com/about/
Ionosphere: WS4G
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.linux-foundation.org/pipermail/accessibility-ia2/attachments/20110726/0afe43a9/attachment.htm