## CongCommand

CongCommand —

## Synopsis

    #define     DEBUG_COMMAND_LIFETIMES
    struct      CongCommand;
    #define     CONG_COMMAND                    (obj)
    #define     CONG_COMMAND_CLASS              (klass)
    #define     IS_CONG_COMMAND                 (obj)
    GType       cong_command_get_type           (void);
    CongCommand* cong_command_construct         (CongCommand *command,
                                                 CongDocument *doc,
                                                 const gchar *description,
                                                 const gchar *consolidation_id);
    CongCommand* cong_command_private_new       (CongDocument *doc,
                                                 const gchar *description,
                                                 const gchar *consolidation_id);
    CongDocument* cong_command_get_document     (CongCommand *command);
    const gchar* cong_command_get_description   (CongCommand *command);
    const gchar* cong_command_get_consolidation_id
                                                (CongCommand *command);
    void        cong_command_undo               (CongCommand *command);
    void        cong_command_redo               (CongCommand *command);
    void        cong_command_merge              (CongCommand *dst,
                                                 CongCommand *src);
    gboolean    cong_command_has_ever_been_undone
                                                (CongCommand *cmd);
    void        cong_command_add_modification   (CongCommand *cmd,
                                                 CongModification *modification);
    void        cong_command_add_node_make_orphan
                                                (CongCommand *cmd,
                                                 CongNodePtr node);
    void        cong_command_add_node_add_after (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 CongNodePtr older_sibling);
    void        cong_command_add_node_add_before
                                                (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 CongNodePtr younger_sibling);
    void        cong_command_add_node_set_parent
                                                (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 CongNodePtr adoptive_parent);
    void        cong_command_add_node_set_text  (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 const gchar *new_content);
    void        cong_command_add_node_set_attribute
                                                (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 xmlNs *ns_ptr,
                                                 const gchar *name,
                                                 const gchar *value);
    void        cong_command_add_node_remove_attribute
                                                (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 xmlNs *ns_ptr,
                                                 const gchar *name);
    void        cong_command_add_selection_change
                                                (CongCommand *cmd,
                                                 const CongLocation *new_logical_start,
                                                 const CongLocation *new_logical_end);
    void        cong_command_add_cursor_change  (CongCommand *cmd,
                                                 const CongLocation *new_location);
    void        cong_command_add_set_dtd_ptr    (CongCommand *cmd,
                                                 xmlDtdPtr dtd_ptr);
    void        cong_command_add_set_clipboard  (CongCommand *cmd,
                                                 const gchar *clipboard_source);
    void        cong_command_add_node_recursive_delete
                                                (CongCommand *cmd,
                                                 CongNodePtr node);
    void        cong_command_for_each_location  (CongCommand *cmd,
                                                 CongUpdateLocationCallback callback,
                                                 gpointer user_data);
    void        cong_command_add_delete_range   (CongCommand *cmd,
                                                 CongRange *range);
    void        cong_command_add_delete_selection
                                                (CongCommand *cmd);
    void        cong_command_add_insert_text_at_cursor
                                                (CongCommand *cmd,
                                                 const gchar *string);
    void        cong_command_add_nullify_cursor (CongCommand *cmd);
    void        cong_command_add_nullify_selection
                                                (CongCommand *cmd);
    CongNodePtr cong_command_add_xml_frag_data_nice_split2
                                                (CongCommand *cmd,
                                                 const CongLocation *loc);
    void        cong_command_add_merge_adjacent_text_nodes
                                                (CongCommand *cmd);
    void        cong_command_add_merge_adjacent_text_children_of_node
                                                (CongCommand *cmd,
                                                 CongNodePtr node);
    gboolean    cong_command_can_add_reparent_selection
                                                (CongCommand *cmd,
                                                 CongNodePtr new_parent);
    CongNodePtr cong_command_add_reparent_selection
                                                (CongCommand *cmd,
                                                 CongNodePtr node);
    CongNodePtr cong_command_add_node_split3    (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 int c0,
                                                 int c1);
    void        cong_command_add_remove_tag     (CongCommand *cmd,
                                                 CongNodePtr node);
    void        cong_command_add_set_cursor_to_first_text_descendant
                                                (CongCommand *cmd,
                                                 CongNodePtr node);
    void        cong_command_add_set_external_dtd
                                                (CongCommand *cmd,
                                                 const gchar *root_element,
                                                 const gchar *public_id,
                                                 const gchar *system_id);
    gboolean    cong_command_add_required_sub_elements
                                                (CongCommand *cmd,
                                                 CongNodePtr node);

## Object Hierarchy

      GObject
       +----CongCommand

## Description

## Details

### DEBUG_COMMAND_LIFETIMES

    #define DEBUG_COMMAND_LIFETIMES 0

### struct CongCommand

    struct CongCommand;

### CONG_COMMAND()

    #define CONG_COMMAND(obj)         G_TYPE_CHECK_INSTANCE_CAST (obj, CONG_COMMAND_TYPE, CongCommand)

`obj` : |

### CONG_COMMAND_CLASS()

    #define CONG_COMMAND_CLASS(klass) G_TYPE_CHECK_CLASS_CAST (klass, CONG_COMMAND_TYPE, CongCommandClass)

