GNOME Bugzilla – Bug 649307
plug/socket documentation is unclear
Last modified: 2011-05-13 16:41:48 UTC
Created attachment 187139 [details] [review] Patch. I think this should clarify things somewhat. Reviews welcome. After talking Mario Sanchez through what is needed to use AtkPlug and AtkSocket, I am realizing that the documentation is unclear; it is not obvious from the documentation (or the ATK code) which functionality is to be implemented by atk-bridge and what needs to be implemented by the application.
I think this patch to the documentation is a great improvement since it perfectly clarifies the most obscure part (IMHO) of the knowledge required to properly use these APIs. At least for me, it was not clear at the beginning that I should extend the AtkPlug and AtkSocket classes *without* providing the implementation for the atk_socket_embed() and atk_plug_get_id() functions, just because the at-spi2 component would step in later on and provide the implementations for those two specific functions. Now that Mike documented that with this patch, it is pretty clear, so I'd say it would be good to commit it as it is now. Added myself to CC
Comment on attachment 187139 [details] [review] Patch. I think this should clarify things somewhat. Reviews welcome. >diff --git a/atk/atkplug.c b/atk/atkplug.c >index 242e947..9445df3 100644 >--- a/atk/atkplug.c >+++ b/atk/atkplug.c >@@ -63,6 +63,11 @@ atk_plug_new (void) > * > * Gets the unique ID of an #AtkPlug object, which can be used to embed inside > * of an #AtkSocket using atk_socket_embed(). >+ * Internally, this calls a class function that should be registered by the >+ * IPC layer (eg, at-spi2-atk). The implementor of an AtkSocket object >+ * should call this function (after atk-bridge is loaded) and pass the value >+ * to the process implementing the AtkPlug into which the AtkSocket is >+ * embedded. > * > * Returns: the unique ID for the plug > * >diff --git a/atk/atksocket.c b/atk/atksocket.c >index 7886e07..ff31d5d 100644 >--- a/atk/atksocket.c >+++ b/atk/atksocket.c >@@ -64,6 +64,11 @@ atk_socket_new (void) > * > * Embeds the children of an #AtkPlug as the children of the #AtkSocket. The > * plug may be in the same process or in a different process. >+ * THe class item used by this function should be filled in by the IPC layer >+ * (ie, at-spi2-atk). The implementor of the AtkSocket should call this >+ * function and pass the id for the plug as returned by atk_plug_get_id. >+ * It is the responsibility of the application to pass the plug id on to >+ * the process implementing the AtkSocket as needed. > * > * Since: 1.30 > **/
Committed after discussion at the ATK hackfest.