Lisa Wollin
Microsoft Corporation
April 2001
Applies to:
Microsoft® Word 2002
Summary: This article describes the new features built into the Microsoft Word 10.0 Object Library that make creating custom solutions for document collaboration easier. (9 printed pages)
Contents
Introduction
Introduction
The Microsoft® Word 10.0 Object Library includes several new objects, properties, and methods for document collaboration. This article shows you how to take advantage of these new members to:
- Change the display of revisions and comments
- Accept and reject revisions
- Start and end a collaborative review cycle
Revisions and Comments
Revisions and comments in Microsoft Word 2002 can now be displayed either inline (as they were in Word 2000), or, when in Print Layout view or Web Layout view, as balloons in the document's margin. New properties and methods provide the ability to change the way in which revisions and comments are displayed. You also have greater control over filtering multiple reviewers' revisions and comments, accepting or rejecting comments, and displaying revisions and comments.
Changing the Display Mode of Revisions and Comments
In Word 2000, revisions were displayed inline with the text they revised, and comments were displayed in ToolTips or in the comments pane. In Word 2002, when in Print Layout view or Web Layout view, you can also display revisions and comments in balloons in the document's margin.
By default, Word 2002 displays revisions and comments as balloons in a document's margin. However, by setting the RevisionsMode property of the View object to wdInLineRevisions, you can display revisions and comments as Word 2000 displayed them regardless of whether your document is displayed in Normal view or Print Layout view.
When revisions and comments are displayed in balloons, you can use the RevisionsBalloonWidth property to set the width of the balloons, as well as use the RevisionsBalloonSide property to change the margin in which they are displayed. The RevisionsBalloonShowConnectingLines property allows you to specify whether Word displays lines that connect the balloons to the changed text. The following example uses these properties to change how Word displays balloons in your document.
Sub ShowTrackedChanges(ByRef objView As View, _
ByVal wdMode As WdRevisionsMode, _
Optional ByVal sngWidth As Single = 72, _
Optional ByVal wdSide As _
WdRevisionsBalloonMargin = wdRightMargin, _
Optional ByVal blnLines As Boolean = True)
With objView
.RevisionsMode = wdMode
If wdMode = wdBalloonRevisions Then
.RevisionsBalloonWidth = sngWidth
.RevisionsBalloonSide = wdSide
.RevisionsBalloonShowConnectingLines = blnLines
End If
End With
End Sub
This routine allows you to display revisions and comments as they are displayed in Word 2000 or as balloons in the margin. If you specify wdInLineRevisions for the wdMode argument, you don't need to specify any of the other arguments. However, if you specify wdBalloonRevisions for the wdMode argument, you can use the other arguments to specify how Word displays balloons in your documents. The following example demonstrates how to use this routine to change Word's display of revisions and comments to inline revisions.
Sub CallShowTrackedChanges()
Call ShowTrackedChanges(objView:=ActiveWindow.View, _
wdMode:=wdInLineRevisions)
End Sub
Displaying Revisions and Comments
There are several new ways to display (or hide) revisions and comments. For example, if a document has numerous changes made by several people, all of those changes can clutter up a user's screen. The new RevisionsView property of the View object provides the ability to view your document without all the clutter of revision marks. The two WdRevisionsView modes allow you to display your document in its final state with revisions applied or in its original state before any revisions were made.
Several other new properties provide the ability to show or hide revisions, comments, and formatting changes. The ShowRevisionsAndComments property shows or hides all revisions and comments made to a document, the ShowInsertionAndDeletions shows or hides all revisions made to a document, the ShowComments property shows or hides all comments inserted into the document, and the ShowFormatChanges property shows or hides all revisions for formatting changes that have been made to a document. The following example uses these four properties to change the display of revisions and comments in a document.
Sub ShowMarkup(ByRef objView As View, _
Optional ByVal blnShowMarkup As Boolean = True, _
Optional ByVal blnShowRevisions As Boolean = True, _
Optional ByVal blnShowComments As Boolean = True, _
Optional ByVal blnShowFormatChanges As Boolean = True)
With objView
.ShowRevisionsAndComments = blnShowMarkup
.ShowInsertionsAndDeletions = blnShowRevisions
.ShowComments = blnShowComments
.ShowFormatChanges = blnShowFormatChanges
End With
End Sub
The following example uses the above routine to show insertions and deletions but hide comments and formatting changes made to a document.
Sub CallShowMarkup()
Call ShowMarkup(objView:=ActiveWindow.View, blnShowMarkup:=True, _
blnShowRevisions:=True, blnShowComments:=False, _
blnShowFormatChanges:=False)
End Sub
One thing to note is that when you use the ShowFormatChanges property to hide formatting changes, it doesn't hide the actual formatting of the text; instead it hides the balloon that marks the formatting change.
Working with the Reviewer Object and the Reviewers Collection
The new Reviewer object and the Reviewers collection provide a means of filtering the display of specific reviewers' revisions and comments. A Reviewer object is an individual reviewer in the Reviewers collection, and the Reviewers collection contains all reviewers. One thing to note is that the Reviewers collection is not just a collection of the reviewers' names for a specific document. Instead, the collection contains all of the reviewers' names for all documents that have been opened in the current session of Word.
You cannot programmatically add or delete reviewers' names from the collection. Therefore, although five reviewers might have collaborated on a specific document, the Count property of the Reviewers collection might return a larger number. However, you can remove all of the Reviewer objects in the Reviewers collection by quitting and starting Word.
You use the Visible property of the Reviewer object to show or hide all of a specific reviewer's revisions and/or comments. The following example hides the revisions and comments of all reviewers in the Reviewers collection and displays only the specified reviewer's revisions and comments.
Sub DisplayCommentsAndRevisions(ByRef objView As View, _
ByVal strReviewer As String, _
Optional ByVal blnShowRevisions As Boolean = True, _
Optional ByVal blnShowComments As Boolean = True, _
Optional ByVal blnShowFormatChanges As Boolean = True)
Dim objReviewer As Reviewer
On Error GoTo ErrorHandler
With objView
'Display all comments and revisions.
.ShowInsertionsAndDeletions = blnShowRevisions
.ShowComments = blnShowComments
.ShowFormatChanges = blnShowFormatChanges
'Hide all reviewers.
For Each objReviewer In .Reviewers
objReviewer.Visible = False
Next objReviewer
'Show only revisions and comments of the specified reviewer.
.Reviewers(strReviewer).Visible = True
End With
Exit_Sub:
Exit Function
ErrorHandler:
Select Case Err.Number
Case Else
MsgBox Err.Number & vbTab & Err.Description
End Select
GoTo Exit_Sub
End Function
The following routine calls the above routine to display revisions and comments and hide formatting changes made by Jeff Price.
Sub CallDisplayCommentsAndRevisions()
Call DisplayCommentsAndRevisions(objView:=ActiveWindow.View, _
strReviewer:="Jeff Price", blnShowFormatChanges:=False)
End Sub
Accepting and Rejecting Revisions and Comments
In the past, there was no easy way for Word users to work with subsets of revisions and comments in documents. In Word 2002, however, you can create solutions that delete subsets of comments, as well as accept or reject only revisions that are displayed on the screen.
In previous versions of Word you had to use the Delete method of a Comment object to delete a comment programmatically. To delete all comments, you had to loop through the Comments collection and delete each comment individually. In Word 2002, you can now use the DeleteAllComments method of the Document object to delete all of the comments in a document by using just one line of code. If you want to delete only the comments of one or more reviewers, you can specify which reviewers' comments to delete by first setting the ShowComments property to True, and then hiding reviewers' names whose comments you don't want deleted by setting the Visible property of the Reviewer object that corresponds to the particular reviewer's name to False.
When you have a reviewer's revisions displayed on the screen, you can accept or reject only the revisions that are displayed on the screen by using the AcceptAllRevisionsShown and RejectAllRevisionsShown methods of the Document object. The following example uses the AcceptAllRevisionsShown method to incorporate all changes made by the specified reviewer.
Sub AcceptAllRevisionsByReviewer(ByRef objView As View, _
ByVal strReviewer As String, _
Optional ByVal blnShowInsertions As Boolean = True, _
Optional ByVal blnShowFormatChanges As Boolean = True)
Dim objReviewer As Reviewer
With objView
'Hide all reviewers.
For Each objReviewer In .Reviewers
objReviewer.Visible = False
Next objReviewer
'Show specified reviewer.
.Reviewers(Index:=strReviewer).Visible = True
'Display or hide comments and revisions for specified reviewer.
.ShowInsertionsAndDeletions = blnShowInsertions
.ShowFormatChanges = blnShowFormatChanges
End With
'Accept only revisions displayed on the screen.
ThisDocument.AcceptAllRevisionsShown
End Sub
The following routine uses the above routine to accept all insertions, deletions, and formatting changes made by the Jeff Price.
Sub CallAcceptAllRevisionsByReviewer()
Call AcceptAllRevisionsByReviewer(objView:=ActiveWindow.View, _
strReviewer:="Jeff Price")
End Sub
Review Cycles
There are two options in Word 2002 to assist you in creating custom solutions for document collaboration. One involves storing documents on a Microsoft SharePoint™ Portal Server. The other option involves e-mailing documents directly to reviewers and comparing and merging the reviewed documents, which is discussed in greater detail below.
Note When a reviewer returns a marked-up document, the copy of the e-mail reply that ends up in the Sent Items folder in Microsoft Outlook® can lose the file extension if the filename contains an embedded period. For example a document named Review.fs.doc would become Review.fs. The file itself is intact, but the user will have to manually rename the file to include the file extension.
Starting a Review Cycle
You use the SendForReview method of the Document object to start a collaborative review. Once the SendForReview method is called, Word e-mails the document to the specified recipients and places it in a review cycle. The following example uses the SendForReview method to start a document review cycle with the specified document. The SendForReview method takes four optional arguments. The example below passes these arguments in as variables.
Sub StartDocumentReviewCycle(ByRef objDocument As Document, _
ByVal strRecipients As String, _
Optional ByVal strSubject As String = _
"Please review the attached document", _
Optional ByVal blnShowMessageBeforeSending As Boolean = False, _
Optional ByVal blnIncludeDocAsAttachment As Boolean = True)
objDocument.SendForReview Recipients:=strRecipients, _
Subject:=strSubject, _
ShowMessage:=blnShowMessageBeforeSending, _
IncludeAttachment:=blnIncludeDocAsAttachment
End Sub
Pointing to the Send To command from the File menu and then clicking on Mail Recipient (for Review) is comparable to calling the SendForReview method. The following example calls the above routine and sends the active document to Jeff Price for review.
Sub CallStartDocumentReviewCycle()
Call StartDocumentReviewCycle(objDocument:=ActiveDocument, _
strRecipients:="Jeff Price")
End Sub
Returning a Reviewed Document
After a recipient receives and reviews a document, the ReplyWithChanges method allows the reviewer to return the document to the author with the recipient's changes. To give your users access to this method, you could create a menu or toolbar item connected to the below routine. The following example uses the ReplyWithChanges method to return the specified document to the author with the reviewers' changes.
Sub ReturnDocumentToAuthor(ByRef objDocument As Document, _
Optional ByVal blnShowMessage As Boolean = False)
objDocument.ReplyWithChanges ShowMessage:=blnShowMessage
End Sub
Although there is nothing in the document that visibly marks that the document is in a review cycle, when the author receives the document back from the reviewers, Word knows that the document was in a review cycle and displays a message asking whether to merge the review cycle document with the original document.
You can give your users access to the ReplyWithChange method by creating a menu or toolbar item and calling the above routine, as shown in the following example.
Sub CallReturnDocumentToAuthor()
Call ReturnDocumentToAuthor(objDocument:=ActiveDocument, _
blnShowMessage:=True)
End Sub
When a document is in a collaborative review cycle, Word adds the Reply with Changes button to the Reviewing toolbar and adds the Original Sender command to the Send To submenu (File menu).
Ending a Review Cycle
After a review cycle is finished and all reviewers have reviewed a document, use the EndReview method to remove a document from a review cycle, as shown in the following example.
Sub EndDocumentReviewCycle(ByRef objDocument As Document) objDocument.EndReview End Sub
The following example calls the above routine and ends the review for the active document.
Sub CallEndDocumentReviewCycle() Call EndDocumentReviewCycle(objDocument:=ActiveDocument) End Sub
Conclusion
The new objects, properties, and methods of the Word 10.0 Object Library shown in this article allow you to change the display of revisions and comments, accept and reject revisions, and start and end a collaborative review cycle. This gives you greater flexibility in creating the document collaboration solutions your organization needs.
