AtkDocument

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

Synopsis

                    AtkDocument;
struct              AtkDocumentIface;
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
  "page-changed"                                   : 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;


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

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

atk_document_get_document_type ()

const gchar *       atk_document_get_document_type      (AtkDocument *document);

Warning

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.

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

Warning

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.

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

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 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 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. [transfer none]

Since 1.12


atk_document_get_locale ()

const gchar *       atk_document_get_locale             (AtkDocument *document);

Warning

atk_document_get_locale is deprecated and should not be used in newly-written code. This method is deprecated since ATK version 2.7.90. 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.

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 "page-changed" signal

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

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

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.

Since 2.12


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.