Consider clarifying that IA2 live region updates also require information in get_newText() and get_oldText()

[sivakusayan]

I notice sometimes that people who are new to the IA2 API, including myself, don't realize that live region insertions require the new text to be returned in the next call to IAccessibleText::newText. Similarly that live region deletions require the old text to be returned in IAccessibleText::oldText (although I'm not sure if oldText is ever used in practice?).

I think it would be nice if this context was given in "Exposing additional useful information" section under the Changes to document content or node visibility heading.

[benbeaudry]

Fair point. I was personally not aware of this requirement either and it could be helpful to explicitly point it out here. Would you like to put together a PR fixing this?

On another somewhat related note, I believe we should update the UIA cells for section 4.8.2 to clarify, just like we did for the AX API, that "if in a live region, EVENT_OBJECT_LIVEREGIONCHANGED", as the documentation specifies that this event should only be fired for content within a live region. See https://learn.microsoft.com/en-us/windows/win32/winauto/event-constants for EVENT_OBJECT_LIVEREGIONCHANGED.

[sivakusayan]

Yeah, I can try putting that together. The UIA change should be straightforward.

I guess the only thing I'm not immediately sure about is whether user agents SHOULD or MUST return the new text in the next call to get_newText() after firing IA2_EVENT_TEXT_INSERTED. My immediate instinct is that it MUST, since the event doesn't really make sense otherwise. But I noticed that the ax_dump_events utility seems to do an if check on the return value of get_newText(), instead of asserting it must always work with a DCHECK. Which maybe means there are cases where it can fail? I'll probably look into this more and see how Firefox does this logic too, maybe a MUST is still appropriate.

As an aside, there does seem to be some kind of nuance in deciding what the inserted text will be. For example, Chromium seems to compute what the inserted text is slightly differently if the text is in an editable or non-editable container. I'm not sure if that nuance is currently in the spec, but maybe that should be a separate issue and can be considered out of scope for this PR.

[spectranaut]

Hi @sivakusayan ! If the screen readers and assistive technologies expect the next call to get_newText(), then it should be a MUST. It would be great if you could submit a PR with this addition! :)

by the way, ax_dump_events is simple a tool for watching accessibility events in the chromium application (or any other application, actually) -- so there shouldn't be any DCHECKs in there. The tool is just reporting what the application is sending out via accessibility events, it is not an implementation of the APIs.

You are right, i do not think that "which text" should be sent is all that well specified, but that kind of specification is not necessarily platform-specific so would belong in the ARIA spec itsself: https://w3c.github.io/aria/. Core-AAM is really only for platform-specific specifications.