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