To create a new file, use the Add method of the Documents collection. The syntax is as follows:

expression.Add Template, NewTemplate, DocumentType, Visible

Here, expression is a required expression that returns a Documents collection. Typically, you'll want to use the Documents collection itself (Documents.Add).

Template is an optional Variant argument that specifies the template on which to base the new document. If you omit Template, Word uses the Normal template (as if you'd clicked the File tab on the Ribbon, then clicked the New button to open a blank document). So you need specify a Template argument only when you want to base the new document on a template other than the default Normal.dotm.

NewTemplate is an optional Variant argument that you can set to True to create a template file (.dotx) rather than a document. NewTemplate is set to False by default, so you can safely omit this argument unless you're creating a template.

DocumentType is an optional Variant argument that you can use to specify the type of document to create: wdNewBlankDocument (the default), wdNewEmailMessage, wdNewFrameset (for a frameset), or wdNewWebPage.

Visible is an optional Variant argument that you can set to False to have the document created in a window that isn't visible. The default setting is True, making the document window visible.

There are two ways to create a document:

The following statements declare a new object variable named myTemplate of the Document class, create a new template based on the template named Fancy.dotx (stored in one of the default template folders), and assign it to myTemplate:

Dim myTemplate As Document

Set myTemplate = Documents.Add(Template:="c:program files (x86)Microsoft OfficeOffice141033Quickstylesfancy.dotx", _
    NewTemplate:=True, Visible:=True)

In this example, the path to the template is specified because this template is not in one of the default template folders. The result is a new .dotx file, based on the Fancy.dotx template.

Just as when a user is saving a newly created document via the keyboard and mouse, when executing VBA code you must specify a filename and path the first time you save a document. After that, you can save it under the same name or specify a different name or format. This is the difference between the Save and Save As options.

Saving a File for the First Time or as a Different File

To save a file for the first time, or to save a file under a different name or in a different format, use the SaveAs method. The syntax is as follows:

expression.SaveAs(FileName, FileFormat, LockComments, Password, AddToRecentFiles,
WritePassword, ReadOnlyRecommended, EmbedTrueTypeFonts, SaveNativePictureFormat,
SaveFormsData, SaveAsAOCELetter, Encoding, InsertLineBreaks, AllowSubstitutions,
LineEnding, AddBiDiMarks, CompatibilityMode

Here, expression is an expression that returns a Document object. For example, you might use the ActiveDocument object or an object in the Documents collection.

FileName is an optional Variant argument that specifies the name for the document. If you omit FileName, VBA uses the current folder and the default filename of Docn.docx( or .docm) or a document and Dotn.dotx (or .dotm) for a template, where n is the next available number (for example, Doc5.docx for a macro-free document or Dot2.dotm for a macro-enabled template).

Avoid Accidentally Overwriting a File

When saving a document, you should first check whether a document with this name and location already exists. If it does, VBA overwrites it without warning, causing data loss.

FileFormat is an optional Variant argument that specifies the format in which to save the document. Table 20.1 lists the wdSaveFormat constants for specifying commonly used formats.

Table 20.1. WdSaveFormat constants

Constant	Saves Document As
wdFormatDocument	A Word document
wdFormatDOSText	A DOS text file
wdFormatDOSTextLineBreaks	A DOS text file with layout
wdFormatEncodedText	A text file with encoding
wdFormatFilteredHTML	A filtered HTML file (Word 2003 and XP only)
wdFormatFlatXML	An unindexed XML document
wdFormatFlatXMLMacroEnabled	An unindexed XML document with macro capability
wdFormatFlatXMLTemplate	An unindexed XML template
wdFormatFlatXMLTemplateMacroEnabled	An unindexed XML template with macro capability
wdFormatHTML	An HTML file
wdFormatOpenDocumentText	An XML file format developed by Sun Microsystems
wdFormatRTF	A Rich Text Format file
wdFormatTemplate	A Word template
wdFormatText	A text file (plain ASCII)
wdFormatTextLineBreaks	A text file with line breaks
wdFormatUnicodeText	A text file with Unicode characters
wdFormatWebArchive	A web archive file
wdFormatXML	An XML file (Word 2003 only)
wdFormatDocument97	Microsoft Word 97 document format
wdFormatDocumentDefault	Word 2010 default document file (.docx)
wdFormatPDF	PDF format
wdFormatTemplate97	Word 97 template format
wdFormatXMLDocument	XML document format
wdFormatXMLDocumentMacroEnabled	XML document format with macros enabled
wdFormatXMLTemplate	XML template format
wdFormatXMLTemplateMacroEnabled	XML template format with macros enabled
wdFormatXPS	XPS format

A Quick Way to See Objects and Their Constants

If you're writing code and you want to quickly see a list of constants, such as the WdSaveFormat constants in Table 20.1, just press F2 to open the Object Browser in the editor. Then type wdsaveformat in the Object Browser's search field and press Enter. You'll see the complete list of constants as shown in the illustration.

The following statement saves the active document as a filtered HTML file under the name Example.html in the current folder:

ActiveDocument.SaveAs FileName:="Example.html", _
    FileFormat:=wdFormatFilteredHTML

After you run this example code, use Windows Explorer to locate this new Example.html file and click on it. It will open in Internet Explorer as if it were a web page, because it's stored using the HTML format (if Internet Explorer is the default application in which .html files are opened). Or take a look at it in Notepad if you want to see the full horror of HTML markup.

Save Documents Using File Converters

In addition to the wdSaveFormat constants described in Table 20.1, you can save documents in other formats for which you have file converters installed by specifying the appropriate value for the SaveFormat property of the FileConverter object—for example, ActiveDocument.SaveAs FileFormat:=FileConverters(15).SaveFormat. See the FileConverters property entry in the VBA Help file for more information.

AddToRecentFiles is an optional Variant argument that you can set to True to have Word add the document to the list of recently used files displayed when you click the File tab on the Ribbon and then click Recent. (Often, when experimenting with documents in procedures, you'll want to avoid listing them on the Most Recently Used list, leaving the user's previous list of recent files undisturbed.)

To protect the document as you save it, you can use four different protection features:

• LockComments is an optional Variant argument that you can set to True to lock the document so that reviewers can enter comments but can't change the text of the document.

• Password is an optional Variant argument that you can use to set a password required before opening the document.

• WritePassword is an optional Variant argument that you can use to set a password required before saving changes to the document.

• ReadOnlyRecommended is an optional Variant argument that you can set to True to have Word recommend that the user open the document as read-only.

Finally, there are the following optional arguments you'll use infrequently, if ever:

• EmbedTrueTypeFonts is an optional Variant argument that you can set to True to save TrueType fonts with the document. (This is a good idea only if you're distributing the document to someone you know doesn't have the TrueType fonts installed to view the document correctly.)

• SaveNativePictureFormat is an optional Variant argument that you can set to True to have graphics imported from another platform saved as Windows graphics.

• SaveFormsData is an optional Variant argument that you can set to True to save the data entered in a form as a data record (as opposed to saving the whole form, including its static text).

• SaveAsAOCELetter is an optional Variant argument that you can set to True to save the document as an AOCE (Apple Open Collaboration Environment) letter (a mailing format for routing documents).

• Encoding is an optional Variant argument for using a different code page than the system code page. For example, you might need to save a document using a Cyrillic code page.

• InsertLineBreaks is an optional Variant argument that you can set to True when saving a document as a text file to make Word insert a line break at the end of each line of text.

• AllowSubstitutions is an optional Variant argument that you can set to True when saving a document as a text file to make Word substitute some symbol characters with similar text. For example, Word substitutes (TM) for a trademark symbol (™).

• LineEnding is an optional Variant argument that you can use when saving a document as a text file to control how Word marks line breaks and paragraph breaks.

• AddBiDiMarks is an optional Variant argument that you can set to True to make Word add control characters to the file to maintain bidirectional layout.

Usually, when saving a file for the first time, you'll need to specify only its name and path; if you want to save it in a format other than a Word document, specify that too. The following statement saves the active document under the name Beehives.docx in the folder \serverProductsField:

ActiveDocument.SaveAs _
    "\serverProductsFieldBeehives.docx"

Documents("Recipe01.docx").Save

expression.Save(NoPrompt, OriginalFormat)

Documents.Save NoPrompt:=True

To open a document, use the Open method with the appropriate Document object. The syntax for the Open method is as follows:

expression.Open FileName, ConfirmConversions, ReadOnly,
AddToRecentFiles, PasswordDocument, PasswordTemplate,
Revert, WritePasswordDocument,  WritePasswordTemplate,
Format, Encoding, Visible, OpenConflictDocument,
OpenAndRepair, DocumentDirection, NoEncodingDialog, XMLTransform

The arguments are as follows:

The following statement opens the document Times.docx found in the C:My Documents folder:

Documents.Open "C:My DocumentsTimes.docx"

The following statement opens the file notes.docm in the folder C: emp as read-only and adds it to the list of most recently used files (the list you see when you click the File tab on the Ribbon, then click Recent):

Documents.Open "C:	emp
otes.docm", ReadOnly:=True, _
    AddToRecentFiles:=True

To close a document, use the Close method with the application Document object. The syntax is as follows:

expression.Close(SaveChanges, OriginalFormat, RouteDocument)

Here, expression is a required expression that returns a Document object or a Documents collection. Typically you use the ActiveDocument object or, to close all documents, the Documents collection object.

SaveChanges is an optional Variant argument you can use to specify how to handle unsaved changes. Use wdDoNotSaveChanges to discard changes, wdPromptToSaveChanges to have Word prompt the user to save changes, or wdSaveChanges to save changes without prompting.

OriginalFormat is an optional Variant argument you can use to specify the save format for the document. Use wdOriginalDocumentFormat to have Word use the original document format, wdPromptUser to have Word prompt the user to choose a format, or wdWordDocument to use the Word document format.

RouteDocument is an optional Variant argument that you can set to True to route a document that has a routing slip attached.

For example, the following statement closes the active document without saving changes:

ActiveDocument.Close SaveChanges:=wdDoNotSaveChanges

The following statement closes all open documents (but not the Word application itself) and saves changes automatically:

Documents.Close SaveChanges:=wdSaveChanges

To change the template attached to a document, set the AttachedTemplate property of the Document object you want to affect to the path and name of the appropriate template. For example, the following statement attaches the template named SalesMarket02.dotm to the active document. In this example, the template is assumed to be stored in one of the Word templates folders, so the path need not be specified:

ActiveDocument.AttachedTemplate = "SalesMarket02.dotm"

To print a document, use the PrintOut method for the appropriate Document object. The syntax for the PrintOut method is as follows:

expression.PrintOut(Background, Append, Range, OutputFileName, From, To, Item,
Copies, Pages, PageType, PrintToFile, Collate, FileName, ActivePrinterMacGX,
ManualDuplexPrint, PrintZoomColumn, PrintZoomRow, PrintZoomPaperWidth,
PrintZoomPaperHeight)

These are the components of the PrintOut method:

For example, the following statement prints three collated copies of the active document in the background:

ActiveDocument.PrintOut Background:=True, Copies:=3, Collate:=True

The following statement prints pages 2 through 5 of the active document:

ActiveDocument.PrintOut Range:=wdPrintFromTo, From:=2, To:=5

The following statement prints the active document at two virtual pages per sheet of paper:

ActiveDocument.PrintOut PrintZoomColumn:=2, PrintZoomRow:=1

The ActiveDocument object returns a Document object that represents the current document you're working with—whichever document has the focus in the Word window. The ActiveDocument object behaves like a Document object, but watch out for two possible problems when working with it.

You may have problems locating information about the ActiveDocument object in the Help system. It's actually a property of the Application object, so its status as an actual object is somewhat iffy. Object taxonomy is an evolving clerical system and, as you see, remains imperfect.

To find the ActiveDocument object in the Help system, MSDN system, or VBA Editor Object Browser, you need to first locate the Application object, then look at its properties (or members). Just remember, ActiveDocument is found only under the Application object. It's a clerical error. It's as if you were looking for California in a geography book's index, but the index is wacky because you find most states listed under their own names (Hawaii is under the Hs, for example). But for some reason, California is not listed in the Cs. You're puzzled. It's a big, important state. Then you stumble upon the solution: In this bizarre index, California is only found under the entry for United States.

The second oddity about the ActiveDocument "property" is that it can be evanescent. The first problem is that if there's no document open in Word, there's no ActiveDocument object, and any code that tries to work with the ActiveDocument object returns an error. You should remember to check the Count property of the Documents collection to make sure there's a document open (Count will be at least 1) before attempting to use the ActiveDocument in your code. Here's an example that tests to see if there is an open document:

If Documents.Count = 0 Then
    If MsgBox("No document is open." & vbCr & vbCr & _
        "Do you want to create a new blank document?", _
        vbYesNo + vbExclamation, "No Document Is Open") = vbYes Then

Documents.Add
    Else
        End
    End If
End If

The second problem relating to this evanescence is that a different document may be active than your code assumes is active. This problem tends to occur when a procedure starts with the active document and then creates a new document to work in; the new document becomes the active document, and from this point on, confusion may result.

If you know the name of the document that should be active, you can check to see if the name of the active document matches it, to verify that you'll be working with the right document.

If there's any doubt about which document you're working with, declare a Document object variable and employ that object variable in your code rather than the ActiveDocument object.

For example, the following statements declare a Document object and assign the ActiveDocument object to it so that subsequent code can work with the Document object:

Dim myDocument As Document
Set myDocument = ActiveDocument
With myDocument
    'actions here
End With

Or if you know the name of the document you want to work with:

Dim myDocument As Document
Set myDocument = ActiveDocument
If myDocument.Name = "CorrectFile.docx" Then
    'actions here
End If

Word recognizes nine different types of selections. When you're working in the active document, you'll often need to check what kind of selection is active so that you know whether you're dealing with a block of selected text, no selection (insertion point), or a special type of selection such as a table or a graphic.

Depending on the current selection, you may not be able to take certain actions in a procedure, and you may not want to take others. You can't, for example, insert a table row into an ordinary text paragraph.

Table 20.3 lists the types of selections that Word differentiates.

To find out what type of selection you currently have, look at the Type property of the Selection object. The following statements check that the current selection is merely an insertion point before inserting a text literal. The text will not be inserted if the user has dragged to select, for example, some characters, a word, or a paragraph:

If Selection.Type = wdSelectionIP Then
    Selection.TypeText "This is inserted."
End If

Beyond the type of selection, you'll sometimes need to find out which "story" the selection is in—the main text story, the comments story, the primary header story, and so on. Microsoft uses the word story instead of zone, type, or other terms to mean a distinct type of content.

Checking the story can help you avoid problems, such as trying to perform actions in a header or footer that Word supports only in a main text story.

The story is the zone of the document within which the current selection is located. So, most of the time the story is the main text story (wdMainTextStory). That's the document and the items within it. But alternative "stories" are things like footnotes, frames, headers, and footers—as you can see in Table 20.4.

You may notice another whimsical, enigmatic feature of Table 20.4. It starts the enumeration value with 1. Compare that to Table 20.3 which starts with 0. Inconsistencies like this make programming more challenging.

Table 20.4 lists the wdStoryType constants and the stories to which they correspond.

Here's a code example that displays a message box if the selection isn't in the main text of a document:

If Selection.StoryType <> wdMainTextStory Then
    MsgBox "This range is not in the main text."
End If

To work effectively with the current selection, you'll often need to know what it contains and where it's positioned. To find out, use the Information property to learn the details you need. Table 20.5 lists the information available in the Information property.

For example:

If Selection.Information(wdCapsLock) = True Then
    MsgBox "The caps lock is ON."
End If

Sharp-eyed readers will notice a capricious inconsistency in this code. In the other code examples in this section, no parentheses were used around a constant, and the operator (= or <> or whatever) is placed between the property and the constant, as shown in this example:

Selection.Type = wdSelectionIP

But with the Information property, you do use parentheses, and you move the operator to the right of the constant:

Selection.Information(wdCapsLock) =

This syntax and punctuation irregularity is yet another of those exceptions to the rule. You should therefore remember that if the usual syntax produces an error message from the editor, try the other (parenthetical) version.

You can insert text at the selection by using the TypeText method of the Selection object, insert text before the selection by using the InsertBefore method, or insert text after the selection by using the InsertAfter method.

The TypeText method inserts text if the selection is collapsed (merely the blinking cursor with nothing actually selected). But if something is selected, such as a word or phrase, that selection is replaced by the string when you execute TypeText. However, the InsertBefore and InsertAfter methods do not replace a selection. They merely insert the new string.

The syntax is as follows:

Selection.TypeText string
Selection.InsertAfter string
Selection.InsertBefore string

Here, string is a required String expression containing the text you want to insert in double quotation marks, as in this example:

Selection.TypeText "Please come to the meeting next Friday at 9:00 A.M."
Selection.InsertBefore "Dr. "
Selection.InsertAfter vbCr & Address

When you use the InsertAfter or the InsertBefore method, VBA extends the selection to include the text you inserted. (You can see selected text, cells, or other items in a document because Word changes the background from the default white to the document frame color.) When you use the TypeText method, the result is a collapsed selection—whether you are replacing a selection or a collapsed selection. (Recall that a collapsed selection means nothing is selected—merely the blinking insertion point.)

You can insert paragraphs:

You can also have VBA type a paragraph by using the Selection.TypeParagraph command.

To apply a style to a paragraph, set the Style property of the Paragraph object:

Selection.Style = "Heading 3"

View the styles in the current document by pressing Ctrl+S, or click the Home tab on the Ribbon.

Similarly, you can apply a character style to the current selection or (as in the following example) to a specific range of words or characters. This example changes the fifth word in the second paragraph of the current document to boldface:

ActiveDocument.Paragraphs(2).Range.Words(5).Style = "Bold"

Note that a character style must always be applied to a range rather than directly to a paragraph.

To extend a selection, use the EndOf method for a Range or Selection object. The syntax for the EndOf method is as follows:

expression.EndOf(Unit, Extend)

Here, expression is a required expression that returns a Range or Selection object, such as an object in the Characters, Words, Sentences, or Paragraphs collection. Unit is an optional Variant specifying the unit of movement (see Table 20.6).

Extend is an optional Variant specifying whether to move or extend the selection or range. wdMove moves the selection or range and is the default setting; wdExtend extends the selection or range.

For example, the following statement extends the current selection to the end of the paragraph:

Selection.EndOf Unit:=wdParagraph, Extend:=wdExtend

The following statement moves the selection to the end of the paragraph:

Selection.EndOf Unit:=wdParagraph, Extend:=wdMove

The following statement selects from the current selection to the end of the current Word story:

Selection.EndOf Unit:=wdStory, Extend:=wdExtend

To select the whole active document, use ActiveDocument.Content.Select. This command has the same effect as pressing Ctrl+A when working interactively.

When you've finished working with a selection larger than an insertion point, you often want to deselect it. In other words, you may want to have the selection in a collapsed state (just the blinking cursor) when the procedure ends. (If you don't do this and the user just starts typing, whatever is selected will be replaced by the user's typing.)

The easiest way to do so is to use the Collapse method of the Selection object to collapse the selection to its start or its end:

Selection.Collapse Direction:=wdCollapseStart
Selection.Collapse Direction:=wdCollapseEnd

Alternatively, you can reduce the selection to just one point by setting the selection's end selection equal to its start (collapsing the selection to its start) or by setting the selection's start equal to its end (collapsing the selection to its end):

Selection.End = Selection.Start
Selection.Start = Selection.End

To create a Range object, you use a Set statement and either the Range method on a Document object or the Range property for an object—for example, the Selection object, the Paragraphs collection, or a Paragraph object. The syntax for using the Range method is as follows:

Set RangeName = Document.Range(Start, End)

Here, RangeName is the name you are assigning to the range, and Start and End are optional arguments specifying the starting and ending points of the range.

The syntax for using the Range property on an object is as follows:

Set RangeName = object.Range

For example, the following statement uses the Range property of the Paragraphs collection to define a range named FirstPara that consists of the first paragraph of the active document. This statement doesn't use Start and End arguments because the starting point and ending point of the paragraph are clearly understood:

Set FirstPara = ActiveDocument.Paragraphs(1).Range

The following statements change to uppercase the first three words at the start of a document:

Dim InitialCaps As Range
Set InitialCaps = ActiveDocument.Range _
(Start:=ActiveDocument.Words(1).Start, _
    End:=ActiveDocument.Words(3).End)
InitialCaps.Case = wdUpperCase

The first statement defines a Range object named InitialCaps. The second statement assigns InitialCaps to a range in the active document, from the beginning of the first word to the end of the third word. The third statement changes the case of the InitialCaps Range object to uppercase.

Because InitialCaps is now defined as a Range object for the duration of the procedure that declares it, you can return to InitialCaps and manipulate it later in the procedure if you want to.

To redefine a range to make it refer to another part of a document, use the SetRange method. The syntax is as follows:

expression.SetRange(Start, End)

Here, expression is a required expression that returns a Range or Selection object, and Start and End are optional arguments specifying the starting and ending points of the range.

For example, the following statement redefines the range named InitialCaps so it now refers to the first two characters of the document:

InitialCaps.SetRange Start:=0, End:=2

You can also redefine a range by reusing the Set method, creating the range again from scratch.

You can use the Duplicate property to store or copy a range so that you can apply it to another range. For example, the following statements declare two ranges, Range1 and Range2; store the duplicate of the current selection's range in Range1; assign to Range2 the Range of the first bookmark in the active document; and then apply to Range2 the contents of Range1:

Dim Range1 As Range, Range2 As Range
Set Range1 = Selection.Range.Duplicate
Set Range2 = ActiveDocument.Bookmarks(1).Range

Hyperlinks in Word documents have proved a mixed blessing—especially since Microsoft's changes to the way Word handles hyperlinks have left users unsure whether to just click or to Ctrl+click the hyperlink to follow it. You can set the CtrlClickHyperlinkToOpen property of the Options object to True to ensure that hyperlinks require Ctrl+clicking:

Options.CtrlClickHyperlinkToOpen = True

Setting this option to False means you can trigger links by merely clicking them—no Ctrl key required.

To make sure your procedures behave as expected, you may need to check that Word is using Insert mode rather than Overtype mode. (In Insert mode, Word inserts the characters you type at the insertion point, moving any text to the right of the characters over, to make room. In Overtype mode, each character you type replaces the character to the right of the insertion point.)

Overtype mode is controlled by the Overtype property of the Options object. When OverType is True, Overtype mode is on; when Overtype is False, Insert mode is on. The following statements store the user's current Overtype setting in a Boolean variable named blnOvertypeOn, set Overtype to False, perform its actions, and then restore the user's Overtype setting:

Dim blnOvertypeOn As Boolean
blnOvertypeOn = Options.Overtype
Options.Overtype = False   'write more code here to perform actions
Options.Overtype = blnOvertypeOn

When configuring Word on a computer, you may need to make sure that its default file paths are set to the correct folders. You can do so by working with the DefaultFilePath property of the Options object. The syntax is as follows:

expression.DefaultFilePath(Path)

Here, expression is a required expression that returns an Options object. Often, it's easiest to use the Options object itself. Path is one of the self-explanatory enumerated constants shown in the following list:

For example, the following statements set the user templates path and the workgroup templates path:

Options.DefaultFilePath(wdUserTemplatesPath) = _
"c:users
ichardappdata
oamingmicrosoft	emplates"
Options.DefaultFilePath(wdWorkgroupTemplatesPath) = _
"\serverusers	emplates"

Before running a procedure that adds, deletes, or formats text, you may need to turn off the Track Changes feature so that the changes the procedure makes are not marked in the text. If the user had Track Changes on, you should turn it back on at the end of the procedure so that changes the user makes are tracked again. Remember that it's usually a good practice when changing options to first store the user's current setting in a variable, carry out your procedure's task, and then restore the user's original setting.

The following example saves the user's setting for the TrackRevisions option in the ActiveDocument object in a Boolean variable named blnTrackChangesOn, sets TrackRevisions to False, performs its actions, and then restores the user's TrackRevisions setting:

Dim blnTrackChangesOn As Boolean
blnTrackChangesOn = ActiveDocument.TrackRevisions
ActiveDocument.TrackRevisions = False
' write more code here to perform actions
ActiveDocument.TrackRevisions = blnTrackChangesOn