Visual Basic Concepts

Using the RichTextBox Control

See Also

The RichTextBox control allows the user to enter and edit text while also providing more advanced formatting features than the conventional TextBox control.

The RichTextBox control provides a number of properties you can use to apply formatting to any portion of text within the control. Using these properties, you can make text bold or italic, change its color, and create superscripts and subscripts. You can also adjust paragraph formatting by setting both left and right indents, as well as hanging indents.

Possible Uses

• As a "bottomless" text box, to allow an application to read extremely large text files.
  
  
• To implement a full-featured text editor into any application.

Features

• Open and save files in both the RTF format and ASCII text format. You can use methods of the control (LoadFile and SaveFile) to directly read and write files, or use properties of the control, such as SelRTF and TextRTF, in conjunction with Visual Basic's file input/output statements.
  
  
• Load the contents of an .rtf file into the RichTextBox control simply by dragging the file (from the Windows Explorer for example), or a highlighted portion of a file used in another application (such as Microsoft Word), and dropping the contents directly onto the control.
  
  
• Set the FileName property to load the contents of an .rtf or .txt file into the control.
  
  
• Print all or part of the text in a RichTextBox control using the SelPrint method.
  
  
• Bind the RichTextBox control with a Data control to a Memo field in a Microsoft Access database or a similar large capacity text field in other databases (such as a TEXT data type field in SQL Server).
  
  
• Programmatically add embedded objects such as bitmaps, icons, application icons, into the control at run time using the OLEObject collection's Add method. At both design time and run time, drag and drop any embedded object, including documents such as Microsoft Excel spreadsheets and Microsoft Word documents, into the control.

Set Scrollbars at Design Time

By default, the RichTextBox doesn't include scrollbars. At run time, if a large file is loaded into the control, the end user will not be able to see all that is in the file. To allow the user to scroll easily, set the ScrollBars property to 1 (horizontal), 2 (vertical), or 3 (both). This must be done at design time, because the ScrollBars property is read-only at run time.

Open and Save Files with the LoadFile and SaveFile Methods

You can easily open or save an RTF file with the RichTextBox control by using the LoadFile and SaveFile methods. To open a file, use a CommonDialog control to supply the path name as shown:

Private Sub OpenFile()
   ' The RichTextBox control is named "rtfData."
   ' The CommonDialog is named "dlgOpenFile."
   ' Declare a String variable for file name.
   ' Show the Open File dialog box, and set the 
   ' variable to the filename.
   Dim strOpen As String
   dlgOpenFile.ShowOpen
   strOpen = dlgOpenFile.FileName
   ' Use LoadFile method to open the file.
   rtfData.LoadFile strOpen
End Sub

To save a file is just as easy, using the SaveFile method:

Private Sub SaveFile()
   Dim strNewFile As String
   dlgOpenFile.ShowSave
   strNewFile = dlgOpenFile.FileName 
   rtfData.SaveFile strNewFile
End Sub

Note   If a file contains RTF codes that aren't supported by the control, the affected text only will not appear in the RichTextBox control.

Use the SelFontName, SelFontSize, and SelFontColor to Set Font Attributes

To change the font attributes of text in the RichTextBox control, use the SelFontName, SelFontSize, and SelFontColor properties.

The ComboBox control is often used to display a range of choices for these properties. Subsequently, the ComboBox control's Click event can be used to change the property. The following code first populates a ComboBox control named "cmbFonts" in the Form object's Load event. The Click event is then used to change the SelFontName property of a RichTextBox control:

Private Sub Form_Load()
   Dim i As Integer
   With cmbFonts
      For i = 0 to Screen.Fonts.Count - 1
      .AddItem Screen.Fonts(i).Text
   End With
End Sub

Private Sub cmbFonts_Click()
   rtfData.SelFontName = cmbFonts.Text
End Sub

Important   These properties only affect selected text, or, if no text is selected, the text that is typed after the current cursor location.

Format Indents, Hanging Indents, and Bulleted Paragraphs

