On 07/24/2012 07:44 PM, Sascha Silbe wrote: > The only document that contains at > least some minor hints is the "GNOME Accessibility Developers > Guide" [2], but all it does is mention two examples [3,4] for > descriptions and roles.
Unfourtunately all those are somewhat outdated. "Update accessibility guides" was on our TODO list for a long time. Something that it is important in order to get new developers helping. > The ATK Best Practices wiki page [5] might have > been what I'm looking for, but it's just a list of things that _should_ > be documented, rather than the documentation itself. Well it has "DRAFT DRAFT" at the beginning ;) But yes, at this moment it is a list of things that should be documented. That page was started in order to document good practices for an accessibility implementation, as a lot of the required information doesn't fit on ATK documentation itself, as ATK documentation should be mostly an API reference. > > Is there any document I missed and that would tell me what attributes I > should add to the widgets used in Sugar and what values to give them? Well you are going in the good path providing names, descriptions and roles. As I mention below, states are also important. > > Some concrete questions I already have: > > 1. Which attributes should be translated? > > Gnome#525226 has some discussion about whether accessibility-name > and / or accessibility-description should be translated, but there's > no conclusion. I have added a comment to that bug. Anyway to anyone reading the list: the general rule is that any string that could be presented to the user should be a translated strings. Action names are a corner case because those names could be used on some heuristics. Like a voice control application that want to check if you can "click" on an element. But for the case of actions, you have atk_action_get_name and atk_action_get_localized_name. Anyway it is true that this can be confusing, and that properly the documentation should be explicit about that. > > What parts of the ATK API should be filled with english texts and > what parts should be filled with translated texts? See my previous comment. > How should > automated tools (e.g. test suites) discover elements and what texts > should tools for users (e.g. screen readers) present to the user? I guess that are you asking how a test suite could search for a button with the name "press here please" always. On my previous experiences with test suites, they are usually run on a controlled environment. And usually as part of that control, the language is always the same. If they make tests for other languages, they need to know how each name is translated. This is usually also easy, because as part of that "controlled environment" they have access to the translation files. > > 2. How should accessible-name and accessible-description be worded? > > The only hint I could locate were two examples [3,4] for > accessible-description: "Opens Preferences dialog" > > Like with other parts of the UI, consistent wording is important to > users. If different applications use different tense or different > style (active/passive etc.), users can get confused. This is even > more true for users with disabilities. Tools (like the test suite I'm > going to work on) OTOH can easily cope, they only care about syntax > (i.e. string literals), not semantics. I agree, and in fact this has been fuzzy for a long time. On the last ATK hackfest we were talking about that, mainly because usually the tooltip was used as description, when usually are not the same. AFAIR at that moment we talked about accessible-name, adding accessible-hint (or something like that), and accessible-description. We also tried to define all of them. I will search my notes to check if we came to a conclusion. Not sure what to say about wording. Probably that fits on the previous general guide, but properly on a language-specific section ie: I guess that active/passive is something that only applies to some specific languages. > > 3. What attributes other than accessible-name, accessible-description > and accessible-role are usually important to users and what values > should they have? The state of the object are also important (ie: know if a check button is checked or not) > > 4. The description of most attributes on AtkObject [7] is pretty > weird. It says the properties are "used to notify that the > [attribute] has changed". Well, it doesn't happens on all properties, but I agree that on the ones happening is weird. After answering this mail I will open a bug in order to improve that documentation. > What does that mean? On GObject each time a property change, it emits the signal "notify", so you can connect to that signal to know when it changes. So probably that documentation was just a brain dump of the developer adding that property. > I would expect signals > to be used for change notification, not properties. Do I need to do > anything about those or will GTK already handle that for me in all > cases? Yes I think that you don't need to do anything. Thanks for the feedback. BR -- Alejandro Piñeiro Iglesias _______________________________________________ gnome-accessibility-list mailing list gnome-accessibility-list@gnome.org https://mail.gnome.org/mailman/listinfo/gnome-accessibility-list
