THE RICHTEXTBOX CONTROL 313

Methods

The first two methods of the RichTextBox control you will learn about are SaveFile and LoadFile:

SaveFile saves the contents of the control to a disk file.

LoadFile loads the control from a disk file.

SaveFile

The syntax of the SaveFile method is

RichTextBox1.SaveFile(path, filetype)

where path is the path of the file in which the current document will be saved. By default, the SaveFile method saves the document in RTF format and uses the RTF extension. You can specify a different format with the second, optional, argument, which can take on the value of one of the members of the RichTextBoxStreamType enumeration, which are described in Table 7.2.

Table 7.2: The RichTextBoxStreamType Enumeration

Format	Effect
PlainText	Stores the text on the control without any formatting
RichNoOLEObjs	Stores the text without any formatting and ignores any embedded OLE objects
RichText	Stores the formatted text
TextTextOLEObjs	Stores the text along with the embedded OLE objects
UnicodePlainText	Stores the text in Unicode format

LoadFile

Similarly, the LoadFile method loads a text or RTF file to the control. Its syntax is identical to the syntax of the SaveFile method:

RichTextBox1.LoadFile(path, filetype)

The filetype argument is optional and can have one of the values of the RichTextBoxStreamType enumeration. Saving and loading files to and from disk files are as simple as presenting a Save or Open common dialog control to the user and then calling one of the SaveFile or LoadFile methods with the filename returned by the common dialog box.

Note You can’t assign formatted text to the control at design time. The Text property is available at design time, but the text is rendered in the same format. The RTF property isn’t available at design time. To display initially some formatted text on the control, you must either load it from a file with the LoadFile method, or assign the equivalent RTF code to the RTF property at runtime, usually from within the form’s Load event.

Copyright ©2002 SYBEX, Inc., Alameda, CA

www.sybex.com

314 Chapter 7 MORE WINDOWS CONTROLS

Select, SelectAll

The Select method selects a section of the text on the control, similar to setting the SelectionStart and SelectionLength properties. The Select method accepts two arguments, which are the location of the first character to be selected and the length of the selection:

RichTextBox1.Select(start, length)

The SelectAll method accepts no arguments and selects all the text on the control.

Advanced Editing Features

The RichTextBox control provides all the text-editing features you’d expect to find in a text-editing application. You can use the arrow keys to move through the text and press Ctrl+C to copy text or Ctrl+V to paste it. To facilitate the design of advanced text-editing features, the RichTextBox control provides the AutoSelectWord property, which controls how the control selects text. If it’s True, the control selects a word at a time.

In addition to formatted text, the RichTextBox control can handle OLE objects. You can insert images in the text by pasting them with the Paste method. The Paste method doesn’t require any arguments; it simply inserts the contents of the Clipboard at the current location in the document.

The RichTextBox control encapsulates undo and redo operations at multiple levels. Each operation has a name (Typing, Deletion, and so on), and you can retrieve the name of the next operation to be undone or redone and display it on the menu. Instead of a simple Undo or Redo caption, you can change the captions of the Edit menu to something like Undo Delete or Redo Typing.

To program undo and redo operation from within your code, you must use the following properties and methods.

CanUndo, CanRedo

These two properties are Boolean values you can read to find out whether an operation can be undone or redone. If they’re False, you must disable the corresponding menu command from within your code. The following statements disable the Undo command if there’s no action to be undone at the time, where EditUndo is the name of the Undo command on the Edit menu:

If RichTextBox1.CanUndo Then

EditUndo.Enabled = True

Else

EditUndo.Enabled = False

End If

These statements appear in the menu item’s Select event handler (not in the Click event handler), because they must be executed before the menu is displayed. The Select event is triggered when a menu is opened. As a reminder, the Click event isn’t fired when you click an item. For more information on programming the events of a menu, see Chapter 5.

UndoActionName, RedoActionName

These two properties return the name of the action that can be undone or redone. The most common value of both properties is the string “typing,” which indicates that the Undo command will delete a number of characters. Another common value is the “delete” string, while some operations

Copyright ©2002 SYBEX, Inc., Alameda, CA

www.sybex.com

THE RICHTEXTBOX CONTROL 315

