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   LAST_SIGNAL
  43 };
  44
  45 static void atk_document_base_init (AtkDocumentIface *class);
  46
  47 static guint atk_document_signals[LAST_SIGNAL] = {0};
  48
  49 GType
  50 atk_document_get_type (void)
  51 {
  52   static GType type = 0;
  53
  54   if (!type) {
  55     static const GTypeInfo tinfo =
  56     {
  57       sizeof (AtkDocumentIface),
  58       (GBaseInitFunc) atk_document_base_init,
  59       (GBaseFinalizeFunc) NULL,
  60
  61     };
  62
  63     type = g_type_register_static (G_TYPE_INTERFACE, "AtkDocument", &tinfo, 0);
  64   }
  65
  66   return type;
  67 }
  68
  69 static void
  70 atk_document_base_init (AtkDocumentIface *class)
  71 {
  72   static gboolean initialized = FALSE;
  73   if (!initialized)
  74     {
  75       /**
  76        * AtkDocument::load-complete:
  77        * @atkdocument: the object which received the signal.
  78        *
  79        * The 'load-complete' signal is emitted when a pending load of
  80        * a static document has completed.  This signal is to be
  81        * expected by ATK clients if and when AtkDocument implementors
  82        * expose ATK_STATE_BUSY.  If the state of an AtkObject which
  83        * implements AtkDocument does not include ATK_STATE_BUSY, it
  84        * should be safe for clients to assume that the AtkDocument's
  85        * static contents are fully loaded into the container.
  86        * (Dynamic document contents should be exposed via other
  87        * signals.)
  88        */
  89       atk_document_signals[LOAD_COMPLETE] =
  90         g_signal_new ("load_complete",
  91                       ATK_TYPE_DOCUMENT,
  92                       G_SIGNAL_RUN_LAST,
  93                       0,
  94                       (GSignalAccumulator) NULL, NULL,
  95                       g_cclosure_marshal_VOID__VOID,
  96                       G_TYPE_NONE, 0);
  97       /**
  98        * AtkDocument::reload:
  99        * @atkdocument: the object which received the signal.
 100        *
 101        * The 'reload' signal is emitted when the contents of a
 102        * document is refreshed from its source.  Once 'reload' has
 103        * been emitted, a matching 'load-complete' or 'load-stopped'
 104        * signal should follow, which clients may await before
 105        * interrogating ATK for the latest document content.
 106        */
 107       atk_document_signals[RELOAD] =
 108         g_signal_new ("reload",
 109                       ATK_TYPE_DOCUMENT,
 110                       G_SIGNAL_RUN_LAST,
 111                       0,
 112                       (GSignalAccumulator) NULL, NULL,
 113                       g_cclosure_marshal_VOID__VOID,
 114                       G_TYPE_NONE, 0);
 115
 116       /**
 117        * AtkDocument::load-stopped:
 118        * @atkdocument: the object which received the signal.
 119        *
 120        * The 'load-stopped' signal is emitted when a pending load of
 121        * document contents is cancelled, paused, or otherwise
 122        * interrupted by the user or application logic.  It should not
 123        * however be emitted while waiting for a resource (for instance
 124        * while blocking on a file or network read) unless a
 125        * user-significant timeout has occurred.
 126        */
 127       atk_document_signals[LOAD_STOPPED] =
 128         g_signal_new ("load_stopped",
 129                       ATK_TYPE_DOCUMENT,
 130                       G_SIGNAL_RUN_LAST,
 131                       0,
 132                       (GSignalAccumulator) NULL, NULL,
 133                       g_cclosure_marshal_VOID__VOID,
 134                       G_TYPE_NONE, 0);
 135
 136       initialized = TRUE;
 137     }
 138 }
 139
 140 /**
 141  * atk_document_get_document_type:
 142  * @document: a #GObject instance that implements AtkDocumentIface
 143  *
 144  * Gets a string indicating the document type.
 145  *
 146  * Returns: a string indicating the document type
 147  **/
 148 const gchar*
 149 atk_document_get_document_type (AtkDocument *document)
 150 {
 151   AtkDocumentIface *iface;
 152
 153   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 154
 155   iface = ATK_DOCUMENT_GET_IFACE (document);
 156
 157   if (iface->get_document_type)
 158     {
 159       return (iface->get_document_type) (document);
 160     }
 161   else
 162     {
 163       return NULL;
 164     }
 165 }
 166
 167 /**
 168  * atk_document_get_document:
 169  * @document: a #GObject instance that implements AtkDocumentIface
 170  *
 171  * Gets a %gpointer that points to an instance of the DOM.  It is
 172  * up to the caller to check atk_document_get_type to determine
 173  * how to cast this pointer.
 174  *
 175  * Returns: (transfer none): a %gpointer that points to an instance of the DOM.
 176  **/
 177 gpointer
 178 atk_document_get_document (AtkDocument *document)
 179 {
 180   AtkDocumentIface *iface;
 181
 182   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 183
 184   iface = ATK_DOCUMENT_GET_IFACE (document);
 185
 186   if (iface->get_document)
 187     {
 188       return (iface->get_document) (document);
 189     }
 190   else
 191     {
 192       return NULL;
 193     }
 194 }
 195
 196 /**
 197  * atk_document_get_locale:
 198  * @document: a #GObject instance that implements AtkDocumentIface
 199  *
 200  * Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale
 201  *          of the content of this document instance.  Individual
 202  *          text substrings or images within this document may have
 203  *          a different locale, see atk_text_get_attributes and
 204  *          atk_image_get_image_locale.
 205  *
 206  * Deprecated: This method is deprecated since ATK version
 207  * 2.7.90. Please use atk_object_get_object_locale() instead.
 208  *
 209  * Returns: a UTF-8 string indicating the POSIX-style LC_MESSAGES
 210  *          locale of the document content as a whole, or NULL if
 211  *          the document content does not specify a locale.
 212  * Virtual: get_document_locale
 213  **/
 214 const gchar *
 215 atk_document_get_locale (AtkDocument *document)
 216 {
 217   AtkDocumentIface *iface;
 218
 219   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 220
 221   iface = ATK_DOCUMENT_GET_IFACE (document);
 222
 223   if (iface->get_document_locale)
 224     {
 225       return (iface->get_document_locale) (document);
 226     }
 227   else
 228     {
 229       return NULL;
 230     }
 231 }
 232
 233
 234 /**
 235  * atk_document_get_attributes:
 236  * @document: a #GObject instance that implements AtkDocumentIface
 237  *
 238  * Gets an AtkAttributeSet which describes document-wide
 239  *          attributes as name-value pairs.
 240  *
 241  * Since: 1.12
 242  *
 243  * Returns: (transfer none): An AtkAttributeSet containing the explicitly
 244  *          set name-value-pair attributes associated with this document
 245  *          as a whole.
 246  * Virtual: get_document_attributes
 247  **/
 248 AtkAttributeSet *
 249 atk_document_get_attributes (AtkDocument *document)
 250 {
 251   AtkDocumentIface *iface;
 252
 253   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 254
 255   iface = ATK_DOCUMENT_GET_IFACE (document);
 256
 257   if (iface->get_document_attributes)
 258     {
 259       return (iface->get_document_attributes) (document);
 260     }
 261   else
 262     {
 263       return NULL;
 264     }
 265 }
 266
 267 /**
 268  * atk_document_get_attribute_value:
 269  * @document: a #GObject instance that implements AtkDocumentIface
 270  * @attribute_name: a character string representing the name of the attribute
 271  *            whose value is being queried.
 272  *
 273  * Since: 1.12
 274  *
 275  * Returns: a string value associated with the named attribute for this
 276  *    document, or NULL if a value for #attribute_name has not been specified
 277  *    for this document.
 278  * Virtual: get_document_attribute_value
 279  */
 280 const gchar *
 281 atk_document_get_attribute_value (AtkDocument *document,
 282                                   const gchar *attribute_name)
 283 {
 284   AtkDocumentIface *iface;
 285
 286   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 287
 288   iface = ATK_DOCUMENT_GET_IFACE (document);
 289
 290   if (iface->get_document_attribute_value)
 291     {
 292       return (iface->get_document_attribute_value) (document, attribute_name);
 293     }
 294   else
 295     {
 296       return NULL;
 297     }
 298 }
 299
 300 /**
 301  * atk_document_set_attribute_value:
 302  * @document: a #GObject instance that implements AtkDocumentIface
 303  * @attribute_name: a character string representing the name of the attribute
 304  *            whose value is being set.
 305  * @attribute_value: a string value to be associated with #attribute_name.
 306  *
 307  * Since: 1.12
 308  *
 309  * Returns: TRUE if #value is successfully associated with #attribute_name
 310  *          for this document, FALSE otherwise (e.g. if the document does not
 311  *          allow the attribute to be modified).
 312  * Virtual: set_document_attribute
 313  */
 314 gboolean
 315 atk_document_set_attribute_value (AtkDocument *document,
 316                                   const gchar *attribute_name,
 317                                   const gchar *attribute_value)
 318 {
 319   AtkDocumentIface *iface;
 320
 321   g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
 322
 323   iface = ATK_DOCUMENT_GET_IFACE (document);
 324
 325   if (iface->set_document_attribute)
 326     {
 327       return (iface->set_document_attribute) (document, attribute_name, attribute_value);
 328     }
 329   else
 330     {
 331       return FALSE;
 332     }
 333 }