Comment class

Comment class

Represents a container for text of a comment. To learn more, visit the Working with Comments documentation article.

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: CommentInlineStoryCompositeNodeNode

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.
child_nodes Gets all immediate child nodes of this node.
(Inherited from CompositeNode)
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 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_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.
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 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