AtkDocument

## AtkDocument AtkDocument — The ATK interface which represents the toplevel container for document content. |

## Synopsis

                        AtkDocument;
    const gchar*        atk_document_get_document_type      (AtkDocument *document);
    gpointer            atk_document_get_document           (AtkDocument *document);
    const gchar*        atk_document_get_attribute_value    (AtkDocument *document,
                                                             const gchar *attribute_name);
    gboolean            atk_document_set_attribute_value    (AtkDocument *document,
                                                             const gchar *attribute_name,
                                                             const gchar *attribute_value);
    AtkAttributeSet*    atk_document_get_attributes         (AtkDocument *document);
    const gchar*        atk_document_get_locale             (AtkDocument *document);

## Object Hierarchy

      GInterface
       +----AtkDocument

## Known Implementations

AtkDocument is implemented by AtkNoOpObject.

## Signals

      "load-complete"                                  : Run Last
      "load-stopped"                                   : Run Last
      "reload"                                         : Run Last

## Description

The AtkDocument interface should be supported by any object whose content is a representation or view of a document. The AtkDocument interface should appear on the toplevel container for the document content; however AtkDocument instances may be nested (i.e. an AtkDocument may be a descendant of another AtkDocument) in those cases where one document contains "embedded content" which can reasonably be considered a document in its own right.

## Details

### AtkDocument

    typedef struct _AtkDocument AtkDocument;

The AtkDocument structure does not contain any fields.

### atk_document_get_document_type ()

    const gchar*        atk_document_get_document_type      (AtkDocument *document);

Gets a string indicating the document type.

`document` : | a GObject instance that implements AtkDocumentIface
Returns : | a string indicating the document type

### atk_document_get_document ()

    gpointer            atk_document_get_document           (AtkDocument *document);

Gets a `gpointer` that points to an instance of the DOM. It is up to the caller to check atk_document_get_type to determine how to cast this pointer.

`document` : | a GObject instance that implements AtkDocumentIface
Returns : | a `gpointer` that points to an instance of the DOM.

### atk_document_get_attribute_value ()

    const gchar*        atk_document_get_attribute_value    (AtkDocument *document,
                                                             const gchar *attribute_name);

`document` : | a GObject instance that implements AtkDocumentIface
`attribute_name` : | a character string representing the name of the attribute whose value is being queried.
Returns : | a string value associated with the named attribute for this document, or NULL if a value for attribute_name has not been specified for this document.

Since ATK 1.12

### atk_document_set_attribute_value ()

    gboolean            atk_document_set_attribute_value    (AtkDocument *document,
                                                             const gchar *attribute_name,
                                                             const gchar *attribute_value);

`document` : | a GObject instance that implements AtkDocumentIface
`attribute_name` : | a character string representing the name of the attribute whose value is being set.
`attribute_value` : | a string value to be associated with attribute_name.
Returns : | TRUE if value is successfully associated with attribute_name for this document, FALSE otherwise (e.g. if the document does not allow the attribute to be modified).

Since ATK 1.12

### atk_document_get_attributes ()

    AtkAttributeSet*    atk_document_get_attributes         (AtkDocument *document);

Gets an AtkAttributeSet which describes document-wide attributes as name-value pairs.

`document` : | a GObject instance that implements AtkDocumentIface
Returns : | An AtkAttributeSet containing the explicitly set name-value-pair attributes associated with this document as a whole.

Since ATK 1.12

### atk_document_get_locale ()

    const gchar*        atk_document_get_locale             (AtkDocument *document);

Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of the content of this document instance. Individual text substrings or images within this document may have a different locale, see atk_text_get_attributes and atk_image_get_image_locale.

`document` : | a GObject instance that implements AtkDocumentIface
Returns : | a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of the document content as a whole, or NULL if the document content does not specify a locale.

## Signal Details

### The `"load-complete"` signal

    void                user_function                      (AtkDocument *atkdocument,
                                                            gpointer     user_data)        : Run Last

The 'load-complete' signal is emitted when a pending load of a static document has completed. This signal is to be expected by ATK clients if and when AtkDocument implementors expose ATK_STATE_BUSY. If the state of an AtkObject which implements AtkDocument does not include ATK_STATE_BUSY, it should be safe for clients to assume that the AtkDocument's static contents are fully loaded into the container. (Dynamic document contents should be exposed via other signals.)

`atkdocument` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"load-stopped"` signal

    void                user_function                      (AtkDocument *atkdocument,
                                                            gpointer     user_data)        : Run Last

The 'load-stopped' signal is emitted when a pending load of document contents is cancelled, paused, or otherwise interrupted by the user or application logic. It should not however be emitted while waiting for a resource (for instance while blocking on a file or network read) unless a user-significant timeout has occurred.

`atkdocument` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"reload"` signal

    void                user_function                      (AtkDocument *atkdocument,
                                                            gpointer     user_data)        : Run Last

The 'reload' signal is emitted when the contents of a document is refreshed from its source. Once 'reload' has been emitted, a matching 'load-complete' or 'load-stopped' signal should follow, which clients may await before interrogating ATK for the latest document content.

`atkdocument` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.