Signals versus methods in ATK

[Luca Saiu <lsaiu hypra fr>]

Hello.

I see that many if not all ATK state-changing operations are captured by
*both* a method and a signal, conveying the same information by
parameters -- plus a generic user_data pointer for signals.

A good example is the atk_text_set_caret_offset method versus the
text-caret-moved signal in AtkText: see
https://developer.gnome.org/atk/unstable/AtkText.html .  The definition
of atk_text_set_caret_offset in ATK (atk/atktext.c) simply calles the
appropriate interface function pointer when non-NULL, and does nothing
otherwise.  An implementation of such a function is
gtk_text_view_accessible_set_caret_offset (GTK+,
gtk/a11y/gtktextviewaccessible.c), which explicitly emits text-caret-moved.

I didn't find an explicit explanation about when to use methods rather
than signals.  I understand that signals can be added to listeners and
handled in "user" code, but the difference between an ATK object
implementation and its usage is quite blurry in what I am doing, and
likely just a matter of convention.

What I can see from the code above and by experimenting is that emitting
a signal does *not* cause the corresponding method to be called, but the
vice-versa is true for ATK objects as implemented in GTK+; I suppose I
should do the same for my own ATK objects.  Thanks to the bridge the
AT-SPI registry in the end receives change notifications from signals,
but not (automatically) by methods.  So I suspsect that, when changing a
widget state in "user" code, I am supposed to always just call set_
methods, and not emit signals; when implemented correctly those methods
would emit signals as needed.

This I deduced from the source code.  Would you please confirm that my
understanding is correct?

Thanks in advance,

-- 
Luca Saiu
HYPRA -- Progressons ensemble : http://hypra.fr