## cong-document

cong-document —

## Synopsis

    #define     CONG_DOCUMENT                   (obj)
    #define     CONG_DOCUMENT_CLASS             (klass)
    #define     IS_CONG_DOCUMENT                (obj)
    GType       cong_document_get_type          (void);
    CongDocument* cong_document_construct       (CongDocument *doc,
                                                 xmlDocPtr xml_doc,
                                                 CongDispspec *ds,
                                                 const gchar *url);
    CongDocument* cong_document_new_from_xmldoc (xmlDocPtr xml_doc,
                                                 CongDispspec *ds,
                                                 const gchar *url);
    xmlDocPtr   cong_document_get_xml           (CongDocument *doc);
    CongNodePtr cong_document_get_root          (CongDocument *doc);
    CongDispspec* cong_document_get_dispspec    (CongDocument *doc);
    CongDispspecElement* cong_document_get_dispspec_element_for_node
                                                (CongDocument *doc,
                                                 CongNodePtr node);
    gchar*      cong_document_get_filename      (CongDocument *doc);
    gchar*      cong_document_get_full_uri      (CongDocument *doc);
    gchar*      cong_document_get_parent_uri    (CongDocument *doc);
    const CongXMLChar* cong_document_get_dtd_public_identifier
                                                (CongDocument *doc);
    xmlNsPtr    cong_document_get_nsptr         (CongDocument *doc,
                                                 const gchar *xmlns);
    void        cong_document_save              (CongDocument *doc,
                                                 const char *filename,
                                                 GtkWindow *parent_window);
    gboolean    cong_document_is_modified       (CongDocument *doc);
    void        cong_document_set_modified      (CongDocument *doc,
                                                 gboolean modified);
    void        cong_document_set_primary_window
                                                (CongDocument *doc,
                                                 CongPrimaryWindow *window);
    void        cong_document_set_url           (CongDocument *doc,
                                                 const gchar *url);
    glong       cong_document_get_seconds_since_last_save_or_load
                                                (const CongDocument *doc);
    guint       cong_document_get_num_nodes     (CongDocument *doc);
    void        cong_document_node_ref          (CongDocument *doc,
                                                 CongNodePtr node);
    void        cong_document_node_unref        (CongDocument *doc,
                                                 CongNodePtr node);
    void        cong_document_set_with_ref      (CongDocument *doc,
                                                 CongNodePtr *node_ptr,
                                                 CongNodePtr node);
    CongCommand* cong_document_begin_command    (CongDocument *doc,
                                                 const gchar *description,
                                                 const gchar *consolidation_id);
    void        cong_document_end_command       (CongDocument *doc,
                                                 CongCommand *cmd);
    void        cong_document_begin_edit        (CongDocument *doc);
    void        cong_document_end_edit          (CongDocument *doc);
    gboolean    cong_document_is_within_edit    (CongDocument *doc);
    void        cong_document_private_node_make_orphan
                                                (CongDocument *doc,
                                                 CongNodePtr node);
    void        cong_document_private_node_add_after
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 CongNodePtr older_sibling);
    void        cong_document_private_node_add_before
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 CongNodePtr younger_sibling);
    void        cong_document_private_node_set_parent
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 CongNodePtr adoptive_parent,
                                                 gboolean add_to_end);
    void        cong_document_private_node_set_text
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 const xmlChar *new_content);
    void        cong_document_private_tag_remove
                                                (CongDocument *doc,
                                                 CongNodePtr x);
    void        cong_document_private_node_set_attribute
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 xmlNs *ns_ptr,
                                                 const xmlChar *name,
                                                 const xmlChar *value);
    void        cong_document_private_node_remove_attribute
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 xmlNs *ns_ptr,
                                                 const xmlChar *name);
    void        cong_document_private_on_selection_change
                                                (CongDocument *doc);
    void        cong_document_private_on_cursor_change
                                                (CongDocument *doc);
    void        cong_document_private_set_dtd_ptr
                                                (CongDocument *doc,
                                                 xmlDtdPtr dtd_ptr);
    void        cong_document_register_view     (CongDocument *doc,
                                                 CongView *view);
    void        cong_document_unregister_view   (CongDocument *doc,
                                                 CongView *view);
    CongCursor* cong_document_get_cursor        (CongDocument *doc);
    CongSelection* cong_document_get_selection  (CongDocument *doc);
    PangoLanguage* cong_document_get_language_for_node
                                                (CongDocument *doc,
                                                 CongNodePtr node);
    CongCommandHistory* cong_document_get_command_history
                                                (CongDocument *doc);
    void        cong_document_undo              (CongDocument *doc);
    void        cong_document_redo              (CongDocument *doc);
    void        cong_document_cut_selection     (CongDocument *doc);
    void        cong_document_copy_selection    (CongDocument *doc);
    void        cong_document_paste_clipboard_or_selection
                                                (CongDocument *doc,
                                                 GtkWidget *widget);
    void        cong_document_paste_source_at   (CongDocument *doc,
                                                 CongLocation *insert_loc,
                                                 const gchar *source_fragment);
    void        cong_document_paste_source_under
                                                (CongDocument *doc,
                                                 CongNodePtr relative_to_node,
                                                 const gchar *source_fragment);
    void        cong_document_paste_source_before
                                                (CongDocument *doc,
                                                 CongNodePtr relative_to_node,
                                                 const gchar *source_fragment);
    void        cong_document_paste_source_after
                                                (CongDocument *doc,
                                                 CongNodePtr relative_to_node,
                                                 const gchar *source_fragment);
    void        cong_document_view_source       (CongDocument *doc);
    gboolean    (*CongDocumentRecursionCallback)
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 gpointer user_data,
                                                 guint recursion_level);
    gboolean    cong_document_for_each_node     (CongDocument *doc,
                                                 CongDocumentRecursionCallback callback,
                                                 gpointer callback_data);
    gboolean    cong_document_for_each_child_of_node
                                                (CongDocument *doc,
                                                 CongNodePtr parent,
                                                 CongDocumentRecursionCallback callback,
                                                 gpointer callback_data);
    CongNodePtr cong_document_make_nodes_from_source_fragment
                                                (CongDocument *doc,
                                                 const gchar *source_fragment);
    typedef     gboolean                        ();
    xmlElementPtr cong_document_get_dtd_element (CongDocument *cong_doc,
                                                 CongNodePtr node);
    GList*      cong_document_get_valid_new_child_elements
                                                (CongDocument *doc,
                                                 CongNodePtr node);
    GList*      cong_document_get_valid_new_previous_sibling_elements
                                                (CongDocument *doc,
                                                 CongNodePtr node);
    GList*      cong_document_get_valid_new_next_sibling_elements
                                                (CongDocument *doc,
                                                 CongNodePtr node);

