|
C H A P T E R 7 |
|
Microsoft Office 97/Visual Basic Programmer's Guide |
Properties of the Application object also provide access
to objects lower in the object hierarchy, such as the Windows
collection (representing all currently open windows) and the Documents
collection (representing all currently open documents). You use
properties, which are sometimes called accessors,
to move down through the object hierarchy from the toplevel
Application object to the lower levels (Document,
Window, Selection, and so forth). You can use either
of following examples to open MyDoc.doc.
Application.Documents.Open FileName:="C:\DOCS\MYDOC.DOC"
Documents.Open FileName:="C:\DOCS\MYDOC.DOC"
Because the Documents property is global,
the Application property is optional. Global properties
and methods don't need the Application object qualifier.
To view the list of global properties and methods in the Object
Browser, click <globals> in the Classes
box. The global items are listed in the Members of box.
Note The
Options object includes a number of properties that control the
global behavior of Word. Many of the properties for the Options
object correspond to items in the Options dialog box (Tools menu).
Use the Options property of the Application object to return the
Options object. The following example sets three applicationwide
options (because the Options property is global, the Application
property isn't needed in this example).
With Application.Options
.AllowDragAndDrop = True
.ConfirmConversions = False
.MeasurementUnit = wdPoints
End With
- You can define and use multiple
Range objects, whereas you can only have one Selection
object per document window.
- Manipulating Range
objects doesn't change the selected text.
- Manipulating
Range objects is faster than working with the selection.
Using the Range Method to Return a Range Object
You use the Range method to create a Range object
in the specified document. The Range method (which is available
from the Document object) returns a Range object
located in the main story, with a given starting point and ending
point. The following example creates a Range object that's
assigned to the variable myRange.
Set myRange = ActiveDocument.Range(Start:=0, End:=10)
In the preceding example, myRange
represents the first 10 characters in the active document. You
can see that the Range object has been created when you
apply a property or method to the Range object stored in
the myRange
variable. The following example applies bold formatting to the
first 10 characters in the active document.
Set myRange = ActiveDocument.Range(Start:=0, End:=10)
myRange.Bold = True
When you need to refer to a Range object multiple times,
you can use the Set statement to set a variable equal to
the Range object. However, if you need to perform only
a single action on a Range object, there's no need to store
the object in a variable. You can achieve the same results by
using just one instruction that identifies the range and changes
the Bold property, as in the following example.
ActiveDocument.Range(Start:=0, End:=10).Bold = True
Like a bookmark, a range can span a group of characters or mark
a location in a document. In the following example, the starting
and ending points of the Range object are the same, and
the range doesn't include any text. The example inserts text at
the beginning of the active document.
ActiveDocument.Range(Start:=0, End:=0).InsertBefore Text:="Hello "
You can define the beginning and ending points of a range by using
the character position numbers as shown in the preceding example,
or by using the Start and End properties with the
Selection, Bookmark, or Range object. The
following example creates a Range object that refers to
the third and fourth sentences in the active document.
Set myDoc = ActiveDocument
Set myRange = myDoc.Range(Start:=myDoc.Sentences(3).Start, _
End:=myDoc.Sentences(4).End)
Tip A
Range object doesn't have a visual representation in a
document. You can, however, use the Select method to select
a Range object to ensure that the Range object refers
to the correct range of text. The Range object in the following
example refers to the first three paragraphs in the active document.
After this macro has been run, the selection indicates the range
of text that was contained in the variable aRange.
Set aRange = ActiveDocument.Range(Start:=0, _
End:=ActiveDocument.Paragraphs(3).Range.End)
aRange.Select
Using the Range Property to Return a Range
Object
The Range property is available from multiple objects —
for instance, Paragraph, Bookmark, Endnote,
and Cell — and is used to return a Range
object. The following example returns a Range object that
refers to the first paragraph in the active document.
Set myRange = ActiveDocument.Paragraphs(1).Range
After you've created a reference to a Range object, you
can use any of its properties or methods to modify the range.
The following example copies the first paragraph in the active
document.
Set myRange = ActiveDocument.Paragraphs(1).Range
myRange.Copy
This following example copies the first row in table one in the
active document.
ActiveDocument.Tables(1).Rows(1).Range.Copy
The following example displays the text marked by the first bookmark
in the active document. The Range property is available
from the Bookmark object.
MsgBox ActiveDocument.Bookmarks(1).Range.Text
If you need to apply numerous properties or methods to the same
Range object, you can use the With…End With
statement. The following example formats the text in the first
paragraph in the active document.
Set myRange = ActiveDocument.Paragraphs(1).Range
With myRange
.Bold = True
.ParagraphFormat.Alignment = wdAlignParagraphCenter
.Font.Name = "Arial"
End With
For additional examples of returning Range objects, see
"Range Property" in Help.
Modifying a Portion of a Document
Visual Basic includes objects you can use to modify the following
types of document elements: characters, words, sentences, paragraphs,
and sections. The following table includes the properties that
correspond to these document elements and the objects they return.
|
This expression |
Returns this object |
|
Words(index)
|
Range
|
|
Characters(index)
|
Range
|
|
Sentences(index)
|
Range
|
|
Paragraphs(index)
|
Paragraph
|
|
Sections(index)
|
Section
|
When you use these properties without an index, a collection with
the same name is returned — for example, the Paragraphs
property returns the Paragraphs collection. However, if
you identify an item within a collection by index, the object
in the second column of the preceding table is returned —
for example, Words(1)
returns a Range object. You can use any of the range properties
or methods to modify a Range object, as in the following
example, which copies the first word in the selection to the Clipboard.
Selection.Words(1).Copy
The items in the Paragraphs and Sections collections
are Paragraph and Section objects, respectively,
rather than Range objects. However, the Range property
(which returns a Range object) is available from both the
Paragraph and Section objects. The following example
copies the first paragraph in the active document to the Clipboard.
ActiveDocument.Paragraphs(1).Range.Copy
All the document element properties in the preceding table are
available from the Document, Selection, and Range
objects, as shown in the following three examples.
This example sets the case of the first word in the active document.
ActiveDocument.Words(1).Case = wdUpperCase
This example sets the bottom margin of the first selected section
to 0.5 inch.
Selection.Sections(1).PageSetup.BottomMargin = InchesToPoints(0.5)
This example doublespaces the text in the active document
(the Content property returns a Range object that
represents the main document story).
ActiveDocument.Content.ParagraphFormat.Space2
Modifying a Group of Document Elements
To modify a range of text that consists of a group of document
elements (characters, words, sentences, paragraphs, or sections),
you can create a Range object that includes the document
elements. Using the Start and End properties with
a Range object, you can create a new Range object
that refers to a group of document elements. The following example
creates a Range object (myRange)
that refers to the first three words in the active document and
then changes the font for these words to Arial.
Set Doc = ActiveDocument
Set myRange = Doc.Range(Start:=Doc.Words(1).Start, End:=Doc.Words(3).End)
myRange.Font.Name = "Arial"
The following example creates a Range object beginning
at the start of the second paragraph and ending after the fourth
paragraph.
Set myDoc = ActiveDocument
Set myRange = myDoc.Range(Start:=myDoc.Paragraphs(2).Range.Start, _
End:=myDoc.Paragraphs(4).Range.End)
The following example creates a Range object (aRange)
beginning at the start of the second paragraph and ending after
the third paragraph. The ParagraphFormat property is used
to access paragraph formatting properties such as SpaceBefore
and SpaceAfter.
Set Doc = ActiveDocument
Set aRange = Doc.Range(Start:=Doc.Paragraphs(2).Range.Start, _
End:=Doc.Paragraphs(3).Range.End)
With aRange.ParagraphFormat
.Space1
.SpaceAfter = 6
.SpaceBefore = 6
End With
Returning or Setting the Text in a Range
Use the Text property to return or set the contents of
a Range object. The following example returns the first
word in the active document.
strText = ActiveDocument.Words(1).Text
The following example changes the first word in the active document
to "Hello."
ActiveDocument.Words(1).Text = "Hello"
Use the InsertAfter or InsertBefore method to insert
text before or after a range. The following example inserts text
at the beginning of the second paragraph in the active document.
ActiveDocument.Paragraphs(2).Range.InsertBefore Text:="In the beginning "
After you use either the InsertAfter or InsertBefore
method, the range expands to include the new text. You can, however,
collapse the range to its beginning or ending point by using the
Collapse method. The following example inserts the word
"Hello" before the existing text and then collapses
the range to its beginning (before the word "Hello").
With ActiveDocument.Paragraphs(2).Range
.InsertBefore Text:="Hello "
.Collapse Direction:=wdCollapseStart
End With
Formatting the Text in a Range
Use the Font property to get to characterformatting
properties and methods, and use the ParagraphFormat property
to get to paragraphformatting properties and methods. The
following example sets character and paragraph formatting for
the text in the first paragraph in the active document.
With ActiveDocument.Paragraphs(1).Range.Font
.Name = "Times New Roman"
.Size = 14
.AllCaps = True
End With
With ActiveDocument.Paragraphs(1).Range.ParagraphFormat
.LeftIndent = InchesToPoints(0.5)
.Space1
End With
Redefining a Range Object
Use the SetRange method to redefine an existing Range
object. The following example defines myRange
as the current selection. The SetRange method redefines
myRange so
that it refers to the current selection plus the next 10 characters.
Set myRange = Selection.Range
myRange.SetRange Start:=myRange.Start, End:=myRange.End + 10
For additional information about and examples of redefining a
Range object, see "SetRange Method" in Help.
You can also redefine a Range object by changing the values
of the Start and End properties, or by using the
MoveStart or MoveEnd methods. The following example
redefines myRange
so that it refers to the current selection plus the next 10 characters.
Set myRange = Selection.Range
myRange.End = myRange.End + 10
The following example uses the MoveEnd method to extend
myRange to
include the next paragraph.
Set myRange = ActiveDocument.Paragraphs(2)
myRange.MoveEnd Unit:=wdParagraph, Count:=1
Looping Through a Range of Paragraphs
There are several different ways to loop through the paragraphs
in a range. This section includes examples of using the For
Each...Next statement and the Next property and method
to loop through a range of paragraphs. You can use these same
techniques to loop through characters, words, or sentences in
a range.
Using the For Each...Next Statement
The recommended way to loop through the paragraphs in a range
is to use the For Each...Next statement, which is also
the recommended way to loop on the elements in a collection. The
following example loops through the first five paragraphs in the
active document, adding text before each paragraph.
Set myDoc = ActiveDocument
Set myRange = myDoc.Range(Start:=myDoc.Paragraphs(1).Range.Start, _
End:=myDoc.Paragraphs(5).Range.End)
For Each para In myRange.Paragraphs
para.Range.InsertBefore "Question:" & vbTab
Next para
Suppose that you want to modify this code to loop through a range
of paragraphs that a user selected. You can use the Selection
property to refer to the paragraphs in the selection. The following
example loops through the paragraphs in the selection, removing
bold formatting.
For Each para In Selection.Paragraphs
para.Range.Bold = False
Next para
Using the Next Property or Method
You can also use the Next property and method to loop through
a range of paragraphs. The following example shows how you can
loop through a range of words and increase the size of each word
by 1 point. The example also uses the Next method to redefine
myRange to
represent the next word.
Set myRange = ActiveDocument.Words(1)
For i = 1 To 5
myRange.Font.Size = myRange.Font.Size + i
Set myRange = myRange.Next(Unit:=wdWord, Count:=1)
Next i
The following example loops through a range of paragraphs and
changes the range's alignment from centered to left aligned. The
example also uses the Next property to redefine myRange
to represent the next paragraph.
Set myRange = ActiveDocument.Paragraphs(1).Range
For i = 1 To 5
If myRange.Paragraphs(1).Alignment = wdAlignParagraphCenter Then
myRange.Paragraphs(1).Alignment = wdAlignParagraphLeft
End If
Set myRange = myRange.Paragraphs(1).Next.Range
Next i
Assigning Ranges
There are several ways to assign an existing Range object
to a variable. In the following examples, the variables Range1
and Range2
refer to Range objects. The instructions in the examples
assign the first and second words in the active document to the
variables Range1
and Range2,
respectively.
Set Range1 = ActiveDocument.Words(1)
Set Range2 = ActiveDocument.Words(2)
Setting a Range Object Variable Equal to Another Range Object
Variable
The following example creates the variable Range2
and assigns it to the same range as Range1.
Set Range2 = Range1
You now have two variables that represent the same range. When
you manipulate the starting point, the ending point, or the text
of Range2,
your changes affect Range1
as well, and vice versa.
The following example assigns the value of the default property
of Range1
(the Text property) to the default property of Range2.
The code in this example is equivalent to Range2.Text
= Range1.Text, which doesn't change what the Range
objects actually represent; the only thing that's changed is the
contents (text) of Range2.
Range2 = Range1
The two ranges (Range2
and Range1)
have the same contents as one another, but they may point to different
locations in the document, or even to different documents.
Using the Duplicate Property
The following example creates a new, duplicated Range object,
Range2, which
has the same starting point, ending point, and text as Range1.
Set Range2 = Range1.Duplicate
If you change the starting or ending point of Range1,
this change doesn't affect Range2,
and vice versa. However, because these two ranges point to the
same location in the document, changing the text in one range
changes the text in the other range as well.
Working with Stories
A story is a document area that contains a range of text distinct
from other areas of text in that document. For example, if a document
includes body text, footnotes, and headers, it contains a main
text story, a footnotes story, and a headers story. There are
11 different types of stories you can have in a document, corresponding
to the following WdStoryType constants: wdCommentsStory,
wdEndnotesStory, wdEvenPagesFooterStory, wdEvenPagesHeaderStory,
wdFirstPageFooterStory, wdFirstPageHeaderStory,
wdFootnotesStory, wdMainTextStory, wdPrimaryFooterStory,
wdPrimaryHeaderStory, and wdTextFrameStory.
Use the StoryType property to return the story type for
the specified range, selection, or bookmark. The following example
closes the footnote pane in the active window if the selection
is contained in the footnote story.
ActiveWindow.View.Type = wdNormalView
If Selection.StoryType = wdFootnotesStory Then ActiveWindow.ActivePane.Close
The StoryRanges collection contains the first story range
for each story type available in a document. Use the NextStoryRange
method to return subsequent stories. The following example searches
each story in the active document for the text "Microsoft
Word." The example also applies italic formatting to any
instances of this text that it finds.
For Each myStoryRange In ActiveDocument.StoryRanges
myStoryRange.Find.Execute FindText:="Microsoft Word", Forward:=True
While myStoryRange.Find.Found
myStoryRange.Italic = True
myStoryRange.Find.Execute FindText:="Microsoft Word", _
Forward:=True, Format:=True
Wend
While Not (myStoryRange.NextStoryRange Is Nothing)
Set myStoryRange = myStoryRange.NextStoryRange
myStoryRange.Find.Execute FindText:="Microsoft Word", Forward:=True
While myStoryRange.Find.Found
myStoryRange.Italic = True
myStoryRange.Find.Execute FindText:="Microsoft Word", _
Forward:=True, Format:=True
Wend
Wend
Next myStoryRange