Creating a Document

To create a new document, 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 (this process is the same as if you'd clicked the File tab on the Ribbon and then clicked the New button to open a blank document). So, you need to 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:

• Creating a document based on Normal.dotm The following statement creates a new document based on the Normal.dotm global template:

• Documents.Add

• Creating a document based on a template The following statement creates a new document based on the template named Company Report.dotm stored in the network folder designated \serverpublic emplates:

• Documents.Add Template:= "\serverpublic	emplatesCompany Report.dotm"

Creating a Template

The following statements declare a new object variable of the Document class named myTemplate, create a new template based on the template named Fancy.dotx, and assign it to myTemplate:

Dim myTemplate As Document
 
Set myTemplate = Documents.Add(Template:="c:MyTemplatesfancy.dotx", _
    NewTemplate:=True, Visible:=True)

In this example, the file path (c:MyTemplatesand so on) to the template is specified because this template is not located in one of the default template folders. The result is a new .dotx file, based on the Fancy.dotx template.

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 SaveAs2 method. The syntax is as follows:

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

With Word 2010, the traditional SaveAs command was replaced by the SaveAs2 command, which is identical except for the addition of a CompatibilityMode argument. Documents can be saved six different ways with respect to their compatibility with earlier versions of Word. Based on how you set the CompatibilityMode argument, Word saves your document in one of these ways:

• 0 is the default if you don't specify any of the other CompatibilityMode options in this list. The document will be saved using whatever compatibility mode is currently used by this document.
• wdCurrent is a compatibility mode equivalent to the latest version of Microsoft Word.
• wdWord2003 is a mode that's compatible with Word 2003. Any features new in Word 2013 are disabled.
• wdWord2007 is essentially the same as 2003 mode, but features compatible with the 2007 version of Word are enabled.
• wdWord2010 is the mode where the Word 2010 features are enabled.
• WdWord2013 enables all Word features.

The traditional SaveAs command, though deprecated, will still work, but the Editor has a tendency to automatically replace it with SaveAs2. Spooky, but no real harm done.

In the syntax, 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 Docn.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).

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.

As an example of how to use one of these constants, the following statement saves the active document as a filtered HTML file under the name Example.html in the current folder:

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

After you run this example code, use Windows Explorer to locate this new Example.html file and click 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 your machine opens .html files). Or, take a look at it in Notepad if you want to see the full horror of HTML markup.

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. (Generally, you'll want to avoid listing documents on this Recent list, thus 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 these 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.doc in the folder C: emp:

ActiveDocument.SaveAs2 _
    "C:	empBeehives.doc"

Saving a Document That Has Already Been Saved

After a document has been first saved, you can save it in the future under the same name by using the Save method. For a Document object, the Save method takes no arguments (all the document's current formats are saved unchanged). For example, the following statement saves the document named Guns01.doc:

Documents("Guns01.doc").Save

Saving All Open Documents

To save all open documents, use the Save method with the Documents collection. The syntax is as follows:

expression.Save(NoPrompt, OriginalFormat)

Here, expression is an expression that returns a Documents collection. Often, you'll use the Documents collection itself.

NoPrompt is an optional Variant argument that you can set to True to make Word save all open documents containing unsaved changes and any attached templates containing unsaved changes without prompting the user. The default setting is False, which causes Word to prompt the user whether to save each document and template. Even if you set NoPrompt to True, Word will prompt the user to save changes to Normal.dotm if the Prompt Before Saving Normal Template check box is selected in the Save section of the Advanced tab of the Options dialog box.

OriginalFormat is an optional Variant argument that you can set to wdOriginalDocumentFormat to save the documents in their original formats, wdWordDocument to force each document to be saved as a Word document, or wdPromptUserX to prompt the user about which format to use.

For example, the following statement saves all open documents and templates without prompting the user:

Documents.Save NoPrompt:=True

Checking Whether a Document Contains Unsaved Changes

To find out whether a document contains unsaved changes, check its Saved property. Saved is a read/write Boolean property that returns False if the document contains unsaved changes and True if it does not. A new document contains no unsaved changes, even though it has never been saved.

Checking the Type of Selection

Word recognizes nine different kinds 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 no selection (just the insertion point), a block of ordinary text, or a special type of text like a table or a graphic.

Depending on the current selection, you may not be able to take certain actions in your procedure, and you may not want to take other actions. You would not, 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

Checking the Story Type of the Selection

Beyond the type of selection, you'll sometimes need to find out which “story” the selection is in. There are 17 stories, representing the 17 different types of content in a document—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 perhaps more descriptive terms) to mean a distinct kind of content. Put another way, a story is the context within which a selection resides.

Checking the story can help you steer clear of doing something weird, such as trying to modify a header or footer story in a way that is only possible inside the 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 proper, and the items within it. But alternative “stories” are things like footnotes, frames, headers, and footers—as you can see in Table 20.4, which lists the wdStoryType constants and the stories to which they correspond.

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.

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

Getting Other Information About the Current Selection

To work effectively with a 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 examples of useful information available in the Information property.

Here's an example showing how to use the Information property:

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 fun exceptions to a Microsoft rule. You should, therefore, remember that if the expected or typical syntax results in an error message from the Editor, you need to try a different syntax and see if that works. Or look for a code sample that displays in action the object you're working with.

To see the complete list of all members, open the Object Browser (F2) and scroll down in the Classes list until you see wdInformation. Double-click it, and its members will be listed in the Members of “WdInformation” list on the right.

Inserting Text at a Selection

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 merely inserts a text string into the document if the selection is collapsed (if it's just the blinking insertion 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 the TypeText method. 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.)

Inserting a Paragraph in a Selection

You can insert paragraphs using the following methods:

• To insert a paragraph at the current selection, use the InsertParagraph method.
• To insert a paragraph before the current selection, use the InsertParagraphBefore method.
• To insert a paragraph after the current selection, use the InsertParagraphAfter method.

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

Applying a Style

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

Selection.Style = "Heading 3"

View the styles available to 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. Also, depending on what styles are defined for the current document, you might see an error message “Item with specified name does not exist.” This means the style you're trying to describe isn't in the list of styles. To fix this, look at the styles and, for example, change Bold to whatever's listed for bold, such as Strong:

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

Extending an Existing Selection

To extend a selection programmatically (through programming rather than by the user), 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.

Collapsing an Existing Selection

When you've finished working with a selection larger than a blinking cursor insertion point, you often want to deselect it. In other words, you may want to force the selection into a collapsed state (just the blinking cursor) when your 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

Defining a Named Range

To create a Range object, you use a Set statement and either the Range method (with the Document object) or the Range property for a different object—for example, the Selection object, the Paragraphs collection, or a Paragraph object classify Range as a property. You might be excused for thinking that a range is always a property of something, but it's how you view the timing. Before a range exists, you can think of it as an action that creates the range, so it's a method. However, after a range exists, it's clearly a property, like an object's color. As I say, object classification is a work in progress. And likely always will be.

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 code changes 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.

Redefining a Range

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.

Using the Duplicate Property to Store or Copy Formatting

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

Making Sure Hyperlinks Require Ctrl+Clicking

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.

Turning Off Overtype

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 right any existing text 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

Setting a Default File Path

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"

Turning Off Track Changes

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 up 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 illustrates this technique.

This 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