## Description

## Details

### CONG_DOCUMENT()

    #define CONG_DOCUMENT(obj)         G_TYPE_CHECK_INSTANCE_CAST (obj, CONG_DOCUMENT_TYPE, CongDocument)

`obj` : |

### CONG_DOCUMENT_CLASS()

    #define CONG_DOCUMENT_CLASS(klass) G_TYPE_CHECK_CLASS_CAST (klass, CONG_DOCUMENT_TYPE, CongDocumentClass)

`klass` : |

### IS_CONG_DOCUMENT()

    #define IS_CONG_DOCUMENT(obj)      G_TYPE_CHECK_INSTANCE_TYPE (obj, CONG_DOCUMENT_TYPE)

`obj` : |

### cong_document_get_type ()

    GType       cong_document_get_type          (void);

Returns : |

### cong_document_construct ()

    CongDocument* cong_document_construct       (CongDocument *doc,
                                                 xmlDocPtr xml_doc,
                                                 CongDispspec *ds,
                                                 const gchar *url);

TODO: Write me

`doc` : |
`xml_doc` : |
`ds` : |
`url` : |
Returns : |

### cong_document_new_from_xmldoc ()

    CongDocument* cong_document_new_from_xmldoc (xmlDocPtr xml_doc,
                                                 CongDispspec *ds,
                                                 const gchar *url);

The new CongDocument is created with a reference count of 1; any views constructed of the document will increment its reference count

`xml_doc` : |
`ds` : |
`url` : |
Returns : | the new CongDocument

### cong_document_get_xml ()

    xmlDocPtr   cong_document_get_xml           (CongDocument *doc);

Retrieve the xmlDocPtr wrapped by a CongDocument. You should not attempt to modify it directly, but instead use methods of the CongDocument

`doc` : | The CongDocument.
Returns : | the xmlDocPtr wrapped by the CongDocument

