AtkDocument: ATK - Accessibility Toolkit

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

## Functions

const gchar * | atk_document_get_document_type ()
gpointer | atk_document_get_document ()
const gchar * | atk_document_get_attribute_value ()
gboolean | atk_document_set_attribute_value ()
AtkAttributeSet * | atk_document_get_attributes ()
const gchar * | atk_document_get_locale ()
gint | atk_document_get_current_page_number ()
gint | atk_document_get_page_count ()

## Signals

void | load-complete | Run Last
void | load-stopped | Run Last
void | page-changed | Run Last
void | reload | Run Last

## Types and Values

| AtkDocument
struct | AtkDocumentIface

## Object Hierarchy

        GInterface
        ╰── AtkDocument

## Known Implementations

AtkDocument is implemented by AtkNoOpObject.

## 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.

## Functions

### atk_document_get_document_type ()

    const gchar *
    atk_document_get_document_type (AtkDocument *document);

`atk_document_get_document_type` is deprecated and should not be used in newly-written code.

Since 2.12. Please use `atk_document_get_attributes()` to ask for the document type if it applies.

Gets a string indicating the document type.

#### Parameters

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);

`atk_document_get_document` is deprecated and should not be used in newly-written code.

Since 2.12. `document` is already a representation of the document. Use it directly, or one of his children, as an instance of the DOM.

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.

#### Parameters

document | a GObject instance that implements AtkDocumentIface |

#### Returns

a `gpointer` that points to an instance of the DOM.

[transfer none]

### atk_document_get_attribute_value ()

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

#### Parameters

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.

[nullable]

Since 1.12

### atk_document_set_attribute_value ()

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

#### Parameters

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 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.

#### Parameters

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.

[transfer none]

Since 1.12

### atk_document_get_locale ()

    const gchar *
    atk_document_get_locale (AtkDocument *document);

`atk_document_get_locale` has been deprecated since version 2.7.90 and should not be used in newly-written code.

Please use `atk_object_get_object_locale()` instead.

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.

#### Parameters

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.

### atk_document_get_current_page_number ()

    gint
    atk_document_get_current_page_number (AtkDocument *document);

#### Parameters

document | the AtkDocument |

#### Returns

current page number inside `document` . -1 if not implemented, not know by the implementor or irrelevant.

Since 2.12

### atk_document_get_page_count ()

    gint
    atk_document_get_page_count (AtkDocument *document);

#### Parameters

document | the AtkDocument |

#### Returns

total page count of `document` . -1 if not implemented, not know by the implementor or irrelevant.

Since 2.12

## Types and Values

### AtkDocument

    typedef struct _AtkDocument AtkDocument;

### struct AtkDocumentIface

    struct AtkDocumentIface {
      GTypeInterface parent;
      const gchar*          ( *get_document_type) (AtkDocument              *document);
      gpointer              ( *get_document)      (AtkDocument              *document);

      const gchar*          ( *get_document_locale) (AtkDocument              *document);
      AtkAttributeSet *     ( *get_document_attributes) (AtkDocument        *document);
      const gchar*          ( *get_document_attribute_value) (AtkDocument   *document,
                                                              const gchar   *attribute_name);
      gboolean              ( *set_document_attribute) (AtkDocument         *document,
                                                        const gchar         *attribute_name,
                                                        const gchar         *attribute_value);
      gint                  ( *get_current_page_number) (AtkDocument *document);
      gint                  ( *get_page_count) (AtkDocument *document);
    };

#### Members

GTypeInterface `parent`; |  |
`get_document_type` () | gets a string indicating the document type. This virtual function is deprecated since 2.12 and it should not be overriden. |
`get_document` () | a GObject instance that implements AtkDocumentIface. This virtual method is deprecated since 2.12 and it should not be overriden. |
`get_document_locale` () | gets locale. This virtual function is deprecated since 2.7.90 and it should not be overriden. |
`get_document_attributes` () | gets an AtkAttributeSet which describes document-wide attributes as name-value pairs. |
`get_document_attribute_value` () | returns a string value assocciated with the named attribute for this document, or NULL |
`set_document_attribute` () | sets the value of an attribute. Returns TRUE on success, FALSE otherwise |
`get_current_page_number` () | gets the current page number. Since 2.12 |
`get_page_count` () | gets the page count of the document. Since 2.12 |

## Signal Details

### The `“load-complete”` signal

    void
    user_function (AtkDocument *atkdocument,
                   gpointer     user_data)

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.)

#### Parameters

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

Flags: Run Last

### The `“load-stopped”` signal

    void
    user_function (AtkDocument *atkdocument,
                   gpointer     user_data)

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.

#### Parameters

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

Flags: Run Last

### The `“page-changed”` signal

    void
    user_function (AtkDocument *atkdocument,
                   gint         page_number,
                   gpointer     user_data)

The 'page-changed' signal is emitted when the current page of a document changes, e.g. pressing page up/down in a document viewer.

#### Parameters

atkdocument | the object on which the signal was emitted |
page_number | the new page number. If this value is unknown or not applicable, -1 should be provided. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since 2.12

### The `“reload”` signal

    void
    user_function (AtkDocument *atkdocument,
                   gpointer     user_data)

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.

#### Parameters

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

Flags: Run Last