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