`klass` : |

### IS_CONG_COMMAND()

    #define IS_CONG_COMMAND(obj)      G_TYPE_CHECK_INSTANCE_TYPE (obj, CONG_COMMAND_TYPE)

`obj` : |

### cong_command_get_type ()

    GType       cong_command_get_type           (void);

Returns : |

### cong_command_construct ()

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

TODO: Write me

`command` : |
`doc` : |
`description` : |
`consolidation_id` : |
Returns : |

### cong_command_private_new ()

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

Should only be called by the internals of CongDocument; if you wish to create a CongCommand you should call `cong_document_begin_command()` instead.

`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 : | the new CongCommand

### cong_command_get_document ()

    CongDocument* cong_command_get_document     (CongCommand *command);

TODO: Write me

`command` : |
Returns : |

### cong_command_get_description ()

    const gchar* cong_command_get_description   (CongCommand *command);

`command` : | a command
Returns : | the human-readable description of this command

### cong_command_get_consolidation_id ()

    const gchar* cong_command_get_consolidation_id
                                                (CongCommand *command);

Gets the ID (or NULL) of the command used for consolidating multiple similar operations into a single entry in the undo/redo history

`command` : | The relevant CongCommand
Returns : | a constant string, or NULL if no merging is to occur

### cong_command_undo ()

    void        cong_command_undo               (CongCommand *command);

Undoes the command. All modifications contained within the command are undone from the document (in reverse order), the document's "is-modified" flag is set to whatever it was when the command was created.

`command` : | a command

### cong_command_redo ()

    void        cong_command_redo               (CongCommand *command);

Redoes a command that has previously been undone. Replays all the modifications on the document in order from start to finish.

`command` : |

### cong_command_merge ()

    void        cong_command_merge              (CongCommand *dst,
                                                 CongCommand *src);

Takes all of the modifications from `src` and places them on the end of `dst`. Only to be used by the internals of the undo/redo management

`dst` : | The CongCommand into which the modifications are to be added
`src` : | The CongCommand from which the modifications are to be taken

### cong_command_has_ever_been_undone ()

    gboolean    cong_command_has_ever_been_undone
                                                (CongCommand *cmd);

A function used by the command consolidation/merging system. If you undo then redo a command, further similar operations should get separate entries in the undo/redo histroy, rather than being merged.

`cmd` : |
Returns : | A gboolean, answering the question "has this command ever been undone?"

### cong_command_add_modification ()

    void        cong_command_add_modification   (CongCommand *cmd,
                                                 CongModification *modification);

TODO: Write me

`cmd` : |
`modification` : |

### cong_command_add_node_make_orphan ()

    void        cong_command_add_node_make_orphan
                                                (CongCommand *cmd,
                                                 CongNodePtr node);

TODO: Write me

`cmd` : |
`node` : |

### cong_command_add_node_add_after ()

    void        cong_command_add_node_add_after (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 CongNodePtr older_sibling);

TODO: Write me

`cmd` : |
`node` : |
`older_sibling` : |

### cong_command_add_node_add_before ()

    void        cong_command_add_node_add_before
                                                (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 CongNodePtr younger_sibling);

TODO: Write me

`cmd` : |
`node` : |
`younger_sibling` : |

### cong_command_add_node_set_parent ()

    void        cong_command_add_node_set_parent
                                                (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 CongNodePtr adoptive_parent);

TODO: Write me

`cmd` : |
`node` : |
`adoptive_parent` : |

### cong_command_add_node_set_text ()

    void        cong_command_add_node_set_text  (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 const gchar *new_content);

TODO: Write me

`cmd` : |
`node` : |
`new_content` : |

### cong_command_add_node_set_attribute ()

    void        cong_command_add_node_set_attribute
                                                (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 xmlNs *ns_ptr,
                                                 const gchar *name,
                                                 const gchar *value);

TODO: Write me

`cmd` : |
`node` : |
`ns_ptr` : |
`name` : |
`value` : |

### cong_command_add_node_remove_attribute ()

    void        cong_command_add_node_remove_attribute
                                                (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 xmlNs *ns_ptr,
                                                 const gchar *name);

TODO: Write me

`cmd` : |
`node` : |
`ns_ptr` : |
`name` : |

### cong_command_add_selection_change ()

    void        cong_command_add_selection_change
                                                (CongCommand *cmd,
                                                 const CongLocation *new_logical_start,
                                                 const CongLocation *new_logical_end);

TODO: Write me

`cmd` : |
`new_logical_start` : |
`new_logical_end` : |

### cong_command_add_cursor_change ()

    void        cong_command_add_cursor_change  (CongCommand *cmd,
                                                 const CongLocation *new_location);

TODO: Write me

`cmd` : |
`new_location` : |

### cong_command_add_set_dtd_ptr ()

    void        cong_command_add_set_dtd_ptr    (CongCommand *cmd,
                                                 xmlDtdPtr dtd_ptr);

TODO: Write me

`cmd` : |
`dtd_ptr` : |

### cong_command_add_set_clipboard ()

    void        cong_command_add_set_clipboard  (CongCommand *cmd,
                                                 const gchar *clipboard_source);

`cmd` : |
`clipboard_source` : |

### cong_command_add_node_recursive_delete ()

    void        cong_command_add_node_recursive_delete
                                                (CongCommand *cmd,
                                                 CongNodePtr node);

TODO: Write me

`cmd` : |
`node` : |

### cong_command_for_each_location ()

    void        cong_command_for_each_location  (CongCommand *cmd,
                                                 CongUpdateLocationCallback callback,
                                                 gpointer user_data);

TODO: Write me

`cmd` : |
`callback` : |
`user_data` : |

### cong_command_add_delete_range ()

    void        cong_command_add_delete_range   (CongCommand *cmd,
                                                 CongRange *range);

Utility function to add a series of modifications to the given command.

Deletes the given range within the document (can include multiple nodes). Updates cursor and selection accordingly.

`cmd` : |
`range` : | a range within the document; both start and end must have the same parent, so that proper nesting is maintained

### cong_command_add_delete_selection ()

    void        cong_command_add_delete_selection
                                                (CongCommand *cmd);

Utility function to add a series of modifications to the given command.

Deletes the current selection within the document, updating cursor and selection accordingly.

`cmd` : |

### cong_command_add_insert_text_at_cursor ()

    void        cong_command_add_insert_text_at_cursor
                                                (CongCommand *cmd,
                                                 const gchar *string);

Utility function to add a series of modifications to the given command.

Inserts the given text at the cursor, moving the cursor to the end of the inserted text.

`cmd` : |
`string` : | a UTF-8 string

### cong_command_add_nullify_cursor ()

    void        cong_command_add_nullify_cursor (CongCommand *cmd);

TODO: Write me

`cmd` : |

### cong_command_add_nullify_selection ()

    void        cong_command_add_nullify_selection
                                                (CongCommand *cmd);

TODO: Write me

`cmd` : |

### cong_command_add_xml_frag_data_nice_split2 ()

    CongNodePtr cong_command_add_xml_frag_data_nice_split2
                                                (CongCommand *cmd,
                                                 const CongLocation *loc);

TODO: Write me

`cmd` : |
`loc` : |
Returns : |

### cong_command_add_merge_adjacent_text_nodes ()

    void        cong_command_add_merge_adjacent_text_nodes
                                                (CongCommand *cmd);

Utility function to add a series of modifications to the given command.

Searches the entire document, looking for text nodes adjacent to other text nodes, merging them together.

`cmd` : |

### cong_command_add_merge_adjacent_text_children_of_node ()

    void        cong_command_add_merge_adjacent_text_children_of_node
                                                (CongCommand *cmd,
                                                 CongNodePtr node);

Utility function to add a series of modifications to the given command.

Searches direct children of the given node, looking for text nodes adjacent to other text nodes, merging them together.

`cmd` : |
`node` : |

### cong_command_can_add_reparent_selection ()

    gboolean    cong_command_can_add_reparent_selection
                                                (CongCommand *cmd,
                                                 CongNodePtr new_parent);

TODO: Write me

`cmd` : |
`new_parent` : |
Returns : |

### cong_command_add_reparent_selection ()

    CongNodePtr cong_command_add_reparent_selection
                                                (CongCommand *cmd,
                                                 CongNodePtr node);

Utility function to add a series of modifications to the given command.

Splits the selected nodes as necessary and adds as a child of the input node

`cmd` : |
`node` : |
Returns : |

### cong_command_add_node_split3 ()

    CongNodePtr cong_command_add_node_split3    (CongCommand *cmd,
                                                 CongNodePtr node,
                                                 int c0,
                                                 int c1);

Utility function to add a series of modifications to the given command.

Splits a text or comment node into 3 nodes, and returns a pointer to the middle one

`cmd` : |
`node` : |
`c0` : |
`c1` : |
Returns : | the middle node of the three newly-created nodes

### cong_command_add_remove_tag ()

    void        cong_command_add_remove_tag     (CongCommand *cmd,
                                                 CongNodePtr node);

Utility function to add a series of modifications to the given command.

Removes the given node from the tree, moving all of its children into the space it occupied.

`cmd` : |
`node` : | a node

### cong_command_add_set_cursor_to_first_text_descendant ()

    void        cong_command_add_set_cursor_to_first_text_descendant
                                                (CongCommand *cmd,
                                                 CongNodePtr node);

TODO: Write me

`cmd` : |
`node` : |

### cong_command_add_set_external_dtd ()

    void        cong_command_add_set_external_dtd
                                                (CongCommand *cmd,
                                                 const gchar *root_element,
                                                 const gchar *public_id,
                                                 const gchar *system_id);

Utility function to add a series of modifications to the given command.

Sets an external DTD on the document, or removes it if NULL is given

`cmd` : | a command
`root_element` : | the root element of the document
`public_id` : |
`system_id` : |

### cong_command_add_required_sub_elements ()

    gboolean    cong_command_add_required_sub_elements
                                                (CongCommand *cmd,
                                                 CongNodePtr node);

`cmd` : |
`node` : |
Returns : |