The first two methods of the RichTextBox control you will learn about are Save File and LoadFile:
- SaveFile saves the contents of the control to a disk flle.
- LoadFile loads the control from a disk file.
The syntax of the SaveFile method is as follows:
RichTextBox1.SaveFile(filename, filetype)
The filename argument is the full path name of the disk file where the contents of the control will be saved, and filetype determines how the control’s contents will be saved. The filetype argument, which is optional, can have one of the two values shown in Table 9.2.
Similarly, the LoadFile method loads a text file or an RTF file to the control. Its syntax is identical to the syntax of the SaveFile method:
RichTextBox1.LoadFile(filename, filetype)
The file type argument is optional. Saving and loading files to and from disk files are as simple as presenting a File Save or File 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.
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 text. To facilitate the design of advanced text editing features, the RichTextBox control provides the Span and UpTo methods. Both of these interesting methods operate similarly, and their syntax is nearly identical.
- Span selects text in a RichTextBoxcontrol based on a set of specified characters.
- UpTo moves the pointer up to, but not including, the first character that’s a member of the specified character set. .
Many text editors provide special keystrokes that either let the user select an entire word or sentence or move the pointer to the end of a word or a sentence. By using the Span and UpTo methods, you can add the exact same capabilities to your application. Use the Span method to specify the characters that signal the end of the selection; use the UpTo method to specify the characters that identify where the pointer will move.
When you call the Span method, the RichTextBox control starts searching from the current position for one of the characters in the specified character set. The first character found causes the search to stop, and the text from the pointer’s location to the position of the character found is selected. When you call the UpTo method, the pointer moves to the position of the first character found instead of selecting a range of text.
The Span method has the following syntax:
RichTextBox1.Span characterset, forward, negate
UpTo has a similar syntax:
RichTextBoxl.UpTo characterset, forward, negate
The characterset.argument is a string variable or constant that contains all the characters that mark the end of the select or the new position of the pointer. The forward argument is a Boolean variable that determines the direction of the search:
- True causes a forward search om the current position of the pointer to the end of the text.
- False causes a backward search.
The negate variable is usually False and means that the search should locate one of the characters specified in the characterset variable, If you want to search for all characters except for a few, you can specify the characters you want to exclude from the search and set the negate argument to True, To implement a “select whole word” or “select sentence” feature in your text editing application, capture the KeyUp event and check for the key pressed, as explained in the following section. .
Selecting Words and Sentences
Suppose you want the program to select the current word when ctrl+W is pressed and the current sentence when Ctrl+S is pressed. First, the program must check the status of the Ctrl key, and if it’s pressed, check the status of the Wand S keys. If the W key is pressed, it should call the Span method to select everything from The pointer’s location to the end of the word. If the S key is pressed, it should call the Span method to select everything from the pointer’s location to the end of the sentence. You must also supply the characters that commonly mark the end of a word or a sentence. See Figure 9.5 for an example of how this works.
If the pointer is in the middle of a word, this technique selects only the characters from the pointer’s location to the end of the word. However, selecting part of a word or a sentence is usually not what users want-they want to select the whole word with a single keystroke. Since you can’t expect the user to position the pointer at
the beginning of a word or sentence, you have to call the Span method twice, once to select the characters thatbelong to the word to the left of the pointer and again to select the characters to the right. In the first call of the function, You must set the forward argument to False (to search backward), and in the second call, you must set the forward argument to True (to search forward), This is what the first segment of Code 9.2 does.
The Ctrl+W and Ctrl+S Key Combinations
Code 9.2:
This subroutine is used in the RTFPad application to implement the select word and select sentence features. The Ctrl+W keystroke selects the current word, and the Ctrl+S keystroke selects the current sentence; Ctrl+Shif+W moves the pointer to the end of the current word, and Ctrl+Shift+S moves the pointer to the end of the current sentence. Notice the similarities between the Span and UpTo methods. You can open the RTFPad application in this chapter’s folder on the CD, enter some text in the control, and see how these keystrokes behave.
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 syntax of’ the Find method is as follows:
RichTextBox1.Find(string, start, end, options)
The siring argument is the string you want to locate in the RichTextBox control, start and end are the starting and ending locations of the search (use them to search for a string within a specified range only), and options is the sum of one or more of the constants listed in Table 9.3.
To combine multiple options, you can add their values or you can combine them with the OR operator. All the arguments of the Find method are optional except for the string to be matched. If you omit them, they take on their default values. As a result, the search isn’t case-sensitive, the entire text is searched, and the matching text is highlighted. If you specify only the start argument, the search is performed on the text from the specified position to the end of the text. Likewise, if you specify only the end argument, the search is performed on the text from the first character up to the specified character position.
The RTFPad application’s Find command demonstrates how to use the Find method and its arguments to build a Find & Replace dialog box that performs all the types of text searching operations you might need in a text editing application. The code is identical to the code of the Search &Replace dialog box of the Notepad application presented in Chapter 5 in “Search and Replace Operations.”
Text Formatting Properties
The RichTextBox control provides a number of properties for setting the appearance of the text in the control. Through the formatting properties, you can format the text in any of the ways possible through a word processing application such as WordPad. This section discusses all the text formatting properties of the Rich- TextBox control and how they are used.
Font Properties and Attributes
The following properties apply user-specified font, size, and attributes to the selected text. They can also be used to read the settirigs from within your code.
SelFontName, SelFontSize Properties To change the font and size of the selected text, use these properties. The following statements render the selected text in 24-point Verdana font:
RichTextBox1.SelFontName = ‘Verdana’
RichTextBox1.SelFontSize = 24
You must supply the name of a font that exists on the user’s computer; if you don’t, a similar font will be substituted. Use the Font common dialog box (discussed in Chapter 8, Advanced ActiveX Controls) to let the user select one of the available fonts, as well as the desired attributes.
SelBold, Selltalic. SelUnderline Properties You can read the value of these properties to check the formatting of the selected text from within your code, or you can set them to change the formatting accordingly. The following statements turn on the bold and italic attributes of the selected text:
RichTextbox1.SelBold =True
RichTextbox1.Selltalic =True
If no text is selected, the attributes are set for the character at the current location of the pointer. By setting the character-formatting properties accordingly (usually with the click of a button or a menu command), the user is, in effect, changing the style of the selected text.
The character-formatting properties are frequently used as toggles. Every time the user clicks a Bold button (or selects Bold from the application’s menu), the following code is executed:
RichTextbox1.SelBold = NOT RichTextbox1.SelBold
If the selected text is in bold, it’s turned back to normal; if it’s normal, it’s turned to bold. There is no property to reset the text style to normal. To do so you must manually set all three properties to False:
RichTextbox1.SelBold= False
RichTextbox1.Selltalic = False
RichTextbox1.SelUnderline= False
SelCharOffset Property This property determines whether the selected characters appear on, above, or below the text baseline. Normally, text appears on the baseline. You can raise characters above their baseline to create superscripts (you must also reduce the text’s font size by a point or two) or place it below the baseline to create subscripts. To lower the selected text, assign a negative number to the SeICharOffset property. This value must be expressed in twips:
Text Alignment Properties
The next group of properties control (or return) the alignment and indentation of the selected text in the RkhTextBox control.
SelAlignment Property Use this property to read or change the alignment of one or more paragraphs. It can have one of the values shown in Table 9.4.
Sellndent, SelRightindent, SeIHanginglndent Properties When designing applications with the RichTextBox control/the most meaningful values for the container’s ScaleMode property are points, inches, and-millimeters (more on this property can be found in Chapter 6, Drawning with Visual Basic). Setting the values of the indentation properties is rather trivial, but designing a user interface that enables the user to intuitively and conveniently set these properties isn’t. You can set the indentation of the selected text with the following properties:
- SelIndent sets (or returns) the amount of the text’s indentation from the left edge of the control.
- SelRightIndent sets the indentation of the right side of the text from the right margin.
- SelHanginglndent specifies the distance between the left edge of the first line of the selected paragraph(s) (including any indentation specified by the SelIndent property) and the left edge of subsequent lines in the paragraph(s).
The hanging indentation can also be negative, in which case, the first line of text extends to the left farther than the rest of the paragraph. Figure 9.6 shows three possible combinations of the left and hanging indentation, all made possible with the two slider controls above the text.
SelBullet Property You use this property to create a list of bulleted items. If you set the SelBullet property to True, the selected paragraphs are formatted with a bullet style, similar to the <UL> tag in HTML. To create a list of bulleted items, select them with the pointer and then assign the value True to the SelBullet property. To
change a list of bulleted items back to normal text, select the items and then assign the value False to the SelBullet property.
The paragraphs formatted With the SelBullet property set to True are indented from the left by a small amount. To change the value of the indentation, use ‘the Bulletlndent property, whose syntax is as follows:
RichTextBox1.Bulletlndent = value
You can also read the BulletIndent property from within your code to find out the bulleted items indentation. Or you can use this property, along with the SelBullet property, to simulate nested bulleted items. If the current selection’s SelBullet property is True and the user wants to apply the bullet format, you can increase the indentation of the current selection.
VB6 at Work: The RTFPad Project
Creating a functional, even fancy, word processor based on the RichTextBox control is quite simple. The challenge is to provide a convenient interface that lets the user select text, apply attributes and styles to it, and then set the control’s properties accordingly. This chapter’s application does just that. It’s called RTFPad, and you can find it in this chapter’s folder on the CD. .
The RTFPad application (see Figure 9.7) is based on the TextPad application developed in Chapter 5, Basic ActiveX Controls. It contains the same text editing commands and some additional text formatting commands that can only be implemented with the RichTextBox control: for example, it allows you to mix font styles in the text. This section examines the code and discusses a few topics unique to this Application’s implementation with the RichTextBox control.
The two slider controls above the RichTextBox control manipulate the indentation of the text. We’ve already explored this arrangement in the discussion of the Slider control in Chapter 5, but let’s review the operation of the two slider controls again. Every time they are scrolled, the following code is executed.
Setting the Slider Controls
Code 9.3:
The Slider1 control sets the text’s left indentation as a percentage of the control’s width (same percentage as the control’s value compared with the maximum value). Next, the code of the other control’s Scroll event is executed to set the hanging indentation. If the user changes the hanging indentation, the Slider1_Scroll sub-routine isn’t called from within the Slider2 control’s code because there’s no reason to adjust the overall indentation.
Enter some text-in the control, select one or more paragraphs, and check out the operation of the two sliders. Unfortunately, there’s no Slider control that has indicators for setting both left and right values, thereby controlling both margins.
The Scroll events of the two slider controls adjust the text’s indentation. The opposite action must take place when the user rests the pointer on another paragraph: the Sliders’ positions must be adjusted to reflect the new indentation of the text. The selection of a new paragraph is signaled to the application by theSelChange event. Among the statements that are executed from within the SeIChange event (they are discussed in the next sections), the following one adjusts the two slider controls to reflect the indentation of the text.
Setting the Slider.Controls
Code 9.4:
Change the sliders’ positions aGCording to the selection’s indentation.
If the user selects multiple paragraphs with different indentations, the Sellndent property returns Null. The code examines the value of the Sellndent property and if it’s Null, it disables the two slider controls (since it can’t set their position). If it’s not Null, it sets the positions of the controls according to the values of the Sellndent and Sell-Hanginglndent properties.
The File Menu
The RTFPad application’s File menu contains the usual Open and Save commands, which are implemented with the LoadFile and SaveFile methods, and the Print command. Here is the implementation of the Open command in the File menu.
The Open Command
Code 9.5:
The OpenFile variable is global and holds the name of the currently open file. It’s set every time a new file is successfully opened and used by the Save command to automatically save the open file, without prompting the user for a filename.
The Save menu’s code is similar, only it calls the SaveFile method to save the RTF code to a disk file,
Printing the RTFDocument
The Print command is implemented with a few lines of code that select all the text on the control and then call the SelPrillt method to print the selected text. The EditSelect, (Click subroutine is the event handler of the Select All command of the Edit menu. The SelPrint method’s argument is the hDC property of the printer where the text is printed. The code uses the default printer, but you can display the Print common dialog box, where the user can select any of the available printers, If you do so, don’t give your users the option to select a range of pages, because the SelPrint method doesn’t provide a mechanism for this. It’s a very simple method that prints the selected text and offers no options, Hopefully, a future version of the RichTextBox control will provide a more flexible Print method. I should warm you that implementing your own printing procedure is quite a task. Here’s the listing for the Print command’s event handler:
The Print Command of the RTFPad Project
Code 9.6
The Edit Menu
The RTFPad application’s Edit menu commands are quite simple. Instead of the SelText property, they use the control’s SelRTF property to move information to the Clipboard and back so that the copied text carries its formatting information with it. If you aren’t familiar with the Clipboard’s methods, all you need to know to follow this example are the SetText method, which copies a string to the Clipboard, and the GetText method, which copies the Clipboard’s contents to a string variable. The Copy and Cut commands are shown next.
The Copy and Cut Commands
Code 9.7:
…
The Paste command examines the type of the contents stored in the Clipboard, with the GetFormat() method and pastes them at the current location in the control either in text or RTF format. The Paste command’s code follows.
The Paste Command
Code 9.8:
You can also insert bitmaps, or other”objects in the RTFPad’s window. To do so, open an image with Paint (or another image processing application), copy it to the Clipboard, and then paste it in the RTFPad application by pressing Shift-Insert, The Paste command won’t paste bitmaps, You’ll see how to paste other types of objects in the RichTextBox control, as well as how to access these objects in Chapter 14; OLE Automation and VBA.
RTFstands for Rich Text Format, which is a standard for storing formatting information along with the text. The beauty of the RichTextBox control for programmers is that they don’t need to supply the formatting codes. The control provides simple properties that turn the selected text into bold, change the alignment of \he current paragraph, and so on. The RTF code is generated internally by the control and used to save and load formatted files. It’s possible to create elaborately formatted documents without knowing the RTF language.
The RTF Language
A basic knowledge of the RTF format, its commands, and how it works, will certainly help you understand how the RichTextBox control works. RTF is a document formatting language that uses simple commands to specify the formatting of a document. These commands, or tags, are ASCll strings, such as \par (the tag that marks the beginning of a new paragraph) and \b (the tag that turns on the bold style). And this is where the value of the RlF format lies. RTF document) don’t contain special characters and can be easily exchanged among different operating systems and computers, as Iong as there is an RTF-capable application to read the document. Let’s look at the RTF document in action.
Open the WordPad application (choose Start» Programs» Accessories» WordPad) and enter a few lines of text (see Figure 9.2). Select a few words or sentences and format them-in different ways with any of WordPad’s formatting commands. Then save the document in RTF format. Choose Pile >Save As, select Rich Text Format, and then save the file as Document.rtf. If you open this file with a text editor such as NotePad, you’ll see the actual RTFcode that produced the document. You can find the RTF file for the document shown in Figure 9.2 in this chapter’s folder on the CD.
The RTFCode for the Document in Figure 9.2
Code 9.2:
RTF is similar to HTML (Hypertext Markup Language), and if you’re familiar with HTML, a few comparisons between the two standards will provide helpful hints and insight into the RTF language. Like HTML, RTF was designed to create formatted documents that could. be displayed on different systems. The RTF language uses tags to describe the document’s format. For example, the tag for italics is \i, and its scope is delimited with a pair of curly brackets. The following RTF segment displays a sentence with a few words in italics:
({\b RTF) (which stands for Rich Text Format) is a (\i document
formatting language) that uses simple commands to specify the
formatting of the document.}
The following is the equivalent HTML code:
<B>RTF</B> (which stands for Rich Text Format) is a <I>document formatting language</I>) that uses simple commands to specify the formatting of the document.
The <B> and <I> tags of HTML are equivalent to the \b and \i tags of RTF. RTF, however, is much more complicated. than HTML. It’s not nearly as easy to understand an RTF document as it is to understand an HTML document because RTF was meant to be used internally by applications. As you can see in the RTF segment presented earlier, RTF contains information about the font being used, its size, and so on. Just as you need a browser to view HTML documents, you need an RTF- capable application to view RTF documents. WordPad, for instance, supports RTF and can both save a document in RTF format and read RTFfiles.
You’re not expected to supply your own RTF code to produce a document. You simply select the segment of the document you want to format and apply the corresponding formatting command from within your word processor. Fortunately, the RichTextBox control isn’t any different. It doesn’t require you Of the users of your application to understand RTF code. The RichTextBox control does all the work for you while hiding the low-level details.
VB6 at Work: The RTFDemo Application
The RTFDemo application, shown in Figure 9.3, demonstrates the principles of programming the RichTextBox control. The RichTextBox control is the large box in the upper section of the Form where you can type text as you would with a regular TextBox control.
Use the buttons on the top row to set styles for the selected text. The Bold and Italic buttons are self-explanatory; the Regular button restores the regular style of the text. All three buttons set (or reset) the value of the properties SelBold (for the bold attribute) and SeIItalic (for the italic attribute). By setting one of these properties to True, the corresponding attribute is turned on for the selected text; if set to False, it will be turned off. Here’s the code behind the Bold button:
RichTextBox1.SelBold = True
The code for the Italic button is:
RichTextBox1.SelItalic = True
The Regular button’s code contains the following two lines:
RichTextBox1.SelBold = False
RichTextBox1.Selltalic = False
The Clear button clears the contents of the control by setting its Text property to an empty string:
RichTextBox1.Text = “”
The two buttons on the second row demonstrate the nature of the RichTextBox control. Select a few words on the control, turn on their bold and/or italic attribute, and then click the Show Text button. You’ll see a message box that contains the control’s text. No matter how the text is formatted the control’s Text property will be same. This is the text you would copy from the control and paste into a text editing application that doesn’t support formatting commands (for example, Notepad).
The RTFCode
H you click the Show RTFbutton, you’ll see the actual RTFcode that produced the formatted document in Figure 9.3. The message box with the RTFcode is shown in Figure 9.4. This is all the information the RichTextBox control requires to render Document. As complicated as it may look, it isn’t difficult to produce. IR programming the RichTextBoxcontrol. you’ll rarely have to worry about inserting actual tags in the code. The control is responsible for generating the RTFcode and for rendering the document, You simply manipulate a few properties (the recurring theme VisualBasic programming) and the control does the rest.
On rather rare occasions, you may have to supply RTF tags. You’ll see an example of this in Chapter 11, Recursive Programming, with the DirMap application, which produces RTFcode on the fly.You don’t have to know much about RTFtags, though. Simply format a few words with the desired attributes using the RTFDemo application (or experiment with the Immediate window), copy the tags that produce the desired result, and use them in your application. If you are curious about RTF, experiment with the RTFDemo application.
One of the most interesting applications on the book’s CD-ROM is the RTFPad application, a word processing application that’s discussed in detail later in this chapter. This application duplicates much of the functionality of Windows Word- Pad, but it’s included in this book to show you how the RichTextBox control is used. The RTFPad application can become your starting point for writing custom word processing applications (a programmer’s text editor with color-coded keywords, for example).
Text Manipulation Properties
The RichTextbox control’s properties for manipulating selected text start with the prefix Sel. The most commonly used properties related to the selected text are shown in Table 9.1
SelText, for example, represents the selected text. To assign the selected text to a variable, use the following statement:
SText= RichTextBox1.SelText
RichTextbox1 is the name of the control. You can also modify the selected text by assigning a new value to the SelText property. The following statement converts the selected text to uppercase:
RichTextbox1.SelText = UCase(RichTextbox1.SelText)
If you assign a string to the SelText property, the selected text in the control is replaced with the string. ‘The following statement replaces the current selection on the RichTextbox1 control with the string “Revised string”:
RichTextbox1.SelText = ‘Revised string’
If no text is selected, the statement inserts the string at the location of the pointer. It is possible, therefore, to insert text automatically by assigning a string to the Sel- Text property.
To simplify the manipulation and formatting of the text on the control, two additional properties, Se/Start and SelLength report the position of the first selected character in the text and the length of the selection, respectively. You can also set the values of these properties to select a piece of text from within your code. One obvious use of these properties is to select (and highlight) the entire text (or a segment of the text):
RichTextBoxl.SelStart= 0
RichTextBox1.SelLength = Len(RichTextBox1.Text)
The search starts with the first character.of the text and moves forward. To implement a “backward search” option, add another CheckBox control on the Find Form, and adjust the start and end arguments of the Find method accordingly.
The Format Menu
The format menu lets the user set t~e font, size, and attributes of the selected text. The first command of the Format menu is Font, and it opens the Font common dialog box, in which the user can select the font, size, and attributes of the selected text. Although the font doesn’t change frequently in a document, the attributes do, and the application shouldn’t force the user to open the Font common dialog box just to turn a word into bold or italics. That’s why the font attributes are also implemented as commands on the Format menu.
The Bold, Italic, Underline, and Regular commands on the Format menu turn and off the corresponding attribute. A checkmark next to one of these commands indicates the attribute of the current selection. If only part of the selection is bold, the SelBold property returns Null to indicate that the selection isn’t uniform. You must always check the values of the Selltalic, SeIBold, and SeIUnderline properties for Null values. You will see an example of how these properties are used to read the attributes of the selected text in the next section, “The SeIChange Event.”
The first function of the Bold, Italic, and Underline commands is.quite simple: to turn on the corresponding attribute of the selected text. If the selected text isn’t bold, selecting the Bold command turns on the attribute. If the selected text is bold already, this command turns off the attribute. The second function of these commands is to reflect the attributes of the selected text; that , you must set or rest the checkmark in front of their names depending on the attributes of the selected text. The RTFPad application must track the user’s actions through the SelChange event, which is triggered every time the current selection changes. From within this event, we must examine the values of the SeIBold, Selltalic, and SelUnderline properties and set (or reset) the checkmark in front of the corresponding menu command. The three iont attribute commands are implemented with code from within two events; the menu command’s Click event and the RichTextBox control’s SeIChange event. The Click event handler for the Bold command is shown next.
The Bold Command
Code 9.10:
First, the program switches the current state of the menu command (if it’s checked, it unchecks it, and vice versa). It then turns on or off the bold attribute of the selected text according to the recently updated state of the Bold command.
SeIChange Event To be able to set the status of the various commands of the Format menu, your code must be able to detect when the user changes the current selection. This action is reported to your application by the control’s SelChange event In the RichTextbox control’s SelChange event. the program does the opposite. It examines the attribute of the selected text and sets the command state accordingly. Following are the statements that manipulate the state of the formatting commands from within the SelChange event.
The SaIChange Event
Code 9.11:
Notice the use of the IsNull() function. If part of the selected text has an attribute twIled on and part of it has the same attribute turned off, the Selbold property is neither True nor False. Instead, it’s undefined, and the program must check for this condition, If the Selbold property is defined, the Bold command is checked or. unchecked, depending on the value of the property.
If the Selbold attribute is undefined, the menu command doesn’t change. (You could replace the Bold title with another string, such as “mixed”, indicating that the corresponding attribute is not uniform for the current selection.) Earlier in the chapter, you learned that the SeIChange event handler also contains statements the adjust the positions of the slider controls to reflect the indentation of the selected text
The font attributes menu commands are best implemented with Tri-state buttons. For example, when the selected text is bold and the user presses the Bold button, the text is reset to regular. If the current selection’s bold attribute is undefined, the corresponding button should assume a third (grayed) appearance.
When the user clicks the Bold button, RTFPad should turn the bold attribute on and off. This feature is relatively easy to implement, except perhaps for designing the pictures for the three states (on, off, mixed) of the Command buttons. Visual programming requires some artistic talent; your programming abilities won’t help you much here.
You’ve learned basically everything there is to know about the RichTextBox control. It provides the basic functionality of a word processing application, and add’ more features to an editor is as simple as setting the values of its various properties.
The Objects Collection If you experiment a little with the RTFPad application you’ll find out that it can accept more than text. You can copy a bitmap in an image processing application and paste it into the RichTextBox control by pressing Shift+Insert. The Paste .command of the Edit menu doesn’t recognize anything more than text (plain or RTF format), but the control itself is capable of accepting other data types, including objects. For example, you can insert a sound file or video file (AVI or MPEG file) at the current location in the text. The various object that can exist on the RichTextBox control along with the text can be accessed through the Objects collection. This is a rather advanced topic, and I will postpon its discussion until Chapter 14, OLE Automation and VBA. In this chapter, you’ll learn how to manipulate the objects embedded in the RichTextBox control and even how to recognize when an object is about to be pasted and how to react to this action .
