[Bug 684630] New: Documentation of the signal "visible-data-changed" is not enough

[atk]

https://bugzilla.gnome.org/show_bug.cgi?id=684630
atk | atk | unspecified

Summary: Documentation of the signal "visible-data-changed" is
not enough
Classification: Platform
Product: atk
Version: unspecified
OS/Version: Linux
Status: NEW
Severity: normal
Priority: Normal
Component: atk
AssignedTo: atk-...@gnome.bugs
ReportedBy: apin...@igalia.com
QAContact: atk-...@gnome.bugs
GNOME version: ---


Looking at the current ATK implementations:
* gtk emit it sometimes
* clutter/st not emit it
* WebKitGTK doesn't emit it either.

This signal is also available on atspi and KDE developers are wondering when
they need to emit it.

Lookin at the current documentation:

http://developer.gnome.org/atk/stable/AtkObject.html#AtkObject-visible-data-changed
The "visible-data-changed" signal is emitted when the visual appearance of the
object changed.

This is not enough, IMHO, to know when and how to emit it. Gtk is the example
that the signal is emitted, so I assume that useful for AT, but obviously is
not enough to know when to emit it, as it is not emitted on any "visible-data"
change.

This is also related with all the work about common, shareable and
cross-toolkit accessibility implementation guidelines.

--
Configure bugmail: https://bugzilla.gnome.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching all bug changes.

[atk]

https://bugzilla.gnome.org/show_bug.cgi?id=684630
atk | atk | unspecified

Alejandro Piñeiro Iglesias (IRC: API) <apinheiro> changed:

What |Removed |Added
----------------------------------------------------------------------------
CC| |jdi...@igalia.com

[atk]

https://bugzilla.gnome.org/show_bug.cgi?id=684630
atk | atk | unspecified

André Klapper <a9016009> changed:

What |Removed |Added
----------------------------------------------------------------------------
CC| |a901...@gmx.de

[atk]

https://bugzilla.gnome.org/show_bug.cgi?id=684630
atk | docs | unspecified

Alejandro Piñeiro Iglesias (IRC: API) <apinheiro> changed:

What |Removed |Added
----------------------------------------------------------------------------
CC| |f...@gpul.org
Component|atk |docs

[atk]

https://bugzilla.gnome.org/show_bug.cgi?id=684630
atk | docs | unspecified

--- Comment #1 from José Millán Soto <f...@gpul.org> 2012-09-22 19:48:00 UTC ---
IAccessible2 has a similar event.
Acording to [1]: "IA2_EVENT_VISIBLE_DATA_CHANGED A visible data event
indicates the change of the visual appearance of an accessible object. This
includes for example most of the attributes available via the
IAccessibleComponent interface." (IAccessibleComponent has 3 properties:
location, background color and foreground color)

[1]
http://accessibility.linuxfoundation.org/a11yspecs/ia2/docs/html/_accessible_event_i_d_8idl.html

[atk]

https://bugzilla.gnome.org/show_bug.cgi?id=684630
atk | docs | unspecified

--- Comment #2 from Alejandro Piñeiro Iglesias (IRC: API) <apin...@igalia.com> 2012-09-22 21:33:14 UTC ---
(In reply to comment #1)

> IAccessible2 has a similar event.
> Acording to [1]: "IA2_EVENT_VISIBLE_DATA_CHANGED A visible data event
> indicates the change of the visual appearance of an accessible object. This
> includes for example most of the attributes available via the
> IAccessibleComponent interface." (IAccessibleComponent has 3 properties:
> location, background color and foreground color)
>
> [1]
> http://accessibility.linuxfoundation.org/a11yspecs/ia2/docs/html/_accessible_event_i_d_8idl.html

That seems to suggest that each time something like that changed, the signal
need to be emitted. Something that seems an overkill.

Looking at Orca, I only found a reference to that signal, onVisibleDataChanged
at thunderbird/script.py, and it seems that it is never called/used (so
probably it was something used in the past, but not anymore).

Anyway, this let me to take a look to Gecko code, and I only found a reference
to this signal:


case nsIAccessibleEvent::EVENT_SECTION_CHANGED:
MAI_LOG_DEBUG(("\n\nReceived: EVENT_SECTION_CHANGED\n"));
g_signal_emit_by_name(atkObj, "visible_data_changed");
break;

So it really seems that it is not only badly defined, but not used at all. So I
see two options right now:

* It is not used because it was badly defined, so badly implemented => improve
documentation/guidelines, ask implementors to implement it properly, notify AT
that they can use it again
* It is not used because it is not required => deprecate it documenting why it
is not required, add that documention to the guidelines, ask implementors to
stop to emit it