atk/atkdocument.c

   1 /* ATK -  Accessibility Toolkit
   2  * Copyright 2001 Sun Microsystems Inc.
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 #include "atkdocument.h"
  21
  22 /**
  23  * SECTION:atkdocument
  24  * @Short_description: The ATK interface which represents the toplevel
  25  *  container for document content.
  26  * @Title:AtkDocument
  27  *
  28  * The AtkDocument interface should be supported by any object whose
  29  * content is a representation or view of a document.  The AtkDocument
  30  * interface should appear on the toplevel container for the document
  31  * content; however AtkDocument instances may be nested (i.e. an
  32  * AtkDocument may be a descendant of another AtkDocument) in those
  33  * cases where one document contains "embedded content" which can
  34  * reasonably be considered a document in its own right.
  35  *
  36  */
  37
  38 enum {
  39   LOAD_COMPLETE,
  40   RELOAD,
  41   LOAD_STOPPED,
  42   PAGE_CHANGED,
  43   LAST_SIGNAL
  44 };
  45
  46 static void atk_document_base_init (AtkDocumentIface *class);
  47
  48 static guint atk_document_signals[LAST_SIGNAL] = {0};
  49
  50 GType
  51 atk_document_get_type (void)
  52 {
  53   static GType type = 0;
  54
  55   if (!type) {
  56     static const GTypeInfo tinfo =
  57     {
  58       sizeof (AtkDocumentIface),
  59       (GBaseInitFunc) atk_document_base_init,
  60       (GBaseFinalizeFunc) NULL,
  61
  62     };
  63
  64     type = g_type_register_static (G_TYPE_INTERFACE, "AtkDocument", &tinfo, 0);
  65   }
  66
  67   return type;
  68 }
  69
  70 static void
  71 atk_document_base_init (AtkDocumentIface *class)
  72 {
  73   static gboolean initialized = FALSE;
  74   if (!initialized)
  75     {
  76       /**
  77        * AtkDocument::load-complete:
  78        * @atkdocument: the object which received the signal.
  79        *
  80        * The 'load-complete' signal is emitted when a pending load of
  81        * a static document has completed.  This signal is to be
  82        * expected by ATK clients if and when AtkDocument implementors
  83        * expose ATK_STATE_BUSY.  If the state of an AtkObject which
  84        * implements AtkDocument does not include ATK_STATE_BUSY, it
  85        * should be safe for clients to assume that the AtkDocument's
  86        * static contents are fully loaded into the container.
  87        * (Dynamic document contents should be exposed via other
  88        * signals.)
  89        */
  90       atk_document_signals[LOAD_COMPLETE] =
  91         g_signal_new ("load_complete",
  92                       ATK_TYPE_DOCUMENT,
  93                       G_SIGNAL_RUN_LAST,
  94                       0,
  95                       (GSignalAccumulator) NULL, NULL,
  96                       g_cclosure_marshal_VOID__VOID,
  97                       G_TYPE_NONE, 0);
  98       /**
  99        * AtkDocument::reload:
 100        * @atkdocument: the object which received the signal.
 101        *
 102        * The 'reload' signal is emitted when the contents of a
 103        * document is refreshed from its source.  Once 'reload' has
 104        * been emitted, a matching 'load-complete' or 'load-stopped'
 105        * signal should follow, which clients may await before
 106        * interrogating ATK for the latest document content.
 107        */
 108       atk_document_signals[RELOAD] =
 109         g_signal_new ("reload",
 110                       ATK_TYPE_DOCUMENT,
 111                       G_SIGNAL_RUN_LAST,
 112                       0,
 113                       (GSignalAccumulator) NULL, NULL,
 114                       g_cclosure_marshal_VOID__VOID,
 115                       G_TYPE_NONE, 0);
 116
 117       /**
 118        * AtkDocument::load-stopped:
 119        * @atkdocument: the object which received the signal.
 120        *
 121        * The 'load-stopped' signal is emitted when a pending load of
 122        * document contents is cancelled, paused, or otherwise
 123        * interrupted by the user or application logic.  It should not
 124        * however be emitted while waiting for a resource (for instance
 125        * while blocking on a file or network read) unless a
 126        * user-significant timeout has occurred.
 127        */
 128       atk_document_signals[LOAD_STOPPED] =
 129         g_signal_new ("load_stopped",
 130                       ATK_TYPE_DOCUMENT,
 131                       G_SIGNAL_RUN_LAST,
 132                       0,
 133                       (GSignalAccumulator) NULL, NULL,
 134                       g_cclosure_marshal_VOID__VOID,
 135                       G_TYPE_NONE, 0);
 136
 137       /**
 138        * AtkDocument::page-changed:
 139        * @atkdocument: the object on which the signal was emitted
 140        * @page_number: the new page number. If this value is unknown
 141        * or not applicable, -1 should be provided.
 142        *
 143        * The 'page-changed' signal is emitted when the current page of
 144        * a document changes, e.g. pressing page up/down in a document
 145        * viewer.
 146        *
 147        * Since: 2.12
 148        */
 149       atk_document_signals[PAGE_CHANGED] =
 150         g_signal_new ("page_changed",
 151                       ATK_TYPE_DOCUMENT,
 152                       G_SIGNAL_RUN_LAST,
 153                       0,
 154                       (GSignalAccumulator) NULL, NULL,
 155                       g_cclosure_marshal_VOID__INT,
 156                       G_TYPE_NONE, 1, G_TYPE_INT);
 157
 158       initialized = TRUE;
 159     }
 160 }
 161
 162 /**
 163  * atk_document_get_document_type:
 164  * @document: a #GObject instance that implements AtkDocumentIface
 165  *
 166  * Gets a string indicating the document type.
 167  *
 168  * Deprecated: Since 2.12. Please use atk_document_get_attributes() to
 169  * ask for the document type if it applies.
 170  *
 171  * Returns: a string indicating the document type
 172  **/
 173 const gchar*
 174 atk_document_get_document_type (AtkDocument *document)
 175 {
 176   AtkDocumentIface *iface;
 177
 178   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 179
 180   iface = ATK_DOCUMENT_GET_IFACE (document);
 181
 182   if (iface->get_document_type)
 183     {
 184       return (iface->get_document_type) (document);
 185     }
 186   else
 187     {
 188       return NULL;
 189     }
 190 }
 191
 192 /**
 193  * atk_document_get_document:
 194  * @document: a #GObject instance that implements AtkDocumentIface
 195  *
 196  * Gets a %gpointer that points to an instance of the DOM.  It is
 197  * up to the caller to check atk_document_get_type to determine
 198  * how to cast this pointer.
 199  *
 200  * Deprecated: Since 2.12. @document is already a representation of
 201  * the document. Use it directly, or one of his children, as an
 202  * instance of the DOM.
 203  *
 204  * Returns: (transfer none): a %gpointer that points to an instance of the DOM.
 205  **/
 206 gpointer
 207 atk_document_get_document (AtkDocument *document)
 208 {
 209   AtkDocumentIface *iface;
 210
 211   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 212
 213   iface = ATK_DOCUMENT_GET_IFACE (document);
 214
 215   if (iface->get_document)
 216     {
 217       return (iface->get_document) (document);
 218     }
 219   else
 220     {
 221       return NULL;
 222     }
 223 }
 224
 225 /**
 226  * atk_document_get_locale:
 227  * @document: a #GObject instance that implements AtkDocumentIface
 228  *
 229  * Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale
 230  *          of the content of this document instance.  Individual
 231  *          text substrings or images within this document may have
 232  *          a different locale, see atk_text_get_attributes and
 233  *          atk_image_get_image_locale.
 234  *
 235  * Deprecated: This method is deprecated since ATK version
 236  * 2.7.90. Please use atk_object_get_object_locale() instead.
 237  *
 238  * Returns: a UTF-8 string indicating the POSIX-style LC_MESSAGES
 239  *          locale of the document content as a whole, or NULL if
 240  *          the document content does not specify a locale.
 241  * Virtual: get_document_locale
 242  **/
 243 const gchar *
 244 atk_document_get_locale (AtkDocument *document)
 245 {
 246   AtkDocumentIface *iface;
 247
 248   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 249
 250   iface = ATK_DOCUMENT_GET_IFACE (document);
 251
 252   if (iface->get_document_locale)
 253     {
 254       return (iface->get_document_locale) (document);
 255     }
 256   else
 257     {
 258       return NULL;
 259     }
 260 }
 261
 262
 263 /**
 264  * atk_document_get_attributes:
 265  * @document: a #GObject instance that implements AtkDocumentIface
 266  *
 267  * Gets an AtkAttributeSet which describes document-wide
 268  *          attributes as name-value pairs.
 269  *
 270  * Since: 1.12
 271  *
 272  * Returns: (transfer none): An AtkAttributeSet containing the explicitly
 273  *          set name-value-pair attributes associated with this document
 274  *          as a whole.
 275  * Virtual: get_document_attributes
 276  **/
 277 AtkAttributeSet *
 278 atk_document_get_attributes (AtkDocument *document)
 279 {
 280   AtkDocumentIface *iface;
 281
 282   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 283
 284   iface = ATK_DOCUMENT_GET_IFACE (document);
 285
 286   if (iface->get_document_attributes)
 287     {
 288       return (iface->get_document_attributes) (document);
 289     }
 290   else
 291     {
 292       return NULL;
 293     }
 294 }
 295
 296 /**
 297  * atk_document_get_attribute_value:
 298  * @document: a #GObject instance that implements AtkDocumentIface
 299  * @attribute_name: a character string representing the name of the attribute
 300  *            whose value is being queried.
 301  *
 302  * Since: 1.12
 303  *
 304  * Returns: a string value associated with the named attribute for this
 305  *    document, or NULL if a value for #attribute_name has not been specified
 306  *    for this document.
 307  * Virtual: get_document_attribute_value
 308  */
 309 const gchar *
 310 atk_document_get_attribute_value (AtkDocument *document,
 311                                   const gchar *attribute_name)
 312 {
 313   AtkDocumentIface *iface;
 314
 315   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 316
 317   iface = ATK_DOCUMENT_GET_IFACE (document);
 318
 319   if (iface->get_document_attribute_value)
 320     {
 321       return (iface->get_document_attribute_value) (document, attribute_name);
 322     }
 323   else
 324     {
 325       return NULL;
 326     }
 327 }
 328
 329 /**
 330  * atk_document_set_attribute_value:
 331  * @document: a #GObject instance that implements AtkDocumentIface
 332  * @attribute_name: a character string representing the name of the attribute
 333  *            whose value is being set.
 334  * @attribute_value: a string value to be associated with #attribute_name.
 335  *
 336  * Since: 1.12
 337  *
 338  * Returns: TRUE if #value is successfully associated with #attribute_name
 339  *          for this document, FALSE otherwise (e.g. if the document does not
 340  *          allow the attribute to be modified).
 341  * Virtual: set_document_attribute
 342  */
 343 gboolean
 344 atk_document_set_attribute_value (AtkDocument *document,
 345                                   const gchar *attribute_name,
 346                                   const gchar *attribute_value)
 347 {
 348   AtkDocumentIface *iface;
 349
 350   g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
 351
 352   iface = ATK_DOCUMENT_GET_IFACE (document);
 353
 354   if (iface->set_document_attribute)
 355     {
 356       return (iface->set_document_attribute) (document, attribute_name, attribute_value);
 357     }
 358   else
 359     {
 360       return FALSE;
 361     }
 362 }
 363
 364 /**
 365  * atk_document_get_current_page_number:
 366  * @document: the #AtkDocument
 367  *
 368  * Since: 2.12
 369  *
 370  * Returns: current page number inside @document. -1 if not
 371  * implemented, not know by the implementor or irrelevant.
 372  */
 373 gint
 374 atk_document_get_current_page_number (AtkDocument *document)
 375 {
 376   AtkDocumentIface *iface;
 377
 378   g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
 379
 380   iface = ATK_DOCUMENT_GET_IFACE (document);
 381
 382   if (iface->get_current_page_number)
 383     {
 384       return (iface->get_current_page_number) (document);
 385     }
 386   else
 387     {
 388       return -1;
 389     }
 390 }
 391
 392 /**
 393  * atk_document_get_page_count:
 394  * @document: the #AtkDocument
 395  *
 396  * Since: 2.12
 397  *
 398  * Returns: total page count of @document. -1 if not implemented, not
 399  * know by the implementor or irrelevant.
 400  */
 401 gint
 402 atk_document_get_page_count (AtkDocument *document)
 403 {
 404   AtkDocumentIface *iface;
 405
 406   g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
 407
 408   iface = ATK_DOCUMENT_GET_IFACE (document);
 409
 410   if (iface->get_page_count)
 411     {
 412       return (iface->get_page_count) (document);
 413     }
 414   else
 415     {
 416       return -1;
 417     }
 418 }