Microsoft Office 2000/Visual Basic Programmer's Guide

The Selection Object

When you use the Word user interface to work with a document, you typically select (highlight) text and then do something to the text, such as formatting it, typing new text, or moving it to another location. The Selection object represents the currently selected text in a Word document. The Selection object is always present in a document; if no text is selected, it represents the insertion point. Unlike the Range object, there can only be one Selection object at a time. You can use the Selection object's Type property to get information about the state of the current selection. For example, if there is no current selection, the Selection object's Type property returns wdSelectionIP. The Type property will return one of nine different values represented by the wdSelectionType enumerated constants.

You access a Selection object by using the Selection property. This property is available from the Application, Window, and Pane objects. However, since the Selection property is global, you can refer to it without referencing another object first. For example, the following sample code illustrates how you use the Selection property to get information about the currently selected text:

Sub SelectionCurrentInfo()
   Dim strMessage As String

   With Selection
      If .Characters.Count > 1 Then
         strMessage = "The Selection object in '" & ActiveDocument.Name _
            & "' contains " & .Characters.Count & " characters, " _
            & .Words.Count & " words, " & .Sentences.Count _
            & " sentences, and " & .Paragraphs.Count _
            & " paragraphs."
         MsgBox strMessage
      End If
   End With
End Sub

The SelectionCurrentInfo procedure is available in the modRangeSimpleCode module in WordSamples.doc file in the ODETools\V9\Samples\OPG\Samples\CH05 subfolder on the Office 2000 Developer CD-ROM.

The Selection Object vs. the Range Object

In many ways, the Selection object is like a Range object. The Selection object represents an arbitrary portion of a document. It has properties that represent characters, words, sentences, paragraphs, and other objects in a Word document. The main difference is that when you use the Range object, it's not necessary to first select the text. In addition, there can only be one Selection object at a time, but the number of Range objects you can create is unlimited.

The Selection object and the Range object have many common methods and properties, and it is easy to return a Range object from a Selection object or to create a Selection object from a Range object. However, most things you can do with a Selection object, you can do even faster with a Range object. There are two main reasons for this:

• The Range object typically requires fewer lines of code to accomplish a task.
  
  
• Manipulating a Range object does not incur the overhead associated with Word having to move or change the selection "highlight" in the active document.

In addition, you can do much more with a Range object than you can with a Selection object:

• You can manipulate a Range object without changing what the user has selected in the document. Practically speaking, you could save the original selection by using a Range object variable, manipulate the Selection object programmatically, and then use the saved Range object's Select method to display the original selection, but there is rarely a good reason to show the user that the selection is changing. Some WordBasic developers relied on changing the selection to indicate to the user that the code is still running (and the machine has not locked up). But this is not the right way to convey information to a user. An operation that takes a long time to execute should signal its progress by using a progress meter or by posting status messages to the status bar.
  
  
• You can maintain multiple Range objects in your code, and, where necessary, store those objects in a custom Collection object. You cannot do these two things by using only the Selection object.

For more information about differences between how the Selection and Range objects work, see "The Find and Replacement Objects" later in this chapter.

When it comes to manipulating text, the Selection and Range objects have many methods and properties in common — for example, all the InsertName methods and the Text property discussed in "Working with Text in a Range Object" earlier in this chapter. However, the Selection object has a unique set of methods for manipulating text. These are the TypeText, TypeParagraph, and TypeBackspace methods. You use these methods to enter or remove text and insert paragraph marks in a Selection object. In order to get the results you expect, there are a few things you need to understand about the TypeName methods.

With the exception of the InsertParagraph and InsertFile methods, which remove selected text, the InsertName methods let you work with a selection without deleting existing text. In contrast, the TypeName methods may delete existing text, depending on the value of the Options object's ReplaceSelection property.

When the ReplaceSelection property is True, using any of the TypeName methods results in the currently selected text being replaced. When the ReplaceSelection property is False, the TypeText and TypeParagraph methods behave just like the InsertBefore method: The text or paragraph mark is inserted at the beginning of the current selection. When the ReplaceSelection property is False, the TypeBackspace method behaves the same as the Collapse method of a Range or Selection object when the wdCollapseStart constant is specified in the Direction argument. The Collapse method collapses a range or selection so that its starting point and ending point are the same.

Knowing when to use a Range object, when to use a Selection object, and when to use both objects together gives you many powerful and flexible options when you are working with the objects in a Word document. This section has given examples showing how to use both objects individually and together. For another example showing how these objects work well together, see the SearchAndReturnExample procedure in "The Find and Replacement Objects" later in this chapter. In addition, there are several procedures in the WordSamples.doc sample file in the ODETools\V9\Samples\OPG\Samples\CH05 subfolder on the Office 2000 Developer CD-ROM that illustrate a wide variety of circumstances where these objects work well together.