### cong_document_get_root ()

    CongNodePtr cong_document_get_root          (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_get_dispspec ()

    CongDispspec* cong_document_get_dispspec    (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_get_dispspec_element_for_node ()

    CongDispspecElement* cong_document_get_dispspec_element_for_node
                                                (CongDocument *doc,
                                                 CongNodePtr node);

TODO: Write me

`doc` : |
`node` : |
Returns : |

### cong_document_get_filename ()

    gchar*      cong_document_get_filename      (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_get_full_uri ()

    gchar*      cong_document_get_full_uri      (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_get_parent_uri ()

    gchar*      cong_document_get_parent_uri    (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_get_dtd_public_identifier ()

    const CongXMLChar* cong_document_get_dtd_public_identifier
                                                (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_get_nsptr ()

    xmlNsPtr    cong_document_get_nsptr         (CongDocument *doc,
                                                 const gchar *xmlns);

`doc` : |
`xmlns` : |
Returns : |

### cong_document_save ()

    void        cong_document_save              (CongDocument *doc,
                                                 const char *filename,
                                                 GtkWindow *parent_window);

TODO: Write me

`doc` : |
`filename` : |
`parent_window` : |

### cong_document_is_modified ()

    gboolean    cong_document_is_modified       (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_set_modified ()

    void        cong_document_set_modified      (CongDocument *doc,
                                                 gboolean modified);

TODO: Write me

`doc` : |
`modified` : |

### cong_document_set_primary_window ()

    void        cong_document_set_primary_window
                                                (CongDocument *doc,
                                                 CongPrimaryWindow *window);

TODO: Write me

`doc` : |
`window` : |

### cong_document_set_url ()

    void        cong_document_set_url           (CongDocument *doc,
                                                 const gchar *url);

TODO: Write me

`doc` : |
`url` : |

### cong_document_get_seconds_since_last_save_or_load ()

    glong       cong_document_get_seconds_since_last_save_or_load
                                                (const CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_get_num_nodes ()

    guint       cong_document_get_num_nodes     (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_node_ref ()

    void        cong_document_node_ref          (CongDocument *doc,
                                                 CongNodePtr node);

Add an "external reference" to the node; it will not be deleted until it has been both removed from the tree AND has lost all external references.

`doc` : |
`node` : |

### cong_document_node_unref ()

    void        cong_document_node_unref        (CongDocument *doc,
                                                 CongNodePtr node);

Remove an "external reference" to the node; it will be deleted if it has been both removed from the tree AND this was its last external reference.

`doc` : |
`node` : |

### cong_document_set_with_ref ()

    void        cong_document_set_with_ref      (CongDocument *doc,
                                                 CongNodePtr *node_ptr,
                                                 CongNodePtr node);

Sets `node_ptr` to `node`, doing any necessary reference count modifications to the old and new value

`doc` : |
`node_ptr` : | A pointer to a CongNodePtr
`node` : | a ptr to a node, or NULL

### cong_document_begin_command ()

    CongCommand* cong_document_begin_command    (CongDocument *doc,
                                                 const gchar *description,
                                                 const gchar *consolidation_id);

Begins creating a named command which will act upon the document. You can then add modifications to this command, and then finish with a call to `cong_document_end_command()`

`doc` : | The CongDocument upon which the command is to act.
`description` : | Human-readable, translated name for this command, as it will appear in the undo/redo history widget
`consolidation_id` : | A string ID (or NULL) for this command to allow multiple similar commands to be consolidated into a single command. For example, multiple characters being typed at the keboard can be merged into a single "Typing" command.
Returns : | a CongCommand to which modifications should be added

### cong_document_end_command ()

    void        cong_document_end_command       (CongDocument *doc,
                                                 CongCommand *cmd);

Finish creating a command which has acted upon the document. You should have created this command using a call to `cong_document_begin_command()`

`doc` : | The CongDocument upon which the command acted.
`cmd` : | The CongCommand which is now complete

### cong_document_begin_edit ()

    void        cong_document_begin_edit        (CongDocument *doc);

TODO: Write me

`doc` : |

### cong_document_end_edit ()

    void        cong_document_end_edit          (CongDocument *doc);

TODO: Write me

`doc` : |

### cong_document_is_within_edit ()

    gboolean    cong_document_is_within_edit    (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_private_node_make_orphan ()

    void        cong_document_private_node_make_orphan
                                                (CongDocument *doc,
                                                 CongNodePtr node);

TODO: Write me

`doc` : |
`node` : |

### cong_document_private_node_add_after ()

    void        cong_document_private_node_add_after
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 CongNodePtr older_sibling);

TODO: Write me

`doc` : |
`node` : |
`older_sibling` : |

### cong_document_private_node_add_before ()

    void        cong_document_private_node_add_before
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 CongNodePtr younger_sibling);

TODO: Write me

`doc` : |
`node` : |
`younger_sibling` : |

### cong_document_private_node_set_parent ()

    void        cong_document_private_node_set_parent
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 CongNodePtr adoptive_parent,
                                                 gboolean add_to_end);

TODO: Write me

`doc` : |
`node` : |
`adoptive_parent` : |
`add_to_end` : | if TRUE, add the node to the end of the parent's list; if FALSE add to the start

### cong_document_private_node_set_text ()

    void        cong_document_private_node_set_text
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 const xmlChar *new_content);

TODO: Write me

`doc` : |
`node` : |
`new_content` : |

### cong_document_private_tag_remove ()

    void        cong_document_private_tag_remove
                                                (CongDocument *doc,
                                                 CongNodePtr x);

`doc` : |
`x` : |

### cong_document_private_node_set_attribute ()

    void        cong_document_private_node_set_attribute
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 xmlNs *ns_ptr,
                                                 const xmlChar *name,
                                                 const xmlChar *value);

TODO: Write me

`doc` : |
`node` : |
`ns_ptr` : |
`name` : |
`value` : |

### cong_document_private_node_remove_attribute ()

    void        cong_document_private_node_remove_attribute
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 xmlNs *ns_ptr,
                                                 const xmlChar *name);

TODO: Write me

`doc` : |
`node` : |
`ns_ptr` : |
`name` : |

### cong_document_private_on_selection_change ()

    void        cong_document_private_on_selection_change
                                                (CongDocument *doc);

TODO: Write me

`doc` : |

### cong_document_private_on_cursor_change ()

    void        cong_document_private_on_cursor_change
                                                (CongDocument *doc);

TODO: Write me

`doc` : |

### cong_document_private_set_dtd_ptr ()

    void        cong_document_private_set_dtd_ptr
                                                (CongDocument *doc,
                                                 xmlDtdPtr dtd_ptr);

TODO: Write me

`doc` : |
`dtd_ptr` : |

### cong_document_register_view ()

    void        cong_document_register_view     (CongDocument *doc,
                                                 CongView *view);

TODO: Write me

`doc` : |
`view` : |

### cong_document_unregister_view ()

    void        cong_document_unregister_view   (CongDocument *doc,
                                                 CongView *view);

TODO: Write me

`doc` : |
`view` : |

### cong_document_get_cursor ()

    CongCursor* cong_document_get_cursor        (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_get_selection ()

    CongSelection* cong_document_get_selection  (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_get_language_for_node ()

    PangoLanguage* cong_document_get_language_for_node
                                                (CongDocument *doc,
                                                 CongNodePtr node);

Every node within a document has an implied language, although the logic to determine this may depend on the dispspec, on attributes of the nodes, and perhaps even on user prefererences (and hence the value may change unexpectedly).

FIXME: what are the ownership/ref count semantics of this function?

`doc` : |
`node` : |
Returns : |

### cong_document_get_command_history ()

    CongCommandHistory* cong_document_get_command_history
                                                (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_document_undo ()

    void        cong_document_undo              (CongDocument *doc);

TODO: Write me

`doc` : |

### cong_document_redo ()

    void        cong_document_redo              (CongDocument *doc);

TODO: Write me

`doc` : |

### cong_document_cut_selection ()

    void        cong_document_cut_selection     (CongDocument *doc);

TODO: Write me

`doc` : |

### cong_document_copy_selection ()

    void        cong_document_copy_selection    (CongDocument *doc);

TODO: Write me

`doc` : |

### cong_document_paste_clipboard_or_selection ()

    void        cong_document_paste_clipboard_or_selection
                                                (CongDocument *doc,
                                                 GtkWidget *widget);

TODO: Write me

`doc` : |
`widget` : |

### cong_document_paste_source_at ()

    void        cong_document_paste_source_at   (CongDocument *doc,
                                                 CongLocation *insert_loc,
                                                 const gchar *source_fragment);

TODO: Write me

`doc` : |
`insert_loc` : |
`source_fragment` : |

### cong_document_paste_source_under ()

    void        cong_document_paste_source_under
                                                (CongDocument *doc,
                                                 CongNodePtr relative_to_node,
                                                 const gchar *source_fragment);

TODO: Write me

`doc` : |
`relative_to_node` : |
`source_fragment` : |

### cong_document_paste_source_before ()

    void        cong_document_paste_source_before
                                                (CongDocument *doc,
                                                 CongNodePtr relative_to_node,
                                                 const gchar *source_fragment);

TODO: Write me

`doc` : |
`relative_to_node` : |
`source_fragment` : |

### cong_document_paste_source_after ()

    void        cong_document_paste_source_after
                                                (CongDocument *doc,
                                                 CongNodePtr relative_to_node,
                                                 const gchar *source_fragment);

TODO: Write me

`doc` : |
`relative_to_node` : |
`source_fragment` : |

### cong_document_view_source ()

    void        cong_document_view_source       (CongDocument *doc);

TODO: Write me

`doc` : |

### CongDocumentRecursionCallback ()

    gboolean    (*CongDocumentRecursionCallback)
                                                (CongDocument *doc,
                                                 CongNodePtr node,
                                                 gpointer user_data,
                                                 guint recursion_level);

`doc` : |
`node` : |
`user_data` : |
`recursion_level` : |
Returns : |

### cong_document_for_each_node ()

    gboolean    cong_document_for_each_node     (CongDocument *doc,
                                                 CongDocumentRecursionCallback callback,
                                                 gpointer callback_data);

TODO: Write me

`doc` : |
`callback` : |
`callback_data` : |
Returns : |

### cong_document_for_each_child_of_node ()

    gboolean    cong_document_for_each_child_of_node
                                                (CongDocument *doc,
                                                 CongNodePtr parent,
                                                 CongDocumentRecursionCallback callback,
                                                 gpointer callback_data);

TODO: Write me

`doc` : |
`parent` : |
`callback` : |
`callback_data` : |
Returns : |

### cong_document_make_nodes_from_source_fragment ()

    CongNodePtr cong_document_make_nodes_from_source_fragment
                                                (CongDocument *doc,
                                                 const gchar *source_fragment);

TODO: Write me

`doc` : |
`source_fragment` : |
Returns : |

### gboolean ()

    typedef     gboolean                        ();

Returns : |

### cong_document_get_dtd_element ()

    xmlElementPtr cong_document_get_dtd_element (CongDocument *cong_doc,
                                                 CongNodePtr node);

Helper function to get the xmlElementPtr within the DTD for a node Currently only looks at the actual DTD, but in future might attempt to use the dispspec to infer an DTD and return that So don't store the return value; it might get deleted etc

`cong_doc` : |
`node` : |
Returns : |

### cong_document_get_valid_new_child_elements ()

    GList*      cong_document_get_valid_new_child_elements
                                                (CongDocument *doc,
                                                 CongNodePtr node);

Get the set of valid children for a node. If the document contains a DTD, this function will return the intersection of the valid children and elements in the display spec of type tag_type. If the document does not contain a dtd, the function will fallback on returning the elements in the display spec of type tag_type.

`doc` : |
`node` : | node for which to get valid children
Returns : | GList of CongDispspecElement

### cong_document_get_valid_new_previous_sibling_elements ()

    GList*      cong_document_get_valid_new_previous_sibling_elements
                                                (CongDocument *doc,
                                                 CongNodePtr node);

Get the set of valid previous siblings for a node. If the document contains a DTD, this function will return the intersection of the valid previous siblings and elements in the display spec of type tag_type. If the document does not contain a dtd, the function will fallback on returning the elements in the display spec of type tag_type.

`doc` : |
`node` : | CongNodePtr node for which to get valid previous siblings
Returns : | GList of CongDispspecElement

### cong_document_get_valid_new_next_sibling_elements ()

    GList*      cong_document_get_valid_new_next_sibling_elements
                                                (CongDocument *doc,
                                                 CongNodePtr node);

Get the set of valid next siblings for a node. If the document contains a DTD, this function will return the intersection of the valid next siblings and elements in the display spec of type tag_type. If the document does not contain a dtd, the function will fallback on returning the elements in the display spec of type tag_type.

`doc` : |
`node` : | node for which to get valid next siblings
Returns : | GList of CongDispspecElement