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  * Returns: a string indicating the document type
 169  **/
 170 const gchar*
 171 atk_document_get_document_type (AtkDocument *document)
 172 {
 173   AtkDocumentIface *iface;
 174
 175   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 176
 177   iface = ATK_DOCUMENT_GET_IFACE (document);
 178
 179   if (iface->get_document_type)
 180     {
 181       return (iface->get_document_type) (document);
 182     }
 183   else
 184     {
 185       return NULL;
 186     }
 187 }
 188
 189 /**
 190  * atk_document_get_document:
 191  * @document: a #GObject instance that implements AtkDocumentIface
 192  *
 193  * Gets a %gpointer that points to an instance of the DOM.  It is
 194  * up to the caller to check atk_document_get_type to determine
 195  * how to cast this pointer.
 196  *
 197  * Returns: (transfer none): a %gpointer that points to an instance of the DOM.
 198  **/
 199 gpointer
 200 atk_document_get_document (AtkDocument *document)
 201 {
 202   AtkDocumentIface *iface;
 203
 204   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 205
 206   iface = ATK_DOCUMENT_GET_IFACE (document);
 207
 208   if (iface->get_document)
 209     {
 210       return (iface->get_document) (document);
 211     }
 212   else
 213     {
 214       return NULL;
 215     }
 216 }
 217
 218 /**
 219  * atk_document_get_locale:
 220  * @document: a #GObject instance that implements AtkDocumentIface
 221  *
 222  * Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale
 223  *          of the content of this document instance.  Individual
 224  *          text substrings or images within this document may have
 225  *          a different locale, see atk_text_get_attributes and
 226  *          atk_image_get_image_locale.
 227  *
 228  * Deprecated: This method is deprecated since ATK version
 229  * 2.7.90. Please use atk_object_get_object_locale() instead.
 230  *
 231  * Returns: a UTF-8 string indicating the POSIX-style LC_MESSAGES
 232  *          locale of the document content as a whole, or NULL if
 233  *          the document content does not specify a locale.
 234  * Virtual: get_document_locale
 235  **/
 236 const gchar *
 237 atk_document_get_locale (AtkDocument *document)
 238 {
 239   AtkDocumentIface *iface;
 240
 241   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 242
 243   iface = ATK_DOCUMENT_GET_IFACE (document);
 244
 245   if (iface->get_document_locale)
 246     {
 247       return (iface->get_document_locale) (document);
 248     }
 249   else
 250     {
 251       return NULL;
 252     }
 253 }
 254
 255
 256 /**
 257  * atk_document_get_attributes:
 258  * @document: a #GObject instance that implements AtkDocumentIface
 259  *
 260  * Gets an AtkAttributeSet which describes document-wide
 261  *          attributes as name-value pairs.
 262  *
 263  * Since: 1.12
 264  *
 265  * Returns: (transfer none): An AtkAttributeSet containing the explicitly
 266  *          set name-value-pair attributes associated with this document
 267  *          as a whole.
 268  * Virtual: get_document_attributes
 269  **/
 270 AtkAttributeSet *
 271 atk_document_get_attributes (AtkDocument *document)
 272 {
 273   AtkDocumentIface *iface;
 274
 275   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 276
 277   iface = ATK_DOCUMENT_GET_IFACE (document);
 278
 279   if (iface->get_document_attributes)
 280     {
 281       return (iface->get_document_attributes) (document);
 282     }
 283   else
 284     {
 285       return NULL;
 286     }
 287 }
 288
 289 /**
 290  * atk_document_get_attribute_value:
 291  * @document: a #GObject instance that implements AtkDocumentIface
 292  * @attribute_name: a character string representing the name of the attribute
 293  *            whose value is being queried.
 294  *
 295  * Since: 1.12
 296  *
 297  * Returns: a string value associated with the named attribute for this
 298  *    document, or NULL if a value for #attribute_name has not been specified
 299  *    for this document.
 300  * Virtual: get_document_attribute_value
 301  */
 302 const gchar *
 303 atk_document_get_attribute_value (AtkDocument *document,
 304                                   const gchar *attribute_name)
 305 {
 306   AtkDocumentIface *iface;
 307
 308   g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
 309
 310   iface = ATK_DOCUMENT_GET_IFACE (document);
 311
 312   if (iface->get_document_attribute_value)
 313     {
 314       return (iface->get_document_attribute_value) (document, attribute_name);
 315     }
 316   else
 317     {
 318       return NULL;
 319     }
 320 }
 321
 322 /**
 323  * atk_document_set_attribute_value:
 324  * @document: a #GObject instance that implements AtkDocumentIface
 325  * @attribute_name: a character string representing the name of the attribute
 326  *            whose value is being set.
 327  * @attribute_value: a string value to be associated with #attribute_name.
 328  *
 329  * Since: 1.12
 330  *
 331  * Returns: TRUE if #value is successfully associated with #attribute_name
 332  *          for this document, FALSE otherwise (e.g. if the document does not
 333  *          allow the attribute to be modified).
 334  * Virtual: set_document_attribute
 335  */
 336 gboolean
 337 atk_document_set_attribute_value (AtkDocument *document,
 338                                   const gchar *attribute_name,
 339                                   const gchar *attribute_value)
 340 {
 341   AtkDocumentIface *iface;
 342
 343   g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
 344
 345   iface = ATK_DOCUMENT_GET_IFACE (document);
 346
 347   if (iface->set_document_attribute)
 348     {
 349       return (iface->set_document_attribute) (document, attribute_name, attribute_value);
 350     }
 351   else
 352     {
 353       return FALSE;
 354     }
 355 }