Set this property to True if you want users to be able to open the dialog box and define their own custom colors, as you can in the one shown in Figure 7.2. The AllowFullOpen property doesn't open the custom section of the dialog box; it simply enables the Define Custom Colors button in the dialog box. Otherwise, this button is disabled.

This property is a Boolean value that determines whether the dialog box displays all available colors in the set of basic colors.

This is the color specified on the control. You can set it to a color value before showing the dialog box to suggest a reasonable selection. On return, read the value of the same property to find out which color was picked by the user in the control:

ColorDialog1.Color = Me.BackColor
If ColorDialog1.ShowDialog = DialogResult.OK Then
    Me.BackColor = ColorDialog1.Color
End If

This property indicates the set of custom colors that will be shown in the dialog box. The Color dialog box has a section called Custom Colors, in which you can display 16 additional custom colors. The CustomColors property is an array of integers that represent colors. To display three custom colors in the lower section of the Color dialog box, use a statement such as the following:

Dim colors() As Integer = {222663, 35453, 7888}
ColorDialog1.CustomColors = colors

You'd expect that the CustomColors property would be an array of Color values, but it's not. You can't create the array CustomColors with a statement such as this one:

Dim colors() As Color =
           {Color.Azure, Color.Navy, Color.Teal}

Because it's awkward to work with numeric values, you should convert color values to integer values by using a statement such as the following:

Color.Navy.ToArgb

The preceding statement returns an integer value that represents the color navy. This value, however, is negative because the first byte in the color value represents the transparency of the color. To get the value of the color, you must take the absolute value of the integer value returned by the previous expression. To create an array of integers that represent color values, use a statement such as the following:

Dim colors() As Integer =
           {Math.Abs(Color.Gray.ToArgb),
            Math.Abs(Color.Navy.ToArgb),
            Math.Abs(Color.Teal.ToArgb)}

Now you can assign the colors array to the CustomColors property of the control and the colors will appear in the Custom Colors section of the Color dialog box.

