Comment class
Comment class
Represents a container for text of a comment. To learn more, visit the Working with Comments documentation article.
Remarks
A comment is an annotation which is anchored to a region of text or to a position in text. A comment can contain an arbitrary amount of block-level content.
If a Comment object occurs on its own, the comment is anchored to the position of the Comment object.
To anchor a comment to a region of text three objects are required: Comment, CommentRangeStart and CommentRangeEnd. All three objects need to share the same Comment.id value.
Comment is an inline-level node and can only be a child of Paragraph.
Comment can contain Paragraph and Table child nodes.
Inheritance: Comment → InlineStory → CompositeNode → Node
Constructors
| Name | Description |
|---|---|
| Comment(doc) | Initializes a new instance of the Comment class. |
| Comment(doc, author, initial, date_time) | Initializes a new instance of the Comment class. |
Properties
| Name | Description |
|---|---|
| ancestor | Returns the parent Comment object. Returns None for top-level comments. |
| author | Returns or sets the author name for a comment. |
| count | Gets the number of immediate children of this node. (Inherited from CompositeNode) |
| custom_node_id | Specifies custom node identifier. (Inherited from Node) |
| date_time | Gets the date and time that the comment was made. |
| document | Gets the document to which this node belongs. (Inherited from Node) |
| done | Gets or sets flag indicating that the comment has been marked done. |
| first_child | Gets the first child of the node. (Inherited from CompositeNode) |
| first_paragraph | Gets the first paragraph in the story. (Inherited from InlineStory) |
| font | Provides access to the font formatting of the anchor character of this object. (Inherited from InlineStory) |
| has_child_nodes | Returns True if this node has any child nodes.(Inherited from CompositeNode) |
| id | Gets or sets the comment identifier. |
| initial | Returns or sets the initials of the user associated with a specific comment. |
| is_composite | Returns True if this node can contain other nodes.(Inherited from Node) |
| is_delete_revision | Returns true if this object was deleted in Microsoft Word while change tracking was enabled. (Inherited from InlineStory) |
| is_insert_revision | Returns true if this object was inserted in Microsoft Word while change tracking was enabled. (Inherited from InlineStory) |
| is_move_from_revision | Returns True if this object was moved (deleted) in Microsoft Word while change tracking was enabled.(Inherited from InlineStory) |
| is_move_to_revision | Returns True if this object was moved (inserted) in Microsoft Word while change tracking was enabled.(Inherited from InlineStory) |
| last_child | Gets the last child of the node. (Inherited from CompositeNode) |
| last_paragraph | Gets the last paragraph in the story. (Inherited from InlineStory) |
| next_sibling | Gets the node immediately following this node. (Inherited from Node) |
| node_type | Returns NodeType.COMMENT. |
| paragraphs | Gets a collection of paragraphs that are immediate children of the story. (Inherited from InlineStory) |
| parent_id | Gets or sets the parent comment ID. A value of -1 means the comment has no parent. |
| parent_node | Gets the immediate parent of this node. (Inherited from Node) |
| parent_paragraph | Retrieves the parent Paragraph of this node. (Inherited from InlineStory) |
| previous_sibling | Gets the node immediately preceding this node. (Inherited from Node) |
| range | Returns a Range object that represents the portion of a document that is contained in this node. (Inherited from Node) |
| replies | Returns a collection of Comment objects that are immediate children of the specified comment. |
| story_type | Returns StoryType.COMMENTS. |
| tables | Gets a collection of tables that are immediate children of the story. (Inherited from InlineStory) |
Methods
| Name | Description |
|---|---|
| accept(visitor) | Accepts a visitor. |
| accept_end(visitor) | Accepts a visitor for visiting the end of the comment. |
| accept_start(visitor) | Accepts a visitor for visiting the start of the comment. |
| add_reply(author, initial, date_time, text) | Adds a reply to this comment. |
| append_child(new_child) | Adds the specified node to the end of the list of child nodes for this node. (Inherited from CompositeNode) |
| clone(is_clone_children) | Creates a duplicate of the node. (Inherited from Node) |
| ensure_minimum() | If the last child is not a paragraph, creates and appends one empty paragraph. (Inherited from InlineStory) |
| get_ancestor(ancestor_type) | Gets the first ancestor of the specified object type. (Inherited from Node) |
| get_ancestor(ancestor_type) | Gets the first ancestor of the specified NodeType. (Inherited from Node) |
| get_child(node_type, index, is_deep) | Returns an Nth child node that matches the specified type. (Inherited from CompositeNode) |
| get_child_nodes(node_type, is_deep) | Returns a live collection of child nodes that match the specified type. (Inherited from CompositeNode) |
| get_text() | Gets the text of this node and of all its children. (Inherited from Node) |
| index_of(child) | Returns the index of the specified child node in the child node array. (Inherited from CompositeNode) |
| insert_after(new_child, ref_child) | Inserts the specified node immediately after the specified reference node. (Inherited from CompositeNode) |
| insert_before(new_child, ref_child) | Inserts the specified node immediately before the specified reference node. (Inherited from CompositeNode) |
| next_pre_order(root_node) | Gets next node according to the pre-order tree traversal algorithm. (Inherited from Node) |
| node_type_to_string(node_type) | A utility method that converts a node type enum value into a user friendly string. (Inherited from Node) |
| prepend_child(new_child) | Adds the specified node to the beginning of the list of child nodes for this node. (Inherited from CompositeNode) |
| previous_pre_order(root_node) | Gets the previous node according to the pre-order tree traversal algorithm. (Inherited from Node) |
| remove() | Removes itself from the parent. (Inherited from Node) |
| remove_all_children() | Removes all the child nodes of the current node. (Inherited from CompositeNode) |
| remove_all_replies() | Removes all replies to this comment. |
| remove_child(old_child) | Removes the specified child node. (Inherited from CompositeNode) |
| remove_reply(reply) | Removes the specified reply to this comment. |
| remove_smart_tags() | Removes all SmartTag descendant nodes of the current node. (Inherited from CompositeNode) |
| select_nodes(xpath) | Selects a list of nodes matching the XPath expression. (Inherited from CompositeNode) |
| select_single_node(xpath) | Selects the first Node that matches the XPath expression. (Inherited from CompositeNode) |
| set_text(text) | This is a convenience method that allows to easily set text of the comment. |
| to_string(save_format) | Exports the content of the node into a string in the specified format. (Inherited from Node) |
| to_string(save_options) | Exports the content of the node into a string using the specified save options. (Inherited from Node) |
Examples
Shows how to add a comment to a document, and then reply to it.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
comment = aw.Comment(doc, "John Doe", "J.D.", datetime.now())
comment.set_text("My comment.")
# Place the comment at a node in the document's body.
# This comment will show up at the location of its paragraph,
# outside the right-side margin of the page, and with a dotted line connecting it to its paragraph.
builder.current_paragraph.append_child(comment)
# Add a reply, which will show up under its parent comment.
comment.add_reply("Joe Bloggs", "J.B.", datetime.now(), "New reply")
# Comments and replies are both Comment nodes.
self.assertEqual(2, doc.get_child_nodes(aw.NodeType.COMMENT, True).count)
# Comments that do not reply to other comments are "top-level". They have no ancestor comments.
self.assertIsNone(comment.ancestor)
# Replies have an ancestor top-level comment.
self.assertEqual(comment, comment.replies[0].ancestor)
doc.save(ARTIFACTS_DIR + "Comment.add_comment_with_reply.docx")
Shows how to add a comment to a paragraph.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
builder.write("Hello world!")
comment = aw.Comment(doc, "John Doe", "JD", date.today())
builder.current_paragraph.append_child(comment)
builder.move_to(comment.append_child(aw.Paragraph(doc)))
builder.write("Comment text.")
self.assertEqual(date.today(), comment.date_time.date())
# In Microsoft Word, we can right-click this comment in the document body to edit it, or reply to it.
doc.save(ARTIFACTS_DIR + "InlineStory.add_comment.docx")
See Also
- module aspose.words
- class InlineStory
- class CommentRangeStart
- class CommentRangeEnd