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:
 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:
 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 his 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:
 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: This method is deprecated since ATK version
 238  * 2.7.90. Please use atk_object_get_object_locale() instead.
 239  *
 240  * Returns: a UTF-8 string indicating the POSIX-style LC_MESSAGES
 241  *          locale of the document content as a whole, or NULL if
 242  *          the document content does not specify a locale.
 243  **/
 244 const gchar *
 245 atk_document_get_locale (AtkDocument *document)
 246 {
 247   AtkDocumentIface *iface;
 248
 249   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 250
 251   iface = ATK_DOCUMENT_GET_IFACE (document);
 252
 253   if (iface->get_document_locale)
 254     {
 255       return (iface->get_document_locale) (document);
 256     }
 257   else
 258     {
 259       return NULL;
 260     }
 261 }
 262
 263
 264 /**
 265  * atk_document_get_attributes:
 266  * @document: a #GObject instance that implements AtkDocumentIface
 267  *
 268  * Gets an AtkAttributeSet which describes document-wide
 269  *          attributes as name-value pairs.
 270  *
 271  * Since: 1.12
 272  *
 273  * Returns: (transfer none): An AtkAttributeSet containing the explicitly
 274  *          set name-value-pair attributes associated with this document
 275  *          as a whole.
 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: (nullable): a string value associated with the named
 305  *    attribute for this document, or NULL if a value for
 306  *    #attribute_name has not been specified for this document.
 307  */
 308 const gchar *
 309 atk_document_get_attribute_value (AtkDocument *document,
 310                                   const gchar *attribute_name)
 311 {
 312   AtkDocumentIface *iface;
 313
 314   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 315
 316   iface = ATK_DOCUMENT_GET_IFACE (document);
 317
 318   if (iface->get_document_attribute_value)
 319     {
 320       return (iface->get_document_attribute_value) (document, attribute_name);
 321     }
 322   else
 323     {
 324       return NULL;
 325     }
 326 }
 327
 328 /**
 329  * atk_document_set_attribute_value:
 330  * @document: a #GObject instance that implements AtkDocumentIface
 331  * @attribute_name: a character string representing the name of the attribute
 332  *            whose value is being set.
 333  * @attribute_value: a string value to be associated with #attribute_name.
 334  *
 335  * Since: 1.12
 336  *
 337  * Returns: TRUE if #value is successfully associated with #attribute_name
 338  *          for this document, FALSE otherwise (e.g. if the document does not
 339  *          allow the attribute to be modified).
 340  */
 341 gboolean
 342 atk_document_set_attribute_value (AtkDocument *document,
 343                                   const gchar *attribute_name,
 344                                   const gchar *attribute_value)
 345 {
 346   AtkDocumentIface *iface;
 347
 348   g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
 349
 350   iface = ATK_DOCUMENT_GET_IFACE (document);
 351
 352   if (iface->set_document_attribute)
 353     {
 354       return (iface->set_document_attribute) (document, attribute_name, attribute_value);
 355     }
 356   else
 357     {
 358       return FALSE;
 359     }
 360 }
 361
 362 /**
 363  * atk_document_get_current_page_number:
 364  * @document: the #AtkDocument
 365  *
 366  * Since: 2.12
 367  *
 368  * Returns: current page number inside @document. -1 if not
 369  * implemented, not know by the implementor or irrelevant.
 370  */
 371 gint
 372 atk_document_get_current_page_number (AtkDocument *document)
 373 {
 374   AtkDocumentIface *iface;
 375
 376   g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
 377
 378   iface = ATK_DOCUMENT_GET_IFACE (document);
 379
 380   if (iface->get_current_page_number)
 381     {
 382       return (iface->get_current_page_number) (document);
 383     }
 384   else
 385     {
 386       return -1;
 387     }
 388 }
 389
 390 /**
 391  * atk_document_get_page_count:
 392  * @document: the #AtkDocument
 393  *
 394  * Since: 2.12
 395  *
 396  * Returns: total page count of @document. -1 if not implemented, not
 397  * know by the implementor or irrelevant.
 398  */
 399 gint
 400 atk_document_get_page_count (AtkDocument *document)
 401 {
 402   AtkDocumentIface *iface;
 403
 404   g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
 405
 406   iface = ATK_DOCUMENT_GET_IFACE (document);
 407
 408   if (iface->get_page_count)
 409     {
 410       return (iface->get_page_count) (document);
 411     }
 412   else
 413     {
 414       return -1;
 415     }
 416 }