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.
22 #include "atkdocument.h"
26 * @Short_description: The ATK interface which represents the toplevel
27 * container for document content.
30 * The AtkDocument interface should be supported by any object whose
31 * content is a representation or view of a document. The AtkDocument
32 * interface should appear on the toplevel container for the document
33 * content; however AtkDocument instances may be nested (i.e. an
34 * AtkDocument may be a descendant of another AtkDocument) in those
35 * cases where one document contains "embedded content" which can
36 * reasonably be considered a document in its own right.
48 static void atk_document_base_init (AtkDocumentIface *class);
50 static guint atk_document_signals[LAST_SIGNAL] = {0};
53 atk_document_get_type (void)
55 static GType type = 0;
58 static const GTypeInfo tinfo =
60 sizeof (AtkDocumentIface),
61 (GBaseInitFunc) atk_document_base_init,
62 (GBaseFinalizeFunc) NULL,
66 type = g_type_register_static (G_TYPE_INTERFACE, "AtkDocument", &tinfo, 0);
73 atk_document_base_init (AtkDocumentIface *class)
75 static gboolean initialized = FALSE;
79 * AtkDocument::load-complete:
80 * @atkdocument: the object which received the signal.
82 * The 'load-complete' signal is emitted when a pending load of
83 * a static document has completed. This signal is to be
84 * expected by ATK clients if and when AtkDocument implementors
85 * expose ATK_STATE_BUSY. If the state of an AtkObject which
86 * implements AtkDocument does not include ATK_STATE_BUSY, it
87 * should be safe for clients to assume that the AtkDocument's
88 * static contents are fully loaded into the container.
89 * (Dynamic document contents should be exposed via other
92 atk_document_signals[LOAD_COMPLETE] =
93 g_signal_new ("load_complete",
97 (GSignalAccumulator) NULL, NULL,
98 g_cclosure_marshal_VOID__VOID,
101 * AtkDocument::reload:
102 * @atkdocument: the object which received the signal.
104 * The 'reload' signal is emitted when the contents of a
105 * document is refreshed from its source. Once 'reload' has
106 * been emitted, a matching 'load-complete' or 'load-stopped'
107 * signal should follow, which clients may await before
108 * interrogating ATK for the latest document content.
110 atk_document_signals[RELOAD] =
111 g_signal_new ("reload",
115 (GSignalAccumulator) NULL, NULL,
116 g_cclosure_marshal_VOID__VOID,
120 * AtkDocument::load-stopped:
121 * @atkdocument: the object which received the signal.
123 * The 'load-stopped' signal is emitted when a pending load of
124 * document contents is cancelled, paused, or otherwise
125 * interrupted by the user or application logic. It should not
126 * however be emitted while waiting for a resource (for instance
127 * while blocking on a file or network read) unless a
128 * user-significant timeout has occurred.
130 atk_document_signals[LOAD_STOPPED] =
131 g_signal_new ("load_stopped",
135 (GSignalAccumulator) NULL, NULL,
136 g_cclosure_marshal_VOID__VOID,
140 * AtkDocument::page-changed:
141 * @atkdocument: the object on which the signal was emitted
142 * @page_number: the new page number. If this value is unknown
143 * or not applicable, -1 should be provided.
145 * The 'page-changed' signal is emitted when the current page of
146 * a document changes, e.g. pressing page up/down in a document
151 atk_document_signals[PAGE_CHANGED] =
152 g_signal_new ("page_changed",
156 (GSignalAccumulator) NULL, NULL,
157 g_cclosure_marshal_VOID__INT,
158 G_TYPE_NONE, 1, G_TYPE_INT);
165 * atk_document_get_document_type: (virtual get_document_type)
166 * @document: a #GObject instance that implements AtkDocumentIface
168 * Gets a string indicating the document type.
170 * Deprecated: Since 2.12. Please use atk_document_get_attributes() to
171 * ask for the document type if it applies.
173 * Returns: a string indicating the document type
176 atk_document_get_document_type (AtkDocument *document)
178 AtkDocumentIface *iface;
180 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
182 iface = ATK_DOCUMENT_GET_IFACE (document);
184 if (iface->get_document_type)
186 return (iface->get_document_type) (document);
195 * atk_document_get_document: (virtual get_document)
196 * @document: a #GObject instance that implements AtkDocumentIface
198 * Gets a %gpointer that points to an instance of the DOM. It is
199 * up to the caller to check atk_document_get_type to determine
200 * how to cast this pointer.
202 * Deprecated: Since 2.12. @document is already a representation of
203 * the document. Use it directly, or one of its children, as an
204 * instance of the DOM.
206 * Returns: (transfer none): a %gpointer that points to an instance of the DOM.
209 atk_document_get_document (AtkDocument *document)
211 AtkDocumentIface *iface;
213 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
215 iface = ATK_DOCUMENT_GET_IFACE (document);
217 if (iface->get_document)
219 return (iface->get_document) (document);
228 * atk_document_get_locale: (virtual get_document_locale)
229 * @document: a #GObject instance that implements AtkDocumentIface
231 * Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale
232 * of the content of this document instance. Individual
233 * text substrings or images within this document may have
234 * a different locale, see atk_text_get_attributes and
235 * atk_image_get_image_locale.
237 * Deprecated: 2.7.90: Please use atk_object_get_object_locale() instead.
239 * Returns: a UTF-8 string indicating the POSIX-style LC_MESSAGES
240 * locale of the document content as a whole, or NULL if
241 * the document content does not specify a locale.
244 atk_document_get_locale (AtkDocument *document)
246 AtkDocumentIface *iface;
248 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
250 iface = ATK_DOCUMENT_GET_IFACE (document);
252 if (iface->get_document_locale)
254 return (iface->get_document_locale) (document);
264 * atk_document_get_attributes: (virtual get_document_attributes)
265 * @document: a #GObject instance that implements AtkDocumentIface
267 * Gets an AtkAttributeSet which describes document-wide
268 * attributes as name-value pairs.
272 * Returns: (transfer none): An AtkAttributeSet containing the explicitly
273 * set name-value-pair attributes associated with this document
277 atk_document_get_attributes (AtkDocument *document)
279 AtkDocumentIface *iface;
281 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
283 iface = ATK_DOCUMENT_GET_IFACE (document);
285 if (iface->get_document_attributes)
287 return (iface->get_document_attributes) (document);
296 * atk_document_get_attribute_value: (virtual get_document_attribute_value)
297 * @document: a #GObject instance that implements AtkDocumentIface
298 * @attribute_name: a character string representing the name of the attribute
299 * whose value is being queried.
301 * Retrieves the value of the given @attribute_name inside @document.
303 * Returns: (nullable): a string value associated with the named
304 * attribute for this document, or %NULL if a value for
305 * @attribute_name has not been specified for this document.
310 atk_document_get_attribute_value (AtkDocument *document,
311 const gchar *attribute_name)
313 AtkDocumentIface *iface;
315 g_return_val_if_fail (ATK_IS_DOCUMENT (document), NULL);
317 iface = ATK_DOCUMENT_GET_IFACE (document);
319 if (iface->get_document_attribute_value)
321 return (iface->get_document_attribute_value) (document, attribute_name);
330 * atk_document_set_attribute_value: (virtual set_document_attribute)
331 * @document: a #GObject instance that implements #AtkDocumentIface
332 * @attribute_name: a character string representing the name of the attribute
333 * whose value is being set.
334 * @attribute_value: a string value to be associated with @attribute_name.
336 * Sets the value for the given @attribute_name inside @document.
340 * Returns: %TRUE if @attribute_value is successfully associated
341 * with @attribute_name for this @document, and %FALSE if if the
342 * document does not allow the attribute to be modified
345 atk_document_set_attribute_value (AtkDocument *document,
346 const gchar *attribute_name,
347 const gchar *attribute_value)
349 AtkDocumentIface *iface;
351 g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
353 iface = ATK_DOCUMENT_GET_IFACE (document);
355 if (iface->set_document_attribute)
357 return (iface->set_document_attribute) (document, attribute_name, attribute_value);
366 * atk_document_get_current_page_number:
367 * @document: the #AtkDocument
369 * Retrieves the current page number inside @document.
371 * Returns: the current page number inside @document, or -1 if
372 * not implemented, not know by the implementor, or irrelevant.
377 atk_document_get_current_page_number (AtkDocument *document)
379 AtkDocumentIface *iface;
381 g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
383 iface = ATK_DOCUMENT_GET_IFACE (document);
385 if (iface->get_current_page_number)
387 return (iface->get_current_page_number) (document);
396 * atk_document_get_page_count:
397 * @document: the #AtkDocument
399 * Retrieves the total number of pages inside @document.
401 * Returns: total page count of @document, or -1 if not implemented,
402 * not know by the implementor or irrelevant.
407 atk_document_get_page_count (AtkDocument *document)
409 AtkDocumentIface *iface;
411 g_return_val_if_fail (ATK_IS_DOCUMENT (document), FALSE);
413 iface = ATK_DOCUMENT_GET_IFACE (document);
415 if (iface->get_page_count)
417 return (iface->get_page_count) (document);