1 /* ATK - Accessibility Toolkit
2 * Copyright 2001 Sun Microsystems Inc.
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.
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.
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.
20 #include "atkdocument.h"
24 * @Short_description: The ATK interface which represents the toplevel
25 * container for document content.
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.
46 static void atk_document_base_init (AtkDocumentIface *class);
48 static guint atk_document_signals[LAST_SIGNAL] = {0};
51 atk_document_get_type (void)
53 static GType type = 0;
56 static const GTypeInfo tinfo =
58 sizeof (AtkDocumentIface),
59 (GBaseInitFunc) atk_document_base_init,
60 (GBaseFinalizeFunc) NULL,
64 type = g_type_register_static (G_TYPE_INTERFACE, "AtkDocument", &tinfo, 0);
71 atk_document_base_init (AtkDocumentIface *class)
73 static gboolean initialized = FALSE;
77 * AtkDocument::load-complete:
78 * @atkdocument: the object which received the signal.
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
90 atk_document_signals[LOAD_COMPLETE] =
91 g_signal_new ("load_complete",
95 (GSignalAccumulator) NULL, NULL,
96 g_cclosure_marshal_VOID__VOID,
99 * AtkDocument::reload:
100 * @atkdocument: the object which received the signal.
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.
108 atk_document_signals[RELOAD] =
109 g_signal_new ("reload",
113 (GSignalAccumulator) NULL, NULL,
114 g_cclosure_marshal_VOID__VOID,
118 * AtkDocument::load-stopped:
119 * @atkdocument: the object which received the signal.
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.
128 atk_document_signals[LOAD_STOPPED] =
129 g_signal_new ("load_stopped",
133 (GSignalAccumulator) NULL, NULL,
134 g_cclosure_marshal_VOID__VOID,
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.
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
149 atk_document_signals[PAGE_CHANGED] =
150 g_signal_new ("page_changed",
154 (GSignalAccumulator) NULL, NULL,
155 g_cclosure_marshal_VOID__INT,
156 G_TYPE_NONE, 1, G_TYPE_INT);
163 * atk_document_get_document_type:
164 * @document: a #GObject instance that implements AtkDocumentIface
166 * Gets a string indicating the document type.
168 * Deprecated: Since 2.12. Please use atk_document_get_attributes() to
169 * ask for the document type if it applies.
171 * Returns: a string indicating the document type
174 atk_document_get_document_type (AtkDocument *document)
176 AtkDocumentIface *iface;
178 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
180 iface = ATK_DOCUMENT_GET_IFACE (document);
182 if (iface->get_document_type)
184 return (iface->get_document_type) (document);
193 * atk_document_get_document:
194 * @document: a #GObject instance that implements AtkDocumentIface
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.
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.
204 * Returns: (transfer none): a %gpointer that points to an instance of the DOM.
207 atk_document_get_document (AtkDocument *document)
209 AtkDocumentIface *iface;
211 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
213 iface = ATK_DOCUMENT_GET_IFACE (document);
215 if (iface->get_document)
217 return (iface->get_document) (document);
226 * atk_document_get_locale:
227 * @document: a #GObject instance that implements AtkDocumentIface
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.
235 * Deprecated: This method is deprecated since ATK version
236 * 2.7.90. Please use atk_object_get_object_locale() instead.
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.
243 atk_document_get_locale (AtkDocument *document)
245 AtkDocumentIface *iface;
247 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
249 iface = ATK_DOCUMENT_GET_IFACE (document);
251 if (iface->get_document_locale)
253 return (iface->get_document_locale) (document);
263 * atk_document_get_attributes:
264 * @document: a #GObject instance that implements AtkDocumentIface
266 * Gets an AtkAttributeSet which describes document-wide
267 * attributes as name-value pairs.
271 * Returns: (transfer none): An AtkAttributeSet containing the explicitly
272 * set name-value-pair attributes associated with this document
276 atk_document_get_attributes (AtkDocument *document)
278 AtkDocumentIface *iface;
280 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
282 iface = ATK_DOCUMENT_GET_IFACE (document);
284 if (iface->get_document_attributes)
286 return (iface->get_document_attributes) (document);
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.
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
307 atk_document_get_attribute_value (AtkDocument *document,
308 const gchar *attribute_name)
310 AtkDocumentIface *iface;
312 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
314 iface = ATK_DOCUMENT_GET_IFACE (document);
316 if (iface->get_document_attribute_value)
318 return (iface->get_document_attribute_value) (document, attribute_name);
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.
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).
340 atk_document_set_attribute_value (AtkDocument *document,
341 const gchar *attribute_name,
342 const gchar *attribute_value)
344 AtkDocumentIface *iface;
346 g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
348 iface = ATK_DOCUMENT_GET_IFACE (document);
350 if (iface->set_document_attribute)
352 return (iface->set_document_attribute) (document, attribute_name, attribute_value);
361 * atk_document_get_current_page_number:
362 * @document: the #AtkDocument
366 * Returns: current page number inside @document. -1 if not
367 * implemented, not know by the implementor or irrelevant.
370 atk_document_get_current_page_number (AtkDocument *document)
372 AtkDocumentIface *iface;
374 g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
376 iface = ATK_DOCUMENT_GET_IFACE (document);
378 if (iface->get_current_page_number)
380 return (iface->get_current_page_number) (document);
389 * atk_document_get_page_count:
390 * @document: the #AtkDocument
394 * Returns: total page count of @document. -1 if not implemented, not
395 * know by the implementor or irrelevant.
398 atk_document_get_page_count (AtkDocument *document)
400 AtkDocumentIface *iface;
402 g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
404 iface = ATK_DOCUMENT_GET_IFACE (document);
406 if (iface->get_page_count)
408 return (iface->get_page_count) (document);