AtkDocument

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

Functions

Signals

Types and Values

Object Hierarchy

    GInterface
    ╰── AtkDocument

Known Implementations

AtkDocument is implemented by AtkNoOpObject.

Includes

#include <atk/atk.h>

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.

[virtual get_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 its 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.

[virtual get_document]

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

Retrieves the value of the given attribute_name inside document .

[virtual get_document_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 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);

Sets the value for the given attribute_name inside document .

[virtual set_document_attribute]

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 attribute_value is successfully associated with attribute_name for this document , and FALSE if 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.

[virtual get_document_attributes]

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.

[virtual get_document_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);

Retrieves the current page number inside document .

Parameters

document

the AtkDocument

 

Returns

the current page number inside document , or -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);

Retrieves the total number of pages inside document .

Parameters

document

the AtkDocument

 

Returns

total page count of document , or -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,
               int          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