Add "load-stopped", "load_complete", "loading" signals to AtkDocument

interface.  Based on patch from Neo Liu <nian.liu@sun.com>.

2 files changed, 49 insertions, 4 deletions

diff --git a/docs/tmpl/atk-unused.sgml b/docs/tmpl/atk-unused.sgml
index d81c262..9efe0cf 100644
--- a/docs/tmpl/atk-unused.sgml
+++ b/docs/tmpl/atk-unused.sgml
@@ -18,3 +18,11 @@
 atk
 
 
+<!-- ##### SIGNAL AtkDocument:: ##### -->
+<para>
+The 'reload' signal is emitted when 
+</para>
+
+@atkdocument: the object which received the signal.
+@arg1: 
+
diff --git a/docs/tmpl/atkdocument.sgml b/docs/tmpl/atkdocument.sgml
index 89e66d8..3283f24 100644
--- a/docs/tmpl/atkdocument.sgml
+++ b/docs/tmpl/atkdocument.sgml
@@ -2,13 +2,16 @@
 AtkDocument
 
 <!-- ##### SECTION Short_Description ##### -->
-The ATK interface which allows access to a DOM associated with on object.
+The ATK interface which represents the toplevel container for document content.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The AtkDocument interface should be supported by any object that has an
-associated document object model (DOM). This interface provides the
-standard mechanism allowing an assistive technology access to the DOM.
+The AtkDocument interface should be supported by any object whose content is a 
+representation or view of a document.  The AtkDocument interface should appear
+on the toplevel container for the document content; however AtkDocument 
+instances may be nested (i.e. an AtkDocument may be a descendant of another
+AtkDocument) in those cases where one document contains "embedded content" 
+which can reasonably be considered a document in its own right.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -27,6 +30,40 @@ The AtkDocument structure does not contain any fields.
 </para>
 
 
+<!-- ##### SIGNAL AtkDocument::load-complete ##### -->
+<para>
+The 'load-complete' signal is emitted when a pending load of a static
+document has completed.  This signal is to be expected by ATK clients 
+if and when AtkDocument implementors expose ATK_STATE_BUSY.  If the state
+of an AtkObject which implements AtkDocument does not include ATK_STATE_BUSY,
+it should be safe for clients to assume that the AtkDocument's static contents
+are fully loaded into the container.  (Dynamic document contents should
+be exposed via other signals.)
+</para>
+
+@atkdocument: the object which received the signal.
+
+<!-- ##### SIGNAL AtkDocument::load-stopped ##### -->
+<para>
+The 'load-stopped' signal is emitted when a pending load of document contents
+is cancelled, paused, or otherwise interrupted by the user or application 
+logic.  It should not however be
+emitted while waiting for a resource (for instance while blocking on a file or 
+network read) unless a user-significant timeout has occurred.
+</para>
+
+@atkdocument: the object which received the signal.
+
+<!-- ##### SIGNAL AtkDocument::reload ##### -->
+<para>
+The 'reload' signal is emitted when the contents of a document is refreshed
+from its source.  Once 'reload' has been emitted, a matching 'load-complete' 
+or 'load-stopped' signal should follow, which clients may await before 
+interrogating ATK for the latest document content.
+</para>
+
+@atkdocument: the object which received the signal.
+
 <!-- ##### FUNCTION atk_document_get_document_type ##### -->
 <para>