This indicates whether the dialog box will restrict users to selecting solid colors only. This setting should be used with systems that can display only 256 colors. Although today few systems can't display more than 256 colors, some interfaces are limited to this number. When you run an application through Remote Desktop, for example, only the solid colors are displayed correctly on the remote screen regardless of the remote computer's graphics card (and that's for efficiency reasons).

This property is a Boolean value that indicates whether the Script combo box will be displayed in the Font dialog box. This combo box allows the user to change the current character set and select a non-Western language (such as Greek, Hebrew, Cyrillic, and so on).

This property is a Boolean value that indicates whether the dialog box allows the display and selection of both vertical and horizontal fonts. Its default value is False, which displays only horizontal fonts.

The Color property sets or returns the selected font color. To enable users to select a color for the font, you must also set the ShowColor property to True.

This property is a Boolean value that indicates whether the dialog box allows only the selection of fixed-pitch fonts. Its default value is False, which means that all fonts (fixed- and variable-pitch fonts) are displayed in the Font dialog box. Fixed-pitch fonts, or monospaced fonts, consist of characters of equal widths that are sometimes used to display columns of numeric values so that the digits are aligned vertically.

This property is a Font object. You can set it to the preselected font before displaying the dialog box and assign it to a Font property upon return. You've already seen how to preselect a font and how to apply the selected font to a control from within your application.

You can also create a new Font object and assign it to the control's Font property. Upon return, the TextBox control's Font property is set to the selected font:

Dim newFont As New Font("Verdana", 12, FontStyle.Underline)
FontDialog1.Font = newFont
If FontDialog1.ShowDialog() = DialogResult.OK Then
    TextBox1.ForeColor = FontDialog1.Color
End If

This property is a Boolean value that indicates whether the dialog box forces the selection of an existing font. If the user enters a font name that doesn't correspond to a name in the list of available fonts, a warning is displayed. Its default value is True, and there's no reason to change it.

These two properties are integers that determine the minimum and maximum point size the user can specify in the Font dialog box. Use these two properties to prevent the selection of extremely large or extremely small font sizes because these fonts might throw off a well-balanced interface (text will overflow in labels, for example).

This property is a Boolean value that indicates whether the dialog box provides an Apply button. Its default value is False, so the Apply button isn't normally displayed. If you set this property to True, you must also program the control's Apply event — the changes aren't applied automatically to any of the controls in the current form.

The following statements display the Font dialog box with the Apply button:

Private Sub Button2_Click(...) Handles Button2.Click
   FontDialog1.Font = TextBox1.Font
   FontDialog1.ShowApply = True
   If FontDialog1.ShowDialog = DialogResult.OK Then
       TextBox1.Font = FontDialog1.Font
   End If
End Sub

The FontDialog control raises the Apply event every time the user clicks the Apply button. In this event's handler, you must read the currently selected font and use it in the form so that users can preview the effect of their selection:

Private Sub FontDialog1_Apply(...) Handles FontDialog1.Apply
   TextBox1.Font = FontDialog1.Font
End Sub

This property is a Boolean value that indicates whether the dialog box allows the selection of special text effects, such as strikethrough and underline. The effects are returned to the application as attributes of the selected Font object, and you don't have to do anything special in your application.

This property is a Boolean value that determines whether the dialog box automatically adds an extension to a filename if the user omits it. The extension added automatically is the one specified by the DefaultExtension property, which you must set before calling the ShowDialog method. This is the default filename extension of the files recognized by your application.

This property is a Boolean value that indicates whether the dialog box displays a warning if the user enters the name of a file that does not exist in the Open dialog box or if the user enters the name of a file that exists in the Save dialog box.

This property is a Boolean value that indicates whether the dialog box displays a warning if the user specifies a path that does not exist as part of the user-supplied filename.

This property sets the default extension for the filenames specified on the control. Use this property to specify a default filename extension, such as .txt or .doc, so that when a file with no extension is specified by the user, the default extension is automatically appended to the filename. You must also set the AddExtension property to True. The default extension property starts with the period, and it's a string — for example, .bin.

This property indicates whether the dialog box returns the location of the file referenced by the shortcut or the location of the shortcut itself. If you attempt to select a shortcut on your Desktop when the DereferenceLinks property is set to False, the dialog box will return to your application a value such as C:WINDOWSSYSTEM32lnkstub.exe, which is the name of the shortcut, not the name of the file represented by the shortcut. If you set the DereferenceLinks property to True, the dialog box will return the actual filename represented by the shortcut, which you can use in your code.

Use this property to retrieve the full path of the file selected by the user in the control. If you set this property to a filename before opening the dialog box, this value will be the proposed filename. The user can click OK to select this file or select another one in the control. The two controls provide another related property, the FileNames property, which returns an array of filenames. To find out how to allow the user to select multiple files, see the discussion of the MultiSelect and FileNames properties later in this chapter.

This property is used to specify the type(s) of files displayed in the dialog box. To display text files only, set the Filter property to Text files|*.txt. The pipe symbol separates the description of the files (what the user sees) from the actual filename extension (how the operating system distinguishes the various file types).

If you want to display multiple extensions, such as .bmp, .gif, and .jpg, use a semicolon to separate extensions with the Filter property. Set the Filter property to the string Images|*.bmp;*.gif;*.jpg to display all the files of these three types when the user selects Images in the Save As Type combo box under the box with the filename.

Don't include spaces before or after the pipe symbol because these spaces will be displayed on the dialog box. In the Open dialog box of an image-processing application, you'll probably provide options for each image file type as well as an option for all images:

OpenFileDialog1.Filter =
     "Bitmaps|*.bmp|GIF Images|*.gif|" &
     "JPEG Images|*.jpg|All Images|*.bmp;*.gif;*.png"

When you specify more than one file type when using the Filter property of the Open dialog box, the first file type becomes the default. If you want to use a file type other than the first one, use the FilterIndex property to determine which file type will be displayed as the default when the Open dialog box is opened. The index of the first type is 1, and there's no reason to ever set this property to 1. If you use the Filter property value of the example in the preceding section and set the FilterIndex property to 2, the Open dialog box will display GIF files by default.

This property sets the initial folder whose files are displayed the first time that the Open and Save dialog boxes are opened. Use this property to display the files of the application's folder or to specify a folder in which the application stores its files by default. If you don't specify an initial folder, the dialog box will default to the last folder where the most recent file was opened or saved. It's also customary to set the initial folder to the application's path by using the following statement:

OpenFileDialog1.InitialDirectory = Application.ExecutablePath

The expression Application.ExecutablePath returns the path in which the application's executable file resides.

Every time the Open and Save As dialog boxes are displayed, the current folder is the one that was selected by the user the last time the control was displayed. The RestoreDirectory property is a Boolean value that indicates whether the dialog box restores the current directory before closing. Its default value is False, which means that the initial directory is not restored automatically. The InitialDirectory property overrides the RestoreDirectory property.

If the Open dialog box allows the selection of multiple files (you have set the MultiSelect property to True), the FileNames property contains the pathnames of all selected files. FileNames is a collection, and you can iterate through the filenames with an enumerator. This property should be used only with the OpenFileDialog control, even though the SaveFileDialog control exposes a FileNames property.

This property is a Boolean value that indicates whether the user can select multiple files in the dialog box. Its default value is False, and users can select a single file. When the MultiSelect property is True, the user can select multiple files, but they must all come from the same folder (you can't allow the selection of multiple files from different folders). This property is unique to the OpenFileDialog control. This and the following two properties are unique to the OpenFileDialog control.

The ReadOnlyChecked property is a Boolean value that indicates whether the Read-Only check box is selected when the dialog box first pops up (the user can clear this box to open a file in read/write mode). You can set this property to True only if the ShowReadOnly property is also set to True. The ShowReadOnly property is also a Boolean value that indicates whether the Read-Only check box is available. If this check box appears on the form, the user can select it so the file will be opened as read-only. Files opened as read-only shouldn't be saved with the same filename — always prompt the user for a new filename.

The OpenFileDialog control exposes the OpenFile method, which allows you to quickly open the selected file. Likewise, the SaveFileDialog control exposes the SaveFile method, which allows you to quickly save a document to the selected file. Normally, after retrieving the name of the file selected by the user, you must open this file for reading (in the case of the Open dialog box) or writing (in the case of the Save dialog box). The topic of reading from or writing to files is discussed in detail in the tutorial "Accessing Files and Folders with the System.IO Class," which is available for download at www.sybex.com/go/masteringvb2010.

When this method is applied to the Open dialog box, the file is opened with read-only permission. The same method can be applied to the SaveFile dialog box, in which case the file is opened with read-write permission. Both methods return a Stream object, and you can call this object's Read and Write methods to read from or write to the file.

The Open dialog box allows the selection of multiple files. This feature can come in handy when you want to process files en masse. You can let the user select many files, usually of the same type, and then process them one at a time. Or, you might want to prompt the user to select multiple files to be moved or copied.

To allow the user to select multiple files in the Open dialog box, set the MultiSelect property to True. The user can then select multiple files with the mouse by holding down the Shift or Ctrl key. The names of the selected files are reported by the property FileNames, which is an array of strings. The FileNames array contains the pathnames of all selected files, and you can iterate through them and process each file individually.

One of this chapter's sample projects is the MultipleFiles project, which demonstrates how to use the FileNames property. The application's form is shown in Figure 7.5. The button at the top of the form, Show Files in Folder, displays the Open dialog box, where you can select multiple files. After closing the dialog box by clicking the Open button on the Open dialog box, the application displays the pathnames of the selected files on a ListBox control.

Figure 7.5. The MultipleFiles project lets the user select multiple files in the Open dialog box.

The code behind the Open Files button is shown in Listing 7.1. In this example, I used the array's enumerator to iterate through the elements of the FileNames array. You can use any of the methods discussed in Chapter 2, "VB Programming Essentials" to iterate through the array.

Private Sub bttnFile_Click(...) Handles bttnFile.Click
    OpenFileDialog1.Multiselect = True
    OpenFileDialog1.ShowDialog()
    Dim filesEnum As IEnumerator
    ListBox1.Items.Clear()
    filesEnum = OpenFileDialog1.FileNames.GetEnumerator()
    While filesEnum.MoveNext
       ListBox1.Items.Add(filesEnum.Current)
    End While
End Sub

This property indicates the initial folder to be displayed when the dialog box is shown. It is not necessarily a string; it can also be a member of the SpecialFolder enumeration. To see the members of the enumeration, enter the following expression:

FolderBrowserDialog1.RootFolder =

As soon as you enter the equals sign, you will see the members of the enumeration. The most common setting for this property is My Computer, which represents the target computer's file system. You can set the RootFolder property to a number of special folders (for example, Personal, Desktop, ApplicationData, LocalApplicationData, and so on). You can also set this property to a string with the desired folder's pathname.

After the user closes the FolderBrowser dialog box by clicking the OK button, you can retrieve the name of the selected folder with the SelectedPath property, which is a string, and you can use it with the methods of the System.IO namespace to access and manipulate the selected folder's files and subfolders.

This property determines whether the dialog box will contain a New button; its default value is True. When users click the New button to create a new folder, the dialog box prompts them for the new folder's name and creates a new folder with the specified name under the selected folder.

The FolderBrowser control is a trivial control, but I'm including a sample application, available for download from www.sybex.com/go/masteringvb2010, to demonstrate its use. The same application demonstrates how to retrieve the files and subfolders of the selected folder and how to create a directory listing in a RichTextBox control, like the one shown in Figure 7.6. The members of the System.IO namespace, which allow you to access and manipulate files and folders from within your code, are discussed in detail in the tutorial "Accessing Files and Folders," which is available for download at www.sybex.com/go/masteringvb2010.

The FolderBrowser dialog box is set to display the entire file system of the target computer and is invoked with the following statements:

FolderBrowserDialog1.RootFolder = Environment.SpecialFolder.MyComputer
FolderBrowserDialog1.ShowNewFolderButton = False
If FolderBrowserDialog1.ShowDialog = DialogResult.OK Then
' process files in selected folder
End If

As usual, we examine the value returned by the ShowDialog method of the control and we proceed if the user has closed the dialog box by clicking the OK button. The code that iterates through the selected folder's files and subfolders, shown in Listing 7.2, is basically a demonstration of some members of the System.IO namespace, but I'll review it briefly here.

Private Sub bttnSelectFiles_Click(...) Handles bttnSelectFiles.Click
    FolderBrowserDialog1.RootFolder =
                   Environment.SpecialFolder.MyComputer
    FolderBrowserDialog1.ShowNewFolderButton = False
    If FolderBrowserDialog1.ShowDialog = Windows.Forms.DialogResult.OK Then
        RichTextBox1.Clear()
        ' Retrieve initial folder
        Dim initialFolder As String =
                   FolderBrowserDialog1.SelectedPath
        Dim InitialDir As New IO.DirectoryInfo(
                     FolderBrowserDialog1.SelectedPath)
        ' and print its name w/o any indentation
        PrintFolderName(InitialDir, "")
        ' and then print the files in the top folder
        If InitialDir.GetFiles("*.*").Length = 0 Then
            SwitchToItalics()
            RichTextBox1.AppendText(
                 "folder contains no files" & vbCrLf)
            SwitchToRegular()
        Else
            PrintFileNames(InitialDir, "")
        End If
        Dim DI As IO.DirectoryInfo
        ' Iterate through every subfolder and print it
        For Each DI In InitialDir.GetDirectories
            PrintDirectory(DI)
        Next
    End If
End Sub

The selected folder's name is stored in the initialFolder variable and is passed as an argument to the constructor of the DirectoryInfo class. The InitialDir variable represents the specified folder. This object is passed to the PrintFolderName() subroutine, which prints the folder's name in bold. Then the code iterates through the same folder's files and prints them with the PrintFileNames() subroutine, which accepts as an argument the DirectoryInfo object that represents the current folder and the indentation level. After printing the initial folder's name and the names of the files in the folder, the code iterates through the subfolders of the initial folder. The GetDirectories method of the DirectoryInfo class returns a collection of objects, one for each subfolder under the folder represented by the InitialDir variable. For each subfolder, it calls the PrintDirectory() subroutine, which prints the folder's name and the files in this folder, and then iterates through the folder's subfolders. The code that iterates through the selected folder's files and subfolders is shown in Listing 7.3.

Private Sub PrintDirectory(ByVal CurrentDir As IO.DirectoryInfo)
    Static IndentationLevel As Integer = 0
    IndentationLevel += 1
    Dim indentationString As String = ""
    indentationString =
             New String(Convert.ToChar(vbTab), IndentationLevel)
    PrintFolderName(CurrentDir, indentationString)
    If CurrentDir.GetFiles("*.*").Length = 0 Then
        SwitchToItalics()
        RichTextBox1.AppendText(indentationString &
                 "folder contains no files" & vbCrLf)
        SwitchToRegular()
    Else
        PrintFileNames(CurrentDir, indentationString)
    End If
    Dim folder As IO.DirectoryInfo
    For Each folder In CurrentDir.GetDirectories
        PrintDirectory(folder)
    Next
    IndentationLevel -= 1
End Sub

The code that iterates through the subfolders of a given folder is discussed in detail in the tutorial "Accessing Files and Folders," available for download from www.sybex.com/go/masteringvb2010, so you need not worry if you can't figure out how it works yet. In the following sections, you'll learn how to display formatted text in the RichTextBox control.

The SelectedText property represents the selected text, whether it was selected by the user via the mouse or from within your code. To assign the selected text to a variable, use the following statement:

selText=RichTextbox1.SelectedText

You can also modify the selected text by assigning a new value to the SelectedText property. The following statement converts the selected text to uppercase:

RichTextbox1.SelectedText =
               RichTextbox1.SelectedText.ToUpper

You can assign any string to the SelectedText property. If no text is selected at the time, the statement will insert the string at the location of the pointer.

To simplify the manipulation and formatting of the text on the control, two additional properties, SelectionStart and SelectionLength, report (or set) the position of the first selected character in the text and the length of the selection, respectively, regardless of the formatting of the selected text. One obvious use of these properties is to select (and highlight) some text on the control:

RichTextBox1.SelectionStart = 0
RichTextBox1.SelectionLength = 100

You can also use the Select method, which accepts as arguments the starting location and the length of the text to be selected.

Use this property to read or change the alignment of one or more paragraphs. This property's value is one of the members of the HorizontalAlignment enumeration: Left, Right, and Center. Users don't have to select an entire paragraph to align it; just placing the pointer anywhere in the paragraph will do the trick because you can't align part of the paragraph.

These properties allow you to change the margins of individual paragraphs. The SelectionIndent property sets (or returns) the amount of the text's indentation from the left edge of the control. The SelectionRightIndent property sets (or returns) the amount of the text's indentation from the right edge of the control. The SelectionHangingIndent property indicates the indentation of each paragraph's first line with respect to the following lines of the same paragraph. All three properties are expressed in pixels.

The SelectionHangingIndent property includes the current setting of the SelectionIndent property. If all the lines of a paragraph are aligned to the left, the SelectionIndent property can have any value (this is the distance of all lines from the left edge of the control), but the SelectionHangingIndent property must be zero. If the first line of the paragraph is shorter than the following lines, the SelectionHangingIndent has a negative value. Figure 7.8 shows several differently formatted paragraphs. The settings of the SelectionIndent and SelectionHangingIndent properties are determined by the two sliders at the top of the form.

Figure 7.8. Various combinations of the SelectionIndent and SelectionHangingIndent properties produce all possible paragraph styles.

You use these properties to create a list of bulleted items. If you set the SelectionBullet 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 from within your code and assign the value True to the SelectionBullet property. To change a list of bulleted items back to normal text, make the same property False.

The paragraphs formatted as bullets are also indented from the left by a small amount. To set the amount of the indentation, use the BulletIndent property, which is also expressed in pixels.

Use this property to set the tab stops in the RichTextBox control. The Selection tab should be set to an array of integer values, which are the absolute tab positions in pixels. Use this property to set up a RichTextBox control for displaying tab-delimited data.

Real World Scenario: Using the RichTextBox Control to Display Delimited Data

As a developer I tend to favor the RichTextBox control over the TextBox control, even though I don't mix font styles or use the more-advanced features of the RichTextBox control. I suggest that you treat the RichTextBox control as an enhanced TextBox control and use it as a substitute for the TextBox control. One of the features of the RichTextBox control that I find very handy is its ability to set the tab positions and display tabular data. You can also display tabular data on a ListView control, as you will see later in the chapter, but it's simpler to use a RichTextBox control with its ReadOnly property set to True and its SelectionTabs property set to an array of values that will accommodate your data. Here's how to set up a RichTextBox control to display a few rows of tab-delimited data:

RichTextBox1.ReadOnly = True
RichTextBox1.SelectionTabs = New Integer() {100, 160, 340}
RichTextBox1.AppendText("R1C1" & vbTab &
             "R1C2" & vbTab &
             "R1C3" & vbCrLf)
RichTextBox1.AppendText("R2C1" & vbTab &
             "R2C2" & vbTab &
             "R2C3" & vbCrLf)

This technique is a lifesaver when I have to read the delimited data from a file. I just set up the tab positions and then load the data with the LoadFile method, which is discussed in the next section.

The syntax of the SaveFile method is as follows, where path is the path of the file in which the current document will be saved:

RichTextBox1.SaveFile(path, filetype)

By default, the SaveFile method saves the document in RTF format and uses the .rtf extension. You can specify a different format by using the second optional argument, which can take on the value of one of the members of the RichTextBoxStreamType enumeration, described in Table 7.2.

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 is as simple as presenting a Save or Open common dialog to the user and then calling one of the SaveFile or LoadFile methods with the filename returned by the common dialog box.

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, 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 it selects all the text on the control.

These two properties are Boolean values you can read to find out whether there's an operation that 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 (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 should 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 is fired when you click an item and not when you open a menu. For more information on programming the events of a menu, see Chapter 6, "Working with Forms."

These two properties return the name of the action that can be undone or redone. The most common value of both properties is Typing, which indicates that the Undo command will delete a number of characters. Another common value is Delete, and some operations are named Unknown. If you change the indentation of a paragraph on the control, this action's name is Unknown. Even when an action's name is Unknown the action can be undone with the Undo method.

The following statement sets the caption of the Undo command to a string that indicates the action to be undone (Editor is the name of a RichTextBox control):

If Editor.CanUndo Then
    EditUndo.Text = "Undo " & Editor.UndoActionName
End If

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 most recent undo action. The Redo method does not repeat the last action; it applies to undo operations only.

The RTFPad application's File menu contains the usual Open, Save, and Save As commands, which are implemented with the control's LoadFile and SaveFile methods. Listing 7.7 shows the implementation of the Open command in the File menu.

Private Sub OpenToolStripMenuItem_Click(...) Handles
                     OpenToolStripMenuItem.Click
    If DiscardChanges() Then
        OpenFileDialog1.Filter =
               "RTF Files|*.RTF|DOC Files|*.DOC|" &
               "Text Files|*.TXT|All Files|*.*"
        If OpenFileDialog1.ShowDialog() =
                       DialogResult.OK Then
            fName = OpenFileDialog1.FileName
            Editor.LoadFile(fName)
            Editor.Modified = False
        End If
    End If
End Sub

The fName variable is declared on the form's level and holds the name of the currently open file. This variable is set every time a new file is successfully opened, and it's used by the Save command to automatically save the open file without prompting the user for a filename.

DiscardChanges() is a function that returns a Boolean value, depending on whether the control's contents can be discarded. The function examines the Editor control's Modified property. If True, it prompts users as to whether they want to discard the edits. Depending on the value of the Modified property and the user response, the function returns a Boolean value. If the DiscardChanges() function returns True, the program goes on and opens a new document. If the function returns False, the program aborts the operation to give the user a chance to save the document. Listing 7.8 shows the DiscardChanges() function.

Function DiscardChanges() As Boolean
   If Editor.Modified Then
      Dim reply As MsgBoxResult
      reply = MsgBox(
          "Text hasn't been saved. Discard changes?",
           MsgBoxStyle.YesNo)
      If reply = MsgBoxResult.No Then
         Return False
      Else
         Return True
      End If
   Else
      Return True
   End If
End Function

The Modified property becomes True after the first character is typed and isn't reset back to False. The RichTextBox control doesn't handle this property very intelligently and doesn't reset it to False even after saving the control's contents to a file. The application's code sets the Editor.Modified property to False after creating a new document as well as after saving the current document.

The Save As command (see Listing 7.9) prompts the user for a filename and then stores the Editor control's contents to the specified file. It also sets the fName variable to the file's path so that the Save command can use it.

Private Sub SaveAsToolStripMenuItem_Click(...)
                  Handles SaveAsToolStripMenuItem.Click
    SaveFileDialog1.Filter =
                 "RTF Files|*.RTF|DOC Files" &
                 "|*.DOC|Text Files|*.TXT|All Files|*.*"
    SaveFileDialog1.DefaultExt = "RTF"
    If SaveFileDialog1.ShowDialog() = DialogResult.OK Then
        fName = SaveFileDialog1.FileName

Editor.SaveFile(fName)
        Editor.Modified = False
    End If
End Sub

The Save command's code is similar, only it doesn't prompt the user for a filename. It calls the SaveFile method, passing the fName variable as an argument. If the fName variable has no value (in other words, if a user attempts to save a new document by using the Save command), the code activates the event handler of the Save As command automatically and resets the control's Modified property to False. Listing 7.10 shows the code behind the Save command.

Private Sub SaveToolStripMenuItem_Click(...)
                 Handles SaveToolStripMenuItem.Click
    If fName <> "" Then
        Editor.SaveFile(fName)
        Editor.Modified = False
    Else
        SaveAsToolStripMenuItem_Click(sender, e)
    End If
End Sub

The Edit menu contains the usual commands for exchanging data through the Clipboard (Copy, Cut, Paste), Undo/Redo commands, and a Find command to invoke the Search & Replace dialog box. All the commands are almost trivial, thanks to the functionality built into the control. The basic Cut, Copy, and Paste commands call the RichTextBox control's Copy, Cut, and Paste methods to exchange data through the Clipboard. Listing 7.11 shows the implementation of the Paste command.

Private Sub PasteToolStripMenuItem_Click(...)
            Handles PasteToolStripMenuItem.Click
    Try
        Editor.Paste()
    Catch exc As Exception
        MsgBox(
              "Can't paste current clipboard's contents. " &
              "Try pasting the data in some other format.")
      End Try
  End Sub

As you may recall from the discussion of the Paste command, using the CanPaste method isn't trivial, you have to handle each data type differently. By using an exception handler, you allow the user to paste all types of data that the RichTextBox control can accept and display a message when an error occurs. Using exceptions for programming application logic can be quite costly, but in this case it's acceptable because the RTFPad editor is a desktop application serving a single user. A delay of a few milliseconds in this case should not make a huge difference.

For a more robust solution though, you might wish to handle each data type separately using the CanPaste method. That way, you can provide the user with much more precise feedback over the problem that caused the error; that is, the exact format of the data in the Clipboard they are trying to paste but the RichTextBox is not able to handle. That way you can save the user from having to guess the format your application can handle.

The Undo and Redo commands of the Edit menu are coded as follows. First, the name of the action to be undone or redone is displayed in the Edit menu. When the Edit menu is selected, the DropDownOpened event is fired. This event takes place before the Click event, so I inserted a few lines of code that read the name of the most recent action that can be undone or redone and print it next to the Undo or Redo command's caption. If there's no such action, the program will disable the corresponding command. Listing 7.12 is the code that's executed when the Edit menu is dropped.

Private Sub EditToolStripMenuItem_DropDownOpened(...) Handles
                 EditToolStripMenuItem.DropDownOpened
    If Editor.UndoActionName <> "" Then
        UndoToolStripMenuItem.Text =
                     "Undo " & Editor.UndoActionName
        UndoToolStripMenuItem.Enabled = True
    Else
        UndoToolStripMenuItem.Text = "Undo"
        UndoToolStripMenuItem.Enabled = False
    End If
    If Editor.RedoActionName <> "" Then
        RedoToolStripMenuItem.Text =
                     "Redo" & Editor.RedoActionName
        RedoToolStripMenuItem.Enabled = True
    Else
        RedoToolStripMenuItem.Text = "Redo"
        RedoToolStripMenuItem.Enabled = False
    End If
End Sub

When the user selects one of the Undo or Redo commands, the code simply calls the appropriate method from within the menu item's Click event handler, as shown in Listing 7.13.

Private Sub RedoToolStripMenuItem_Click(...) Handles
  RedoToolStripMenuItem.Click
      If Editor.CanRedo Then Editor().Redo()
  End Sub

  Private Sub UndoToolStripMenuItem_Click(...) Handles
  UndoToolStripMenuItem.Click
      If Editor.CanUndo Then Editor.Undo()
  End Sub

Calling the CanUndo and CanRedo method is unnecessary; if the corresponding action can't be performed, the two menu items will be disabled, but an additional check does no harm.

The commands of the Format menu control the alignment and the font attributes of the current selection. The Font command displays the Font dialog box and then assigns the font selected by the user to the current selection. Listing 7.14 shows the code behind the Font command.

Private Sub FontToolStripMenuItem_Click(...) Handles
                      FontToolStripMenuItem.Click
    If Not Editor.SelectionFont Is Nothing Then
         FontDialog1.Font = Editor.SelectionFont
    Else
         FontDialog1.Font = Nothing
    End If
    FontDialog1.ShowApply = True
    If FontDialog1.ShowDialog() = DialogResult.OK Then
         Editor.SelectionFont = FontDialog1.Font
    End If
End Sub

Notice that the code preselects a font in the dialog box, the font of the current selection. If the current selection isn't formatted with a single font, no font is preselected.

To enable the Apply button of the Font dialog box, set the control's ShowApply property to True and insert the following statement in its Apply event handler:

Private Sub FontDialog1_Apply(...) Handles FontDialog1.Apply
    Editor.SelectionFont = FontDialog1.Font
    Editor.SelectionColor = FontDialog1.Color
End Sub

The options of the Align menu set the RichTextBox control's SelectionAlignment property to different members of the HorizontalAlignment enumeration. The Align

Editor.SelectionAlignment = HorizontalAlignment.Left

The Find command in the Edit menu opens the dialog box shown in Figure 7.9, which performs search-and-replace operations (whole-word or case-sensitive match or both). The Search & Replace form (it's the frmFind form in the project) has its TopMost property set to True so that it remains visible while it's open, even if it doesn't have the focus. The code behind the buttons on this form is quite similar to the code for the Find & Replace dialog box of the TextPad application, with one basic difference: the RTFPad project's code uses the RichTextBox control's Find method; the simple TextBox control doesn't provide an equivalent method and we had to use the methods of the String class to perform the same operations. The Find method of the RichTextBox control performs all types of searches, and some of its options are not available with the IndexOf method of the String class.

Figure 7.9. The Search & Replace dialog box of the RTFPad application

To invoke the Search & Replace dialog box, the code calls the Show method of the frmFind form, as discussed in Chapter 5, via the following statement:

frmFind.Show()

The Find method of the RichTextBox control allows you to perform case-sensitive or -insensitive searches as well as search for whole words only. These options are specified through an argument of the RichTextBoxFinds type. The SetSearchMode() function (see Listing 7.15) examines the settings of the two check boxes at the bottom of the form and sets the mode variable, which represents the Find method's search mode.

Function SetSearchMode() As RichTextBoxFinds
    Dim mode As RichTextBoxFinds =
                 RichTextBoxFinds.None
    If chkCase.Checked = True Then
        mode = mode Or RichTextBoxFinds.MatchCase
    End If
    If chkWord.Checked = True Then
        mode = mode Or RichTextBoxFinds.WholeWord
    End If
    Return mode
End Function

The Click event handlers of the Find and Find Next buttons call this function to retrieve the constant that determines the type of search specified by the user on the form. This value is then passed to the Find method. Listing 7.16 shows the code behind the Find and Find Next buttons.

Private Sub bttnFind_Click(...) Handles bttnFind.Click
    Dim wordAt As Integer
    Dim srchMode As RichTextBoxFinds
    srchMode = SetSearchMode()
    wordAt = frmEditor.Editor.Find(
                    txtSearchWord.Text, 0, srchMode)
    If wordAt = −1 Then
        MsgBox("Can't find word")
        Exit Sub
    End If
    frmEditor.Editor.Select(wordAt, txtSearchWord.Text.Length)
    bttnFindNext.Enabled = True
    bttnReplace.Enabled = True
    bttnReplaceAll.Enabled = True
    frmEditor.Editor.ScrollToCaret()
End Sub

Private Sub bttnFindNext_Click(...) Handles bttnFindNext.Click
    Dim selStart As Integer
    Dim srchMode As RichTextBoxFinds
    srchMode = SetSearchMode()
     selStart = frmEditor.Editor.Find(
                  txtSearchWord.Text,
                  frmEditor.Editor.SelectionStart + 2,
                  srchMode)

If selStart = −1 Then
        MsgBox("No more matches")
        Exit Sub
     End If
     frmEditor.Editor.Select(
                  selStart, txtSearchWord.Text.Length)
     frmEditor.Editor.ScrollToCaret()
 End Sub

Notice that both event handlers call the ScrollToCaret method to force the selected text to become visible — should the Find method locate the desired string outside the visible segment of the text.

Let's look now at the process of populating the TreeView control. Adding an initial collection of nodes to a TreeView control at design time is trivial. Locate the Nodes property in the Properties window, and you'll see that its value is Collection. To add items, click the ellipsis button, and the TreeNode Editor dialog box will appear, as shown in Figure 7.15. To add a root item, just click the Add Root button. The new item will be named Node0 by default. You can change its caption by selecting the item in the list and setting its Text property accordingly. You can also change the node's Name property, and you can change the node's appearance by using the NodeFont, FontColor, and ForeColor properties.

Figure 7.15. The TreeNode Editor dialog box

Follow these steps to enter the root node with the string Globe, a child node for Europe, and two more nodes under Europe: Germany and Italy. I'm assuming that you're starting with a clean control. If your TreeView control contains any items, clear them all by selecting one item at a time in the list and pressing the Delete key, or click the delete button (the one with the X icon) on the dialog box.

Click the Add Root button first to add the node Node0. Select it with the mouse, and its properties appear in the right pane of the TreeNode Editor window. Here you can change the node's Text property to Globe. You can specify the appearance of each node by setting its font and fore/background colors.

Then click the Add Child button, which adds a new node under the Globe root node. Select it with the mouse as before, and change its Text property to Europe. Then select the newly added node in the list and click the Add Child button again. Name the new node Germany. You've successfully added a small hierarchy of nodes. To add another node under Europe, select the Europe node in the list and click the Add Child button again. Name the new item Italy. Continue adding a few cities under each country to complete the tree.

Click the OK button to close the TreeNode Editor's window and return to your form. The nodes you added to the TreeView control are there, but they're collapsed. Only the root nodes are displayed with the plus sign in front of their names. Click the plus sign to expand the tree and see its child nodes. The TreeView control behaves the same at design time as it does at runtime — as far as navigating the tree goes, at least.

Adding items to the control at runtime is a bit more involved. All the nodes belong to the control's Nodes collection, which is made up of TreeNode objects. To access the Nodes collection, use the following expression, where TreeView1 is the control's name and Nodes is a collection of TreeNode objects:

TreeView1.Nodes

This expression returns a collection of TreeNode objects and exposes the proper members for accessing and manipulating the individual nodes. The control's Nodes property is the collection of all root nodes.

The following statements print the strings shown highlighted below them (these strings are not part of the statements; they're the output that the statements produce):

Debug.WriteLine(TreeView1.Nodes(0).Text)
Globe
Debug.WriteLine(TreeView1.Nodes(0).Nodes(0).Text)
Europe
Debug.WriteLine(TreeView1.Nodes(0).Nodes(0).Nodes(1).Text)
Italy

newNode = Nodes.Add(nodeCaption)

newNode = Nodes.Add(nodeObj)

Dim nodeObj As New TreeNode
nodeObj.Text = "Tree Node"
nodeObj.ForeColor = Color.BlueViolet
TreeView1.Nodes.Add(nodeObj)

newNode = Nodes.Add(index, nodeObj)

TreeView1.Nodes(0).Nodes.Add("Asia")

TreeView1.Nodes(0).Nodes(1).Nodes.Add("Japan")

Dim ContinentNode As TreeNode
ContinentNode = TreeView1.Nodes(0).Nodes(2)

ContinentNode.Nodes.Add("France")
ContinentNode.Nodes.Add("Germany")

Dim CountryNode As TreeNode
CountryNode = ContinentNode.Nodes.Add("Germany")
CountryNode.Nodes.Add("Berlin")
CountryNode.Nodes.Add("Frankfurt")

To display items in Details view, you must first set up the appropriate columns. The first column corresponds to the item's caption, and the following columns correspond to its subitems. If you don't set up at least one column, no items will be displayed in Details view. Conversely, the Columns collection is meaningful only when the ListView control is used in Details view.

The items of the Columns collection are of the ColumnHeader type. The simplest way to set up the appropriate columns is to do so at design time by using a visual tool. Locate and select the Columns property in the Properties window, and click the ellipsis button next to the property. The ColumnHeader Collection Editor dialog box, shown in Figure 7.16, will appear, and you can use it to add and edit the appropriate columns.

Adding columns to a ListView control and setting their properties through the dialog box shown in Figure 7.16 is quite simple. Don't forget to size the columns according to the data you anticipate storing in them and to set their headers. You can also add columns from within your code at runtime, a topic that's discussed in the tutorial "The ListView and TreeView Controls," available for download from www.sybex.com/go/masteringvb2010.

Figure 7.16. The ColumnHeader Collection Editor dialog box

As with the TreeView control, the ListView control can be populated either at design time or at runtime. To add items at design time, click the ellipsis button next to the ListItems property in the Properties window. When the ListViewItem Collection Editor dialog box pops up, you can enter the items, including their subitems, as shown in Figure 7.17.

Figure 7.17. The ListViewItem Collection Editor dialog box

Click the Add button to add a new item. Each item has subitems, which you can specify as members of the SubItems collection. To add an item with three subitems, you must populate the item's SubItems collection with the appropriate elements. Click the ellipsis button next to the SubItems property in the ListViewItem Collection Editor; the ListViewSubItem Collection Editor will appear. This dialog box is similar to the ListViewItem Collection Editor dialog box, and you can add each item's subitems. Assuming that you have added the item called Item 1 in the ListViewItem Collection Editor, you can add these subitems: Item 1-a, Item 1-b, and Item 1-c. The first subitem (the one with zero index) is actually the main item of the control.

Notice that you can set other properties such as the color and font for each item, the check box in front of the item that indicates whether the item is selected, and the image of the item. Use this window to experiment with the appearance of the control and the placement of the items, especially in Details view because subitems are visible only in this view. Even then, you won't see anything unless you specify headers for the columns. Note that you can add more subitems than there are columns in the control. Some of the subitems will remain invisible.

Unlike the TreeView control, the ListView control allows you to specify a different appearance for each item and each subitem. To set the appearance of the items, use the Font, BackColor, and ForeColor properties of the ListViewItem object.

All the items on the ListView control form a collection: the Items collection. This collection exposes the typical members of a collection that let you manipulate the control's items. These members are discussed next.

Each item in the ListView control may have one or more subitems. You can think of the item as the key of a record and the subitems as the other fields of the record. The subitems are displayed only in Details mode, but they are available to your code in any view. For example, you can display all items as icons and, when the user clicks an icon, show the values of the selected item's subitems on other controls.

To access the subitems of a given item, use its SubItems collection. The following statements add an item and three subitems to the ListView1 control:

Dim LItem As ListViewItem
LItem = ListView1.Items.Add("Alfred's Futterkiste")
LItem.SubItems.Add("Maria Anders")
LItem.SubItems.Add("030-0074321")
LItem.SubItems.Add("030-0076545")

To access the SubItems collection, you need a reference to the item to which the subitems belong. The Add method returns a reference to the newly added item, the LItem variable, which is then used to access the item's subitems, as shown in the preceding code segment.

Displaying the subitems on the control requires some overhead. Subitems are displayed only in Details view mode. However, setting the View property to Details is not enough. You must first create the columns of the Details view, as explained earlier. The ListView control displays only as many subitems as there are columns in the control. The first column, with the header Company, displays the items of the list. The following columns display the subitems. Moreover, you can't specify which subitem will be displayed under each header. The first subitem (Maria Anders in the preceding example) will be displayed under the second header, the second subitem (030-0074321 in the same example) will be displayed under the third header, and so on. At runtime, the user can rearrange the columns by dragging them with the mouse. To disable the rearrangement of the columns at runtime, set the control's AllowColumnReorder property to False (its default value is True).

Unless you set up each column's width, they will all have the same width. The width of individual columns is specified in pixels, and you can set it to a percentage of the total width of the control, especially if the control is docked to the form. The following code sets up a ListView control with four headers, all having the same width:

Dim LWidth = ListView1.Width - 5
Dim headers =
    {
        New ColumnHeader() With {.Text = "Company", .Width = LWidth / 4},
        New ColumnHeader() With {.Text = "Contact", .Width = LWidth / 4},
        New ColumnHeader() With {.Text = "Phone", .Width = LWidth / 4},
        New ColumnHeader() With {.Text = "Fax", .Width = LWidth / 4}
    }
ListView1.Columns.AddRange(headers)
ListView1.View = View.Details

The first header corresponds to the item (not a subitem). The number of headers you set up must be equal to the number of subitems you want to display on the control, plus one. The constant 5 is subtracted to compensate for the width of the column separators. If the control is anchored to the vertical edges of the form, you must execute these statements from within the form's Resize event handler so that the columns are resized automatically as the control is resized.

You can also sort a ListView control with the Sort method, which sorts the list's items, and the Sorting property, which determines how the items will be sorted. For more information on sorting the control's items, see the tutorial "The ListView and TreeView Controls," available for download from www.sybex.com/go/masteringvb2010.

The user can select multiple items from a ListView control by default. Even though you can display a check mark in front of each item, it's not customary. Multiple items in a ListView control are selected with the mouse while holding down the Ctrl or Shift key.

The selected items form the SelectedListItemCollection collection, which is a property of the control. You can iterate through this collection with a For ... Next loop or through the enumerator object exposed by the collection. Listing 7.17 is the code behind the Selected Items button of the ListViewDemo project. It goes through the selected items with a For Each ... Next loop and displays each one of them, along with its subitems, in the Output window. Notice that you can select multiple items in any view, even when the subitems are not visible. They're still there, however, and they can be retrieved through the SubItems collection.

Private Sub bttnIterate_Click(...) Handles bttnIterate.Click
    Dim LItem As ListViewItem
    Dim LItems As ListView.SelectedListViewItemCollection
    LItems = ListView1.SelectedItems
    For Each LItem In LItems
        Debug.Write(LItem.Text & vbTab)
        Debug.Write(LItem.SubItems(0).ToString & vbTab)
        Debug.Write(LItem.SubItems(1).ToString & vbTab)
        Debug.WriteLine(LItem.SubItems(2).ToString & vbTab)
    Next
End Sub