doc: improve ATK_TEXT_ATTR documentation

[platform/upstream/atk.git] / atk / atkdocument.c

diff --git a/atk/atkdocument.c b/atk/atkdocument.c
index bf5cc9a..f1515bb 100755 (executable)
--- a/atk/atkdocument.c
+++ b/atk/atkdocument.c
@@ -39,6 +39,7 @@ enum {
   LOAD_COMPLETE,
   RELOAD,
   LOAD_STOPPED,
+  PAGE_CHANGED,
   LAST_SIGNAL
 };
 
@@ -133,6 +134,27 @@ atk_document_base_init (AtkDocumentIface *class)
                       g_cclosure_marshal_VOID__VOID,
                       G_TYPE_NONE, 0);
 
+      /**
+       * AtkDocument::page-changed:
+       * @atkdocument: the object on which the signal was emitted
+       * @page_number: the new page number. If this value is unknown
+       * or not applicable, -1 should be provided.
+       *
+       * The 'page-changed' signal is emitted when the current page of
+       * a document changes, e.g. pressing page up/down in a document
+       * viewer.
+       *
+       * Since: 2.12
+       */
+      atk_document_signals[PAGE_CHANGED] =
+        g_signal_new ("page_changed",
+                      ATK_TYPE_DOCUMENT,
+                      G_SIGNAL_RUN_LAST,
+                      0,
+                      (GSignalAccumulator) NULL, NULL,
+                      g_cclosure_marshal_VOID__INT,
+                      G_TYPE_NONE, 1, G_TYPE_INT);
+
       initialized = TRUE;
     }
 }
@@ -143,6 +165,9 @@ atk_document_base_init (AtkDocumentIface *class)
  *
  * Gets a string indicating the document type.
  *
+ * Deprecated: Since 2.12. Please use atk_document_get_attributes() to
+ * ask for the document type if it applies.
+ *
  * Returns: a string indicating the document type
  **/
 const gchar*
@@ -172,6 +197,10 @@ atk_document_get_document_type (AtkDocument *document)
  * up to the caller to check atk_document_get_type to determine
  * how to cast this pointer.
  *
+ * Deprecated: Since 2.12. @document is already a representation of
+ * the document. Use it directly, or one of his children, as an
+ * instance of the DOM.
+ *
  * Returns: (transfer none): a %gpointer that points to an instance of the DOM.
  **/
 gpointer