GNOME Bugzilla – Bug 648260
Improve the documentation of ATK_STATE_VISIBLE and deprecate ATK_STATE_SHOWING
Last modified: 2021-06-10 11:25:08 UTC
We currently have: ~~~~~~~~~~~~~~~~~ ATK_STATE_VISIBLE Indicates this object is visible, e.g. has been explicitly marked for exposure to the user. ATK_STATE_SHOWING Indicates this object, the object's parent, the object's parent's parent, and so on, are all 'shown' to the end-user, i.e. subject to "exposure" if blocking or obscuring objects do not interpose between this object and the top of the window stack. ~~~~~~~~~~~~~~~~~ Problems/Issues/Questions: 1. In many cases these coincide. Example: A tooltip pops up. We get two object:state-changed events and have two states to let ATs know the tooltip is there. 2. In some cases where they do not coincide (e.g. a menu item in a closed menu; a paragraph that is off screen at the moment within the current document), we see confusion on the part of implementors as to what the right state is. 3. Whether or not something is on the screen IS relevant to screen readers. Example: Orca's flat review feature provides a "frozen," "birds eye" view of what's on the screen. In this mode, Orca should not present what's off the screen. Thus we need to know if it's "viewable by a sighted user right now." Whether or not it "could be visible if the user did foo" (where foo is, say, open the parent menu) is of no concern to a screen reader. None. It is assumed the user will, if interested, do foo, navigate to the object, and we'll present it then. Otherwise, we simply don't care. :-) 4. Whether or not something can be seen by a sighted user is (afaik) of no interest to an alternative input device. BUT whether or not it "could be visible if the user did foo" is. For instance, an alternative input device might wish to make all menu items available to the user without forcing the user to physically open each menu. Given all of the above, would it make sense to: 1. Have one state that means "Sighted users can see it right now, just by using their eyes." 2. Stop exposing (to ATs) "accessible" objects which are not truly accessible because the user cannot see or interact with them in any fashion* with or without an AT. ? Or to put it another way: Do we really need both of these states, and the associated events, and the associated implementor confusion? (And if the answer is "Yes, we do." then let's repurpose this bug to reflect the need for better documentation, best practices, samples/demos, etc.) *Note: We already have other states like: ~~~~~~~~~~~~~~~~~ ATK_STATE_ENABLED Indicates that this object is enabled, i.e. that it currently reflects some application state. Objects that are "greyed out" may lack this state, and may lack the STATE_SENSITIVE if direct user interaction cannot cause them to acquire STATE_ENABLED. See also: ATK_STATE_SENSITIVE ATK_STATE_SENSITIVE Indicates this object is sensitive, e.g. to user interaction. STATE_SENSITIVE usually accompanies STATE_ENABLED for user-actionable controls, but may be found in the absence of STATE_ENABLED if the current visible state of the control is "disconnected" from the application state. In such cases, direct user interaction can often result in the object gaining STATE_SENSITIVE, for instance if a user makes an explicit selection using an object whose current state is ambiguous or undefined. see STATE_ENABLED, STATE_INDETERMINATE. ~~~~~~~~~~~~~~~~~ To communicate to ATs that while one "can see it" something else is preventing the user from interacting with it at the moment.
(In reply to comment #0) > We currently have: > > ~~~~~~~~~~~~~~~~~ > ATK_STATE_VISIBLE Probably inherited from the VISIBLE state of gtk (and then also used on clutter). > ATK_STATE_SHOWING More useful in the practice (I guess that in your case, this is the one that you look for) > Problems/Issues/Questions: > > 1. In many cases these coincide. Example: A tooltip pops up. We get two > object:state-changed events and have two states to let ATs know the tooltip is > there. There is any problem if the ATs get two state-changed events? After all, this is what is happening. > 2. In some cases where they do not coincide (e.g. a menu item in a closed menu; > a paragraph that is off screen at the moment within the current document), we > see confusion on the part of implementors as to what the right state is. Well, in this example it would not include ATK_STATE_SHOWING, and ATK_STATE_VISIBLE would depend on the internal state of the object. And if there is any confusion, it is a bug on the atk implementor. > 3. Whether or not something is on the screen IS relevant to screen readers. > Example: Orca's flat review feature provides a "frozen," "birds eye" view of > what's on the screen. In this mode, Orca should not present what's off the > screen. Thus we need to know if it's "viewable by a sighted user right now." > Whether or not it "could be visible if the user did foo" (where foo is, say, > open the parent menu) is of no concern to a screen reader. None. It is assumed > the user will, if interested, do foo, navigate to the object, and we'll present > it then. Otherwise, we simply don't care. :-) So I guess that you just check ATK_STATE_SHOWING. > 1. Have one state that means "Sighted users can see it right now, just by using > their eyes." This is more or less the definition of ATK_STATE_SHOWING. > 2. Stop exposing (to ATs) "accessible" objects which are not truly accessible > because the user cannot see or interact with them in any fashion* with or > without an AT. > > ? Well here you are implying that *all* the ATs will just require those kind of objects. Sincerely it seems a strong statement. I also had this doubt on my experience: right not cally expose all the objects in the clutter hierarchy. And I always thought if it has sense to expose objects like behaviours, effects, etc. But, from the implementor side, it is not trivial to make this filtering, although AFAIK, Webkit did the same. And in the same way, I always feared make this effort, and then realize that I'm "filtering too much". > Or to put it another way: Do we really need both of these states, and the > associated events, and the associated implementor confusion? (And if the answer > is "Yes, we do." then let's repurpose this bug to reflect the need for better > documentation, best practices, samples/demos, etc.) First, it is just about extra information. I really think that it is better to have extra information that not enough information (of course, with a limit, so it is good to debate that). Second, I find a situation where this information is useful. Automatic testing. Although the main purpose of the accessibility framework is accessibility (surprise!), the second big use case of this framework is the automatic testing. And I think that in this case it would be good to have those objects. > *Note: We already have other states like: > > ~~~~~~~~~~~~~~~~~ > ATK_STATE_ENABLED > Indicates that this object is enabled, i.e. that it currently reflects some > application state. Objects that are "greyed out" may lack this state, and may > lack the STATE_SENSITIVE if direct user interaction cannot cause them to > acquire STATE_ENABLED. See also: ATK_STATE_SENSITIVE > > ATK_STATE_SENSITIVE > Indicates this object is sensitive, e.g. to user interaction. STATE_SENSITIVE > usually accompanies STATE_ENABLED for user-actionable controls, but may be > found in the absence of STATE_ENABLED if the current visible state of the > control is "disconnected" from the application state. In such cases, direct > user interaction can often result in the object gaining STATE_SENSITIVE, for > instance if a user makes an explicit selection using an object whose current > state is ambiguous or undefined. see STATE_ENABLED, STATE_INDETERMINATE. > ~~~~~~~~~~~~~~~~~ > > To communicate to ATs that while one "can see it" something else is preventing > the user from interacting with it at the moment.
I officially withdraw this request. :-)
Reopening. During the ATK hackfest, some related issues were discussed, with the conclusion being these states need to be better documented so that implementors know what the heck they are.
[Mass-reassigning open atk bug reports for better trackability as requested in https://bugzilla.gnome.org/show_bug.cgi?id=653179 . PLEASE NOTE: If you have watched the previous assignee of this bug report as a workaround for actually getting notified of changes in atk bugs, you yourself will now have to add atk-maint@gnome.bugs to your watchlist at the bottom of https://bugzilla.gnome.org/userprefs.cgi?tab=email to keep watching atk bug reports in GNOME Bugzilla. Sorry for the noise: Feel free to filter for this comment in order to mass-delete the triggered bugmail.]
Some new information about it: <Company> fregl: does qt a11y implement ATK_STATE_SHOWING? <joanie> clown: but anyone using the "stable" release of Orca would not be impacted. <Company> hrm <Company> docs vs reality again <joanie> I like to think of our docs as poorly-written fiction <Company> gail implementation and atk docs don't agree <joanie> reference? <Company> ATK_STATE_SHOWING <Company> is defined as obj == VISIBLE && obj->parent == SHOWING <shaunm> joanie: I'm going to start making tshirts out of your quotes <Company> which is easy to do <Company> gail makes SHOWING mean "can be seen on screen" * joanie reviews the docs * joanie continues to hate this state <Company> so rows in the treeview can be not SHOWING when scrolled out of the scrolled window <joanie> Company: right <fregl> Company: for me currently I think showing == visible... <Company> fregl: i'll go that way, too, i think <joanie> that's why I hate these states <joanie> showing == can be seen on the screen (aka "visible" in English) <Company> invisible (in gtk terms) items don't eist in gail <Company> joanie: the problem is that that is really freakin hard to implement <Company> joanie: not the querying necessarily, but update notifications <Company> the only way to implement that correctly with current GTK is to do if (doing a repaint) recompute_all_the_showing_states(); <Company> which leads to an electicty bill due to the performance that is roughly as expensive as hiring indians to look at your screen and tell you whenever you need to know <API> back from lunch * API reading <API> Company, yes, it is true that going too far into the definition of SHOWING is just not practical * API looking at cally <API> in the case of clutter, ATK_STATE_VISIBLE==CLUTTER_ACTOR_IS_VISIBLE <API> and SHOWING==clutter_actor_get_paint_visibility (actor)) <API> in that sense, an actor change his SHOWING state when the mapped property changes <API> http://docs.clutter-project.org/docs/clutter/stable/ClutterActor.html#ClutterActor--mapped <Company> right <API> in the past clutter has a method that checks if an actor will be painted on the stage <API> I don't know the implementation details <API> don't know if they used occlusion culls or whatever <API> anyway, that method dissapeared <API> probably due this performance reasons <Company> but that means stuff that's scrolled out of view is still SHOWING * API looking for the name of that dead method * API knew that adding boring comments will worth <API> /* It would be good to also check if the actor is on screen, <API> like the old and removed clutter_actor_is_on_stage*/ <API> if (clutter_actor_get_paint_visibility (actor)) <API> atk_state_set_add_state (state_set, ATK_STATE_SHOWING); <API> Company, yes thats true <API> that SHOWING implementation is not 100% accurate <API> compared with the definition <API> but it is a good aproximation, imho * API looking the exact text of atk docs <API> well, documentation already have some exceptions like blocking or obscuring objects <Company> yeah, i think it's purely meant for scrolling, but even that is hard <Company> i mean, if i open a menu, it does not change the SHOWING state of toolbar items below the menu <Company> even though strictly speaking it should <API> well, as you said in the practice it is hard to go for that <Company> right <API> so probably we just need to add something like "except blocking, obscuring or if the object is out of the application viewport" <API> or something like that <Company> well <Company> i dunno about the usefulness of VISIBLE vs SHOWING at that point <API> taking into account that joanie also hates that state, I will look for that bug in which bug defending those two <API> so know I also need to take into account you ;) * API looking for that bug <API> https://bugzilla.gnome.org/show_bug.cgi?id=648260 <tota11y> Bug 648260: enhancement, Normal, ---, atk-maint, UNCONFIRMED, Improve the documentation of ATK_STATE_VISIBLE and ATK_STATE_SHOWING <API> right now is about documentation, but the initial description was about nuke one of those * API reading his old thoughts on that bug <API> well, it seems somewhat weak at this moment <API> my usual conservative pov of not removing stuff if not totally required, as some tools are using both <API> we can discuss this again, although at this moment probably it is worth to remove one <API> maintaining what ATK_STATE_SHOWING is supposed to be <API> although probably ATK_STATE_VISIBLE could be a better name <Company> i agree on all of that
Taking into account the conversation on comment 6: * We should remove one. * Maintain ATK_STATE_VISIBLE but updating the meaning, something more similar to the soon-to-be deceased ATK_STATE_SHOWING. Something like: ATK_STATE_VISIBLE: "Indicates this object, the object's parent, the object's parent's parent, and so on, are all 'shown' to the end-user, i.e. subject to "exposure" if blocking or obscuring objects do not interpose between this object and the top of the window stack, or the object is in the application viewport" Although not sure if "viewport" is too technical at this level of abstraction (anyway, old ATK_STATE_VISIBLE seems too low level, as seems just like a projection of GTK_IS_VISIBLE, in the same way that old ATK_STATE_SHOWING seems like a projection of GTK_IS_MAPPED).
Due recent issues related with the VISIBLE/SHOWING stuff I started to gather on what others do. Specifically, I started with IA2. As GTK+ developers did recently, the general rule is that non visible are not exposed to the accessibility clients. Anyway, they have a INVISIBLE state in order to at least provide an exception to that rule. Additionally, they provide a OFFSCREEN state, that gives extra info to the reasons of the INVISIBLE state. Note that additionally, they mention that although a object on INVISIBLE state is "allowed", it should not expose any children. This is similar to what aria does, as it just provides a hidden state [2]. The IA2 full description (from MSAA reference [1]): "STATE_SYSTEM_INVISIBLE The object is programmatically hidden. For example, menu itmes are programmatically hidden until a user activates the menu. Because objects with this state are not available to users, client applications should not communicate information about the object to users. However, if client applications find an object with this state, they should check to see if STATE_SYSTEM_OFFSCREEN is also set. If this second state is defined, then clients can communicate the information about the object to users. For example, a list box can have both STATE_SYSTEM_INVISIBLE and STATE_SYSTEM_OFFSCREEN set. In this case, the client application can communicate all items in the list to users. If a client application is navigating through an IAccessible tree and encounters a parent object that is invisible, Active Accessibility will not expose information about any possible children of the parent as long as the parent is invisible. " [1] http://msdn.microsoft.com/en-us/library/ms697270.aspx [2] http://www.w3.org/TR/wai-aria/states_and_properties#aria-hidden
There is a technique used with web pages for hiding content from sighted users while still providing the content to screen reader users. The rationale for this technique is that the information is redundant for sighted users, but needed by screen reader users. Putting aside the question whether the rationale is sound, the technique, in brief, involves positioning the content outside the viewing area of the web page such that it is clipped and cannot be scrolled into view. For example: <h2 style="position:absolute; left:-9999px; overflow:hidden">Function keys row</h2> FF provides an accessible for the heading. For IA2, the accessible has STATE_SYSTEM_OFFSCREEN. Of note, it does *not* have STATE_SYSTEM_FOCUSABLE, meaning that it cannot take keyboard focus. (Oddly, it does have STATE_SYSTEM_SELECTABLE). With respect to AT-SPI, the accessible has STATE_VISIBLE and STATE_SELECTABLE_TEXT. As with IA2, there is no STATE_FOCUSABLE. (The full set of states is enabled, opaque, selectable text, sensitive, and visible). The AT-SPI Component interface shows: - absolute position: -9851, 325 - relative position: -9998, 298 - size: 181 x 23 Thus, although there is no explicit offscreen state in ATK/AT-SPI, one can check that the content is outside the viewport by acquiring its extents from the Component interface. The above results are for the following page (link follows). Stripping out the CSS, the markup consists of a set of headings, <h2>, and unordered lists, <ul>, where the headings are positioned offscreen. The above results are for the first <h2>: http://help.apple.com/voiceover/vo/en/VOKeysBW_1.html More information about the offscreen technique can be found at WebAim: http://webaim.org/techniques/css/invisiblecontent/
(In reply to comment #8) Regarding the MSAA documentation: > > "STATE_SYSTEM_INVISIBLE > ... if client > applications find an object with this state, they should check to see if > STATE_SYSTEM_OFFSCREEN is also set. If this second state is defined, then > clients can communicate the information about the object to users. For example, > a list box can have both STATE_SYSTEM_INVISIBLE and STATE_SYSTEM_OFFSCREEN set. > In this case, the client application can communicate all items in the list to > users. > ..." FWIW, this could be interpreted as saying that the object isn't really invisible because it is simply out-of-view. Compare that with CSS "display:none" which means that the object is not rendered at all [1], and "visibility:hidden" which means the space is rendered, but not the contents [2]. [1] http://www.w3.org/TR/CSS2/visuren.html#propdef-display [2] http://www.w3.org/TR/CSS2/visufx.html#visibility
This blog post describes how Firefox uses ATK STATE_VISIBLE and STATE_SHOWING: http://asurkov.blogspot.ca/2012/02/firefox-12-for-at-developers.html Summary: * STATE_VISIBLE and STATE_SHOWING means rendered on screen, * STATE_VISIBLE but not STATE_SHOWING means not rendered on screen ("offscreen"), * neither STATE_VISIBLE nor STATE_SHOWING means hidden.
GNOME is going to shut down bugzilla.gnome.org in favor of gitlab.gnome.org. As part of that, we are mass-closing older open tickets in bugzilla.gnome.org which have not seen updates for a longer time (resources are unfortunately quite limited so not every ticket can get handled). If you can still reproduce the situation described in this ticket in a recent and supported software version of atk, then please follow https://wiki.gnome.org/GettingInTouch/BugReportingGuidelines and create a ticket at https://gitlab.gnome.org/GNOME/atk/-/issues/ Thank you for your understanding and your help.