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 * Returns: a string indicating the document type
171 atk_document_get_document_type (AtkDocument *document)
173 AtkDocumentIface *iface;
175 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
177 iface = ATK_DOCUMENT_GET_IFACE (document);
179 if (iface->get_document_type)
181 return (iface->get_document_type) (document);
190 * atk_document_get_document:
191 * @document: a #GObject instance that implements AtkDocumentIface
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.
197 * Returns: (transfer none): a %gpointer that points to an instance of the DOM.
200 atk_document_get_document (AtkDocument *document)
202 AtkDocumentIface *iface;
204 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
206 iface = ATK_DOCUMENT_GET_IFACE (document);
208 if (iface->get_document)
210 return (iface->get_document) (document);
219 * atk_document_get_locale:
220 * @document: a #GObject instance that implements AtkDocumentIface
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.
228 * Deprecated: This method is deprecated since ATK version
229 * 2.7.90. Please use atk_object_get_object_locale() instead.
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
237 atk_document_get_locale (AtkDocument *document)
239 AtkDocumentIface *iface;
241 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
243 iface = ATK_DOCUMENT_GET_IFACE (document);
245 if (iface->get_document_locale)
247 return (iface->get_document_locale) (document);
257 * atk_document_get_attributes:
258 * @document: a #GObject instance that implements AtkDocumentIface
260 * Gets an AtkAttributeSet which describes document-wide
261 * attributes as name-value pairs.
265 * Returns: (transfer none): An AtkAttributeSet containing the explicitly
266 * set name-value-pair attributes associated with this document
268 * Virtual: get_document_attributes
271 atk_document_get_attributes (AtkDocument *document)
273 AtkDocumentIface *iface;
275 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
277 iface = ATK_DOCUMENT_GET_IFACE (document);
279 if (iface->get_document_attributes)
281 return (iface->get_document_attributes) (document);
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.
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
300 * Virtual: get_document_attribute_value
303 atk_document_get_attribute_value (AtkDocument *document,
304 const gchar *attribute_name)
306 AtkDocumentIface *iface;
308 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
310 iface = ATK_DOCUMENT_GET_IFACE (document);
312 if (iface->get_document_attribute_value)
314 return (iface->get_document_attribute_value) (document, attribute_name);
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.
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
337 atk_document_set_attribute_value (AtkDocument *document,
338 const gchar *attribute_name,
339 const gchar *attribute_value)
341 AtkDocumentIface *iface;
343 g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
345 iface = ATK_DOCUMENT_GET_IFACE (document);
347 if (iface->set_document_attribute)
349 return (iface->set_document_attribute) (document, attribute_name, attribute_value);