are named “unknown.” If you change the indentation of a paragraph on the control, this action’s name is “unknown.” It’s likely that more action names will be recognized in future versions of the control.

The following statement sets the caption of the Undo command to a string that indicates the action to be undone:

EditUndo.Text = “Undo “ & Editor.UndoActionName

Undo, Redo

These two methods undo or redo an action. The Undo method cancels the effects of the last action of the user on the control. The Redo method redoes the last action that was undone. Obviously, unless one or more actions have been undone already, the Redo method won’t have any effect.

You will see how the Undo and Redo methods, as well as the related properties, are used in an application in the section “The RTFPad Project,” later in this chapter.

Cutting and Pasting

To cut, or copy, and paste text on the RichTextBox control, you can use the same techniques as with the regular TextBox control. For example, you can replace the current selection by assigning a string to the SelectedText property. The RichTextBox, however, provides useful methods for performing these operations. The methods Copy, Cut, and Paste perform the corresponding operations. The Cut and Copy methods are straightforward and require no arguments. The Paste method accepts a single argument, which is the format of the data to be pasted. Since the data will come from the Clipboard, you can extract the format of the data in the Clipboard at the time and then call the CanPaste method to find out whether the control can handle this type of data. If so, you can then paste them on the control with the Paste method.

This technique requires quite a bit of code, because the Clipboard object doesn’t return the format of the data it holds. You must call the following method of the Clipboard object to find out whether the data is of a specific type and then call the control’s CanPaste method to find out whether it can handle the data:

If Clipboard.GetDataObject.GetDataPresent(DataFormats.Text) Then

RichTextBox.Paste(DataFormats.Text)

End If

This is a very simple case, because we know that the RichTextBox control can accept text. For a robust application, you must call the GetDataPresent method for each type of data your application should be able to handle (you may not want to allow users to paste all types of data that the control can handle).

In the RTFPad project later in this chapter, we’ll use a structured exception handler to allow users to paste anything on the control. If the control can’t handle it, the data won’t be pasted on the control. As you already know, the RichTextBox control can display images along with text. Each image takes up the entire width of the control. You can center it on the page with the usual alignment properties, but you can’t enter text to either side of the image. If you need a control with the functionality of Word, then you can either automate Word from within your VB application (see Chapter 10 for more information on programming Word’s objects) or purchase a third-party control with advanced processing features.

Copyright ©2002 SYBEX, Inc., Alameda, CA

www.sybex.com

316 Chapter 7 MORE WINDOWS CONTROLS

Searching in a RichTextBox Control

The Find method locates a string in the control’s text and is similar to the InStr() function. You can use InStr() with the control’s Text property to locate a string in the text, but the Find method is optimized for the RichTextBox control and supports a couple of options that the InStr() function doesn’t. The simplest form of the Find method is the following:

RichTextBox1.Find(string)

The string argument is the string you want to locate in the RichTextBox control. The method returns an integer value that is the location of the first instance of the string in the text. If the specified string can’t be found in the text, the value –1 is returned.

Another, equally simple syntax of the Find method allows you to specify how the control will search for the string:

RichTextBox1.Find(string, searchMode)

The searchMode argument is a member of the RichTextBoxFinds enumeration, which are shown in Table 7.3.

Table 7.3: The RichTextBoxFinds Enumeration

Value	Effect
MatchCase	Performs a case-sensitive search.
NoHighlight	The text found will not be highlighted.
None	Locates instances of the specified string even if they’re not whole words.
Reverse	The search starts at the end of the document.
WholeWord	Locate only instances of the specified string that are whole words.

Two more forms of the Find method allow you specify the range of the text in which the search will take place:

RichTextBox1.Find(string, start, searchMode)

RichTextBox1.Find(string, start, end, searchMode)

The arguments start and end are the starting and ending locations of the search (use them to search for a string within a specified range only). If you omit the end argument, the search will start at the location specified by the start argument and will extend to the end of the text.

You can combine multiples of the values of the searchMode argument with the OR operator. The default search is case-insensitive, covers the entire document, and highlights the matching text on the control. The RTFPad application’s Find command demonstrates how to use the Find method and its arguments to build a Search & Replace dialog box that performs all the types of text-searching operations you might need in a text-editing application.

Copyright ©2002 SYBEX, Inc., Alameda, CA

www.sybex.com