Another feature of the RichTextBox control is its ability to create paragraphs with indents, hanging indents, and bulleted paragraphs. The three styles are shown here:

Indents and bulleted indents (rtf_3ind.bmp)

As with the SelFontName, SelFontSize, and SelFontColor properties, the end user must select a paragraph or range of paragraphs before applying these attributes. Thus, assuming the user had selected the second paragraph only, the code to create an indent and hanging indent would be as follows:

' Assuming the control is named "rtfData."
rtfData.SelIndent = .5
rtfdata.SelHangingIndent = 1.5

Note that the number used to set the SelIndent, SelHangingIndent, BulletIndent and other properties depends upon the ScaleMode property of the container of the RichTextBox control. For example, if the RichTextBox's container is a Form object, and you change the Form object's ScaleMode property from 7 (centimeters) to 1 (twips), the SelIndent property must change from .5 (centimeters) to 283 (twips). This is because one centimeter = 567 twips.

Also note that the SelBullet property of a paragraph must be set to True for a paragraph to have the bullet style.

Use the SelChange Event for Notification of Attribute Changes

To notify the user of the current attributes of any selected text, use the SelChange event, which occurs whenever the insertion point moves, or the selection has changed. The following example uses a Toolbar control to notify the user of changes in the SelBold property.

Private Sub rtfData_SelChange()
   ' Reset the Value property of a Toolbar
   ' Button object. The Toolbar control is 
   ' named "tlbRTF."

   ' SelBold returns 0, -1, or Null. If it's Null 
   ' then set the MixedState property to True.

   Select Case rtfData.SelBold
   Case 0 ' Not bold.
      tlbRTF.Buttons("bold").Value = tbrUnpressed
   Case -1 ' Bold.
      tlbRTF.Buttons("bold").Value = tbrPressed
   Case Else ' Mixed state.
      tlbRTF.Buttons("bold").MixedState = True
   End Select
End Sub

Use the SelPrint Method to Print the RichTextBox Contents

To print from the RichTextBox control, use the SelPrint method. This method requires one argument, the hDC property of the Printer object that will print the RichTextBox control's contents. If any text is selected by the user, only the selected text will be printed. If no text is selected, the entire contents of the control will be printed.

The following code uses the CommonDialog control to display a Printer dialog box when the user clicks a CommandButton control. The Flags property disables page numbers, and allows the user to choose various options on the dialog box:

Private Sub cmdPrint_Click()
   ' The CommonDialog control is named "dlgPrint."
    
   dlgPrint.Flags = cdlPDReturnDC + cdlPDNoPageNums
   If rtfData.SelLength = 0 Then
      dlgPrint.Flags = dlgPrint.Flags + cdlPDAllPages
   Else
      dlgPrint.Flags = dlgPrint.Flags + cdlPDSelection
   End If
   dlgPrint.ShowPrinter
   rtfData.SelPrint dlgPrint.hDC
End Sub

For More Information   For more information on using the CommonDialog control, see "Using the CommonDialog Control", in the Programmer's Guide.

Display Embedded Objects in the Control

At run time, the end user can drag and drop any embedded objects into the RichTextBox control. There are two kinds of objects that can be embedded into the control: objects which display as icons, and objects which display as data. As an example of the first type, the following figure shows a RichTextBox with an embedded file object.

When clicked, the embedded object will behave as expected — starting up the application associated with the file. When the data in the control is saved as an RTF file (using the SaveFile method), the information in the embedded object will also be saved.

However, if the end user embeds a bitmap into the control, the bitmap itself will be displayed, not its icon, as shown:

Clicking on the bitmap will start the Paint application, allowing the end user to edit the bitmap.

Add Embedded Objects Using the OLEObjects Collection's Add Method

You can programmatically add embedded objects to the control using the OLEObject collection's Add method, as shown:

Private Sub cmdAddObject_Click()
   ' Add the butterfly bitmap to the control.
   RichTextBox1.OLEObjects.Add , , , "bfly.bmp"
End Sub

Using the Add, Clear, and Remove methods, you can dynamically populate the control with embedded objects at run time.