Many controls in Windows Forms 2.0 display a small triangle, or glyph, toward the top, right side of the control when highlighted in the visual designer. This is a new feature called a smart tag. If you click this glyph, you get a pop-up dialog with common operations for the control. Many of the features that you access through the property box can also be accessed through the smart tag. In general, this chapter uses the Properties window for manipulating properties, but you should be aware of the smart tag shortcut for commonly used features.

Text boxes and combo boxes have new properties for autocompletion of text entries. This capability could be added manually or with third-party controls in previous versions, but is now built in. The AutoCompleteMode property controls how autocompletion works in the control, while the AutoCompleteSource and AutoCompleteCustomSource properties tell the control where to get entries for autocompletion.

An example of autocompletion in action is shown later, in the section entitled "Advanced Capabilities for Data Entry."

The base Control class, which is a base class for all Windows Forms controls, has several new properties in Windows Forms 2.0. Because all controls inherit from this class, all Windows Forms controls gain these new properties and the new functionality that goes along with them.

Two of the new properties, Padding and Margin, are most useful when used in conjunction with some new controls, TableLayoutPanel and FlowLayoutPanel. Those two properties are discussed later in the chapter. The other new properties are discussed here. They include MaximumSize, MinimumSize, and UseWaitCursor.

The MaximumSize and MinimumSize properties specify the control's maximum and minimum height and width, respectively. Forms had these properties in Windows Forms 1.0 and 1.1, but now all controls have them.

If the maximum height and width are both set to the default value of 0, then there is no maximum. Similarly, if the minimum height and width are set to zero, then there is no minimum. The form or control can be any size.

If these properties are set to anything else, then the settings become limits on the size of the control. For example, if the MaximumSize height and width are both set to 100, then the control cannot be bigger than 100 × 100 pixels. The visual designer will not make the control any larger on the form design surface. Attempting to set the height or width of the control in code at runtime to a value greater than 100 will cause it to be set to 100 instead.

The MaximumSize and MinimumSize properties can be reset at runtime to enable sizing of the controls outside the limits imposed at design time. However, the properties have a return type of Size, so resetting either property requires creating a Size structure. For example, you can reset the MinimumSize property for a button named Button1 with the following line of code:

Button1.MinimumSize = New Size(20, 20)

This sets the new minimum width and height to 20 pixels.

The Size structure has members for Height and Width, which can be used to fetch the current minimum or maximum sizes for either height or width. For example, to find the current minimum height for Button1, use the following line of code:

Dim n As Integer = Button1.MinimumSize.Height

Windows Forms interfaces can use threading or asynchronous requests to allow tasks to execute in the background. When a control is waiting for an asynchronous request to finish, it is helpful to indicate that to the user by changing the mouse cursor when the mouse is inside the control. Normally, the cursor used is the familiar hourglass, which is called the WaitCursor in Windows Forms.

For any control, setting the UseWaitCursor property to True causes the cursor to change to the hourglass (or whatever is being used for the WaitCursor) while the mouse is positioned inside the control. This allows a control to visually indicate that it is waiting for something. The typical usage is to set UseWaitCursor to True when an asynchronous process is begun and then set it back to False when the process is finished and the control is ready for normal operation again.

Even smart client applications often need to display HTML or browse websites. Windows Forms 1.0 or 1.1 did not include a true Windows Forms control for browsing. The legacy ActiveX browsing control built into Windows could be used via interoperability, but this had drawbacks for deployment and versioning.

The legacy ActiveX control is still the ultimate foundation for browsing capability, but Windows Forms 2.0 includes an intelligent Windows Forms wrapper that makes it much easier to use and deploy the control.

Windows Forms 1.0 offered replacements for almost all of the controls available in Visual Basic 6, but one notable exception was the MaskedEdit control. In Windows Forms 1.0 and 1.1, masked edit capabilities were available only through third-party controls or by doing your own custom development.

That omission has now been rectified. The MaskedTextbox control resembles the old MaskedEdit control in functionality. It allows a mask for input and a variety of useful properties to control user interaction with the control. More information on this control is available in the section "Advanced Capabilities for Data Entry."

Browser-based user interfaces are good at dynamically arranging controls at runtime, because browser windows can be different sizes for different users. Forms-based interfaces have traditionally lacked such capabilities. Dynamic positioning can be done in forms, but it requires writing a lot of sizing and positioning logic.

Two new controls in Windows Forms 2.0 mimic layout capabilities in a browser, offering better options for dynamic positioning of controls: FlowLayoutPanel and TableLayoutPanel. Both are containers than can automatically reposition controls that are placed in them, based on the current space available in the container.

An example illustrating usage of both controls is included in the section "Dynamic Sizing and Positioning of Controls."

In the owner form, another form can be made owned with the AddOwnedForm method. The following code makes an instance of Form2 become owned by Form1. This code would reside somewhere in Form1 and would typically be placed just before the line that shows the instance of Form2 to the screen:

Dim frm As New Form2
Me.AddOwnedForm(frm)

The relationship can also be set up in the owned form. This is done with the Owner property of the form. Here is a method that would work inside Form2 to make it owned by a form that is passed in as an argument to the function:

Public Sub MakeMeOwned(frmOwner As Form)
    Me.Owner = frmOwner
End Sub

Because this technique requires a reference to the owner inside the owned form, it is not used as often as using the AddOwnedForm method in the Owner form.

The owner form can access its collection of owned forms with the OwnedForms property. Here is code to loop through the forms owned by a form:

Dim frmOwnedForm As Form
For Each frmOwnedForm In Me.OwnedForms
  Console.WriteLine(frmOwnedForm.Text)
Next

The owner form can remove an owned form with the RemoveOwnedForm property. This could be done in a loop like the previous example, with code like the following:

Dim frmOwnedForm As Form
For Each frmOwnedForm In Me.OwnedForms
  Console.WriteLine(frmOwnedForm.Text)
  Me.RemoveOwnedForm(frmOwnedForm)
Next

This loop would cause an owner form to stop owning all of its slaved forms. Note that those "deslaved" forms would not be unloaded, they would simply no longer be owned.

The Opacity property measures how opaque or transparent a form is. A value of 0 percent makes the form fully transparent. A value of 100 percent makes the form fully visible. Any value greater than 0 and less than 100 makes the form partially visible, as if it were a ghost. Note that an opacity value of 0 percent disables the capability to click the form.

Very low levels of opacity, in the range of 1 or 2 percent, make the form effectively invisible, but still allow the form to be clickable. This means that the Opacity property has the potential to create mischievous applications that sit in front of other applications and "steal" their mouse clicks and other events.

Tool and dialog windows that should not completely obscure their background are one example of a usage for Opacity. Setting expiration for a "free trial" by gradually fading out the application's user interface is another.

The following block of code shows how to fade a form out and back in when the user clicks a button named Button1. You may have to adjust the Step value of the array, depending on your computer's performance:

Private Sub Button1_Click(ByVal sender As System.Object, _
                          ByVal e As System.EventArgs) _
                          Handles Button1.Click
   Dim i As Double
   For i = −1 To 1 Step 0.005
     ' Note - opacity is a value from 0.0 to 1.0 in code
     ' Absolute value is used to keep us in that range
     Me.Opacity = System.Math.Abs(i)
     Me.Refresh
   Next i
End Sub

Instead of making an entire form translucent or transparent, the TransparencyKey property enables you to specify a color that will become transparent on the form. This enables you to make some sections of a form transparent, while other sections are unchanged.

For example, if TransparencyKey is set to a red color and some areas of the form are that exact shade of red, then they will be transparent. Whatever is behind the form shows through in those areas; and if you click in one of those areas, you are actually clicking the object behind the form.

TransparencyKey can be used to create irregularly shaped "skin" forms. A form can have its BackgroundImage property set with an image, and by just painting a part of the image with the TransparencyKey color, you can make parts of the form disappear.

Another way to gain the capability of "skins" is by using the Region property of a form. The Region property allows a shape for a form to be encoded as a "graphics path," thereby changing the shape from the default rectangle to another shape. A path can contain line segments between points, curves, and arcs, and outlines of letters, in any combination.

The following example changes the shape of a form to an arrow. Create a new Windows application. Set the FormBorderStyle property of Form1 to None. Then place the following code in the Load event for Form1:

Dim PointArray(6) As Point
PointArray(0) = New Point(0, 40)
PointArray(1) = New Point(200, 40)
PointArray(2) = New Point(200, 0)
PointArray(3) = New Point(250, 100)
PointArray(4) = New Point(200, 200)
PointArray(5) = New Point(200, 160)
PointArray(6) = New Point(0, 160)
Dim myGraphicsPath As _
System.Drawing.Drawing2D.GraphicsPath = _
        New System.Drawing.Drawing2D.GraphicsPath

myGraphicsPath.AddPolygon(PointArray)
Me.Region = New Region(myGraphicsPath)

When the program is run, Form1 will appear in the shape of a right-pointing arrow. If you lay out the points in the array, you will see that they have become the vertices of the arrow.

In Windows Forms, a regular form is converted to an MDI parent form by setting the IsMDIContainer property of the form to True. This is normally done in the Properties window at design time.

A form can also be made into an MDI parent at runtime by setting the IsMDIContainer property to True in code, but the design of an MDI form is usually different from that of a normal form, so this approach is not often needed.

In VB6, an MDI parent form can only contain controls that have a property called Align, which is similar to the Dock property in Windows Forms. These controls, such as a PictureBox, can then contain other controls.

In Windows Forms, an MDI parent can contain any control that a regular form can contain. Buttons, labels, and the like can be placed directly on the MDI surface. Such controls appear in front of any MDI child forms that are displayed in the MDI client area.

It is still possible to use controls such as PictureBoxes to hold other controls on a Windows Forms MDI parent. These controls can be docked to the side of the MDI form with the Dock property, which is discussed in the section "Dynamic Sizing and Positioning of Controls."

In Windows Forms, a form becomes an MDI child at runtime by setting the form's MDIParent property to point to an MDI parent form. This makes it possible to use a form as either a standalone form or an MDI child in different circumstances. In fact, the MDIParent property cannot be set at design time — it must be set at runtime to make a form an MDI child. (Note that this is completely different from VB6, where it was necessary to make a form an MDI child at design time.)

Any number of MDI child forms can be displayed in the MDI parent-client area. The currently active child form can be determined with the ActiveForm property of the MDI parent form.

MDI parent forms have a method called LayoutMDI that automatically arranges child forms in the familiar cascade or tile layout. For the preceding example, add a menu item to your Windows menu called Tile Vertical and insert the following code into the menu item's Click event to handle it:

Me.LayoutMdi(MDILayout.TileVertical)

To see an example of the rearrangement, suppose that the MDI form in Figure 15-2 is rearranged with the MDILayout.TileVertical option. It would then look similar to the image in Figure 15-3.

When showing a dialog form, you'll often need to get information about what action the user selected. This was often done with a custom property in VB6, but Windows Forms has a built-in property for that purpose. When a form is shown with the ShowDialog method, the form has a property called DialogResult to indicate its state.

The DialogResult property can take the following enumerated results:

When the DialogResult property is set, the dialog is hidden as a byproduct. That is, setting the DialogResult property causes an implicit call to the Hide method of the dialog form, so that control is released back to the form that called the dialog.

The DialogResult property of a dialog box can be set in two ways. The most common way is to associate a DialogResult value with a button. Then, when the button is pressed, the associated value is automatically placed in the DialogResult property of the form.

To set the DialogResult value associated with a button, the DialogResult property of the button is used. If this property is set for the button, then it is unnecessary to set the DialogResult in code when the button is pressed.

Here is an example that uses this technique. In Visual Studio 2008, start a new VB Windows application. On the automatic blank form that comes up (named Form1), place a single button and set its Text property to Dialog.

Now add a new Windows form by selecting Project

Do not put any code in DialogForm at all. The form should look like the one shown in Figure 15-4.

Figure 15.4. Figure 15-4

On the first form, Form1, place the following code in the Click event for Button1:

Private Sub Button1_Click(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles Button1.Click
   Dim frmDialogForm As New DialogForm()
   frmDialogForm.ShowDialog()

   ' You're back from the dialog - check user action.
   Select Case frmDialogForm.DialogResult
     Case DialogResult.OK
       MsgBox("The user pressed OK")
     Case DialogResult.Cancel
       MsgBox("The user pressed cancel")
   End Select
   frmDialogForm = Nothing
End Sub

Run and test the code. When a button is pressed on the dialog form, a message box should be displayed (by the calling form) indicating the button that was pressed.

The second way to set the DialogResult property of the form is in code. In a Button_Click event, or anywhere else in the dialog form, a line like the following can be used to set the DialogResult property for the form and simultaneously hide the dialog form, returning control to the calling form:

Me.DialogResult = DialogResult.Ignore

This particular line sets the dialog result to DialogResult.Ignore, but setting the dialog result to any of the permitted values also hides the dialog form.

Docking refers to gluing a control to the edge of a parent control. Good examples of docked controls are menu bars and status bars, which are typically docked to the top and bottom of a form, respectively. All visual controls have a Dock property.

To work through an example, create a new Windows application and place a Textbox on a form. Set the Text property of the TextBox to I'm Getting Docked. The result when you show the form should look something like Figure 15-6.

Figure 15.6. Figure 15-6

Suppose that you need to glue this TextBox to the top of the form. To do this, view the Dock property of the label. If you pull it down, you'll see a small graphic like the one shown in Figure 15-7.

Figure 15.7. Figure 15-7

Simply click the top section of the graphic to stick the label at the top of the form. The other sections give you other effects. (A status bar would use the bottom section, for example. Clicking the box in the middle causes the control to fill the form.) The TextBox control will immediately "stick" to the top of your form. When you run your program and stretch the window sideways, you'll see the effect shown in Figure 15-8.

Figure 15.8. Figure 15-8

If you want a gap between the edge of your form and the docked controls, set the DockPadding property of the parent control. You can set a different value for each of the four directions (Left, Right, Top, Bottom). You can also set all four properties to the same value using the All setting.

Anchoring is similar to docking except that you can specifically define the distance that each edge of your control will maintain from the edges of a parent. To see it in action, add a button to the form in the docking example. The result should look like what is shown in Figure 15-9.

Figure 15.9. Figure 15-9

Dropping down the Anchor property of the button gives you the graphic shown in Figure 15-10.

Figure 15.10. Figure 15-10

The four rectangles surrounding the center box enable you to toggle the anchor settings of the control. Figure 15-10 shows the default anchor setting of Top, Left for all controls.

When the setting is on (dark gray), the edge of the control maintains its original distance from the edge of the parent as the parent is resized. If you set the anchor to two opposing edges (such as the left and right edges), the control stretches to accommodate this, as shown in Figure 15-11.

Figure 15.11. Figure 15-11

One of the most common uses of anchoring is to set the Anchor property for buttons in the lower-right portion of a form. Setting the Anchor property of a button to Bottom, Right causes the button to maintain a constant distance from the bottom-right corner of the form.

You can also set the Anchor property in code. The most common scenario for this would be for a control created on-the-fly. To set the Anchor property in code, you must add the anchor styles for all the sides to which you need to anchor. For example, setting the Anchor property to Bottom, Left would require a line of code like this:

MyControl.Anchor = Ctype(AnchorStyles.Bottom + AnchorStyles.Right, AnchorStyles)

Early versions of Windows Forms used the Splitter control to allow resizing of containers. This control is still available in Windows Forms 2.0, but it doesn't appear by default in the Toolbox. In its place is a replacement control, SplitContainer, that provides the same functionality with less work on your part.

A single SplitContainer acts much like two panels with an appropriately inserted Splitter. You can think of it as a panel with two sections separated by a movable divider so that the relative sizes of the sections can be changed by a user.

To use a SplitContainer, simply drop it on a form, resize it, and position the draggable divider to the appropriate point. If you want the divider to be horizontal instead of vertical, you change the Orientation property. Then you can place controls in each subpanel in any way you like. It is common to insert a control such as a TreeView or ListBox, and then dock it to its respective subpanel. This enables users to resize such contained controls. A typical example of a SplitContainer in action is shown in Figure 15-12.

Figure 15.12. Figure 15-12

The cursor in Figure 15-12 shows that the mouse is hovering over the divider, allowing repositioning of the divider by dragging the mouse. A SplitContainer may be nested inside another SplitContainer. This enables you to build forms in which several parts are resizable relative to each other.

To assist in positioning controls in the FlowLayoutPanel, all controls have a new property called Margin. There are settings for Margin.Left, Margin.Right, Margin.Top, and Margin.Bottom. These settings determine how much space is reserved around a control when calculating its automatic position in a FlowLayoutPanel.

You can see the Margin property in action by changing the Margin property for one or more of the buttons in the previous example. If you change all the Margin settings for the first Button to 10 pixels, for example, and run the application, the form will look like the one shown in Figure 15-15.

Figure 15.15. Figure 15-15

The first button now has a 10-pixel separation from all the other controls in the FlowLayoutPanel, as well as a 10-pixel separation from the edges of the FlowLayoutPanel itself.

The Padding property is for the FlowLayoutPanel or other container control. When a control is embedded into a FlowLayoutPanel, the Padding.Left, Padding.Right, Padding.Top, and Padding.Bottom properties of the FlowLayoutPanel determine how far the control should be positioned from the inside edge of the container.

You can see the Padding property in action by changing the Padding property for the FlowLayoutPanel in the previous example. If you set all Padding settings to 20 pixels, and reset the Margin property for the first Button back to the default, then the form will look like what is shown in Figure 15-16 in the visual designer.

Figure 15.16. Figure 15-16

Notice that all the controls in the FlowLayoutPanel are now at least 20 pixels from the edges.

The Padding property is also applicable to other container controls, if the contained controls have their Dock property set. If the settings for Padding are not zero, then a docked control will be offset from the edge of the container by the amount specified by the Padding property.

The ToolTip is the simplest of the built-in extender providers. It adds just one property to each control: ToolTip on ToolTip1 (assuming the ToolTip control has the default name of ToolTip1). This property works in very much the same way the ToolTipText property works in VB6, and in fact replaces it.

To see this in action, create a Windows Forms application. On the blank Form1 that is created for the project, place a couple of buttons. Take a look at the Properties window for Button1. Notice that it does not have a ToolTip property of any kind.

Drag over the ToolTip control, which will be placed in the component tray. Go back to the Properties window for Button1. A property named ToolTip on ToolTip1 is now present. Set any string value you like for this property.

Run the project and hover the mouse pointer over Button1. You will see a tooltip containing the string value you entered for the ToolTip on ToolTip1 property.

Other properties of the ToolTip component enable you to control other characteristics of the tooltip, such as the initial delay before the tooltip appears.

New in Windows Forms 2.0 is the capability to change the shape of tooltips to a "balloon." This is done by setting the IsBalloon property of the Tooltip component to True. Instead of a hovering rectangular tooltip, the tooltip has a rounded rectangular outline with a pointer to the control it is associated with, not unlike the dialog balloons in a comic strip. Figure 15-19 shows an example.

Figure 15.19. Figure 15-19

The HelpProvider enables controls to have associated context-sensitive help available by pressing F1. When a HelpProvider is added to a form, all controls on the form get the following new properties, which show up in the controls' Properties window:

Filling in the HelpString property immediately causes the control to provide tooltip help when F1 is pressed while the control has the focus. The HelpProvider control has a property to point to a help file (either an HTML help file or a Win32 help file), and the help topic in the HelpTopic property points to a topic in this file.

The ErrorProvider component presents a simple, visual way to indicate to a user that a control on a form has an error associated with it. The added property for controls on the form when an ErrorProvider is used is called Error on ErrorProvider1 (assuming the ErrorProvider has the default name of ErrorProvider1). Setting this property to a string value causes the error icon to appear next to a control. In addition, the text appears in a tooltip if the mouse hovers over the error icon.

Figure 15-20 shows a screen with several text boxes, and an error icon next to one (with a tooltip). The error icon and tooltip are displayed and managed by an ErrorProvider.

Figure 15.20. Figure 15-20

The ErrorProvider component's default icon is a red circle with an exclamation point. When the Error property for the text box is set, the icon blinks for a few moments, and hovering over the icon causes the tooltip to appear. Writing your own code to set the Error property is explained in the section "Working with Extender Providers in Code."

In addition to providing other controls with properties, extender providers also have properties of their own. For example, the ErrorProvider has a property named BlinkStyle. When it is set to NeverBlink, the blinking of the icon is stopped for all controls affected by the ErrorProvider.

Other properties of the ErrorProvider enable you to change things such as the icon used and where the icon appears in relation to the field containing the error. For instance, you might want the icon to appear on the left side of a field instead of the default right side. You can also have multiple error providers on your form. For example, you might wish to give users a warning, rather than an error. A second error provider with a yellow icon could be used for this feature.

Setting the Error property in the previous example can be done with the Properties window, but this is not very useful for on-the-fly error management. However, setting the Error property in code is not done with typical property syntax. By convention, extender providers have a method for each extended property they need to set, and the arguments for the method include the associated control and the property setting. To set the Error property in the previous example, the following code was used:

ErrorProvider1.SetError(txtName, "You must provide a location!")

The name of the method to set a property is the word Set prefixed to the name of the property. The preceding line of code shows that the Error property is set with the SetError method of the ErrorProvider.

There is a corresponding method to get the value of the property, and it is named with Get prefixed to the name of the property. To determine the current Error property setting for txtName, you would use the following line:

sError = ErrorProvider1.GetError(txtName)

Similar syntax is used to manipulate any of the properties managed by an extender provider. The discussion of the tooltip provider earlier mentioned setting the tooltip property in the Properties window. To set that same property in code, the syntax would be as follows:

ToolTip1.SetToolTip(Button1, "New tooltip for Button1")

Responsive user interfaces help users accomplish their purposes, thereby making them more productive. One classic way to do this is with autocompletion.

An example of autocompletion is IntelliSense in Visual Studio. Using IntelliSense, the user only has to type in a few letters, and Visual Studio presents a list of probable entries matching those letters. If the desired entry is found, the user only needs to select it, rather than type the entire entry.

Autocompletion is available in Windows Forms 2.0 with text boxes and combo boxes. Both use a set of properties to control how autocompletion works and from where the list of entries available to the user comes.

To see autocompletion in action, create a Windows application project. Drag a Textbox from the toolbox onto the blank Form1 created for the project. Set the AutoCompleteMode for the text box to Suggest in the Properties window. Then set the AutoCompleteSource to CustomSource. Finally, click the button in the setting window for AutoCompleteCustomSource. You'll see a window for adding entries that is very similar to the window for entering items for a list box or combo box.

Enter the following items into the dialog:

Holder
Holland
Hollis
Holloway
Holly
Holstein
Holt

Start the project and type Hol into the text box. As soon as you start typing, a drop-down will appear that contains entries matching what you've typed, including all seven elements in the list. If you then type another 1, the list will decrease to four elements that begin with Holl. If you then type an o, the list will contain only the entry Holloway.

The AutoCompleteMode has two other modes. The Append mode does not automatically present a drop-down, but instead appends the rest of the closest matching entry to the text in the Textbox or ComboBox, and highlights the untyped characters. This allows the closest matching entry to be placed in the text area without the user explicitly selecting an entry.

The SuggestAppend mode combines Suggest and Append. The current best match is displayed in the text area, and the drop-down with other possibilities is automatically displayed. This mode is the one most like IntelliSense.

You can also set the list of items to be included in the autocompletion list at runtime, which is the most common usage scenario. A list of items from a database table would typically be loaded for autocompletion. Here is typical code to create a list of items and attach the list to a combo box:

Dim autoCompleteStringCollection1 As New AutoCompleteStringCollection
Dim nReturn As Integer
nReturn = autoCompleteStringCollection1.Add("Holder")
nReturn = autoCompleteStringCollection1.Add("Holland")
nReturn = autoCompleteStringCollection1.Add("Hollis")
nReturn = autoCompleteStringCollection1.Add("Holloway")
ComboBox1.AutoCompleteCustomSource = autoCompleteStringCollection1

For this sample to work properly, the Combobox control's AutoCompleteSource property must be set to CustomSource.

Several built-in lists are available for use with autocompletion. Instead of setting AutoCompleteSource to CustomSource, you can set it to sources such as files in the file system, or URLs recently used in Internet Explorer. See the documentation for AutoCompleteSource for additional options; or, if you are using AutoCompleteSource in code, IntelliSense will show the options available.

The MaskedTextbox control fulfills the same function as the old VB6 MaskedEdit control. If you have used MaskedEdit in VB6, the MaskedTextbox will feel quite familiar.

After dragging a MaskedTextbox control to a form, you typically want to first set the mask associated with the control. You can do this in the Properties window by selecting the Mask property, but you can also click the smart tag (right-pointing arrow) on the right side of the MaskedTextbox. In either case, you can either construct a mask manually or select one of the commonly used masks from a list.

If you need to create your own mask, you need to design it based on the following set of formatting characters:

Literal characters are simply inserted automatically by the MaskedTextbox control. If you have literal characters for the parentheses in a phone number, for example, the user need not type these in order for them to show up in the text area of the control.

As an example of a mask, suppose that you have an account number that must consist of exactly two uppercase letters and five digits. You could construct a mask of >??00000. The first character forces all letters to uppercase. The two question marks specify two required alphabetic characters, and the five zeros specify five required digits.

Once you have set the Mask for the MaskedTextbox, all entries in the control will be coerced to the Mask pattern. Keystrokes that don't conform will be thrown away.

The Validating event fires when your control begins its validation. It is here that you need to place the code that validates your control, and set a visual indication for an error. Insert the following code to see this in action:

Private Sub UserNameTextBox_Validating(ByVal sender As Object, _
                            ByVal e As System.ComponentModel.CancelEventArgs) _
                            Handles UserNameTextBox.Validating
    If userNameTextbox.Text = "" Then
        ErrorProvider1.SetError(UserNameTextBox, "User Name cannot be blank")
    Else
        ErrorProvider1.SetError(UserNameTextBox, "")
    End If
End Sub

Private Sub PasswordTextBox_Validating(ByVal sender As Object, _
                           ByVal e As System.ComponentModel.CancelEventArgs) _
                           Handles PasswordTextBox.Validating
    If passwordTextbox.Text = "" Then
        ErrorProvider1.SetError(PasswordTextBox, "Password cannot be blank")
    Else
        ErrorProvider1.SetError(PasswordTextBox, "")
    End If
End Sub

Run the program and then tab between the controls without entering any text to get the error message. You'll see an icon blink next to each of the text box controls; and if you hover over an error icon, you'll see the appropriate error message.

There is also a Validated event that fires after a control's Validating event. It can be used, for example, to do a final check after other events have manipulated the contents of the control.

The CausesValidation property determines whether the control will participate in the validation events on the form. A control with a CausesValidation setting of True (it is True by default) has two effects:

It is important to understand that the validation events fire for a control not when the focus is lost but when the focus shifts to a control that has a CausesValidation value of True.

To see this effect, set the CausesValidation property of the password text box in your application to False (be sure to leave it True for the user ID and OK button). When you run the program, tab off the user ID text box and again to the OK button. Notice that it isn't until the focus reaches the OK button that the validating event of the user ID text box fires. Also notice that the validating event of the Password field never fires.

Ultimately, if you determine that the control is not valid, you need to specify what happens. That may include setting the focus to the control that needs attention (as well as indicating the error with an ErrorProvider).

Try an example to see how to build a toolbar using the ToolStrip control. Create a new Windows application. Add a ToolStrip control to the blank Form1 that is included with the new project. Make the form about twice its default width so that you have plenty of room to see the ToolStrip as you work on it.

The ToolStrip is positioned at the top of the form by default. It does not contain any elements, although if you highlight the ToolStrip control in the component tray, a "menu designer" will appear in the ToolStrip.

The easiest way to add multiple elements to the ToolStrip is to use the designer dialog for the ToolStrip. Highlight the ToolStrip in the component tray and click the button in the Properties window for the Items property. You'll see a designer dialog like the one shown in Figure 15-22.

Figure 15.22. Figure 15-22

The drop-down in the upper-left corner contains the different types of items that can be placed on the toolbar. The names in the drop-down are the same as the names in the table of controls except that the "Toolstrip" prefix is not present. Add one each of the following types, with the setting specified:

Click OK. The ToolStrip will look like the one shown in Figure 15-23.

You can now handle events on any of these toolbar elements the same way you would any other controls. You can double-click to get a Click event routine or access the event routines through the drop-downs in the Code Editor.

To make the Toolstrip more dynamic, it must be embedded in a ToolStripContainer. You can do that manually by dragging one over and putting the Toolstrip in it, but the easy way to do it is to click the smart tag on the Toolstrip and then select Embed in ToolStripContainer. This causes a ToolStripContainer to appear on your form. Set the Dock property for the ToolStripContainer to Fill and it will provide a surface for the Toolstrip that includes all four edges of the form.

Run your program. Using the mouse, grab the dotted handle on the far left edge of the toolbar. If you drag this to the right, then the toolbar will be repositioned. If you drag it to other positions on the form, then the entire toolbar will dock to different edges of the form.

Figure 15.23. Figure 15-23

By default, the AllowItemReorder property of the ToolStrip is set to False. If you change that to True, then the elements on the toolbar can be moved around in relation to one another (reordered) at runtime.

Change the AllowItemReorder property to True for the ToolStrip and run your program again. Hold down the Alt key and drag elements on the toolbar around. They will assume new positions on the toolbar when you drop them.

If you need a toolbar that has the typical visual elements for cut, copy, paste, and so on, it is not necessary to create the elements. The designer will do it for you.

Create a new form in your project and drag a ToolStrip onto it. As before, it will be positioned at the top and will not contain any elements. With the ToolStrip highlighted in the component tray, click the Item property. Below the properties in the Properties window, a link named Insert Standard Items will appear. Click that link; elements will be inserted into the ToolStrip, making it look like the one shown in Figure 15-24.

Figure 15.24. Figure 15-24

If your form's menu needs to have the standard top-level options (File, Edit, and so on) and the typical options under these items, then you can have all these usual options inserted for you automatically.

To see this capability in action, drag a MenuStrip to a form and then click the smart tag (the right arrow at the right edge) for the MenuStrip to bring up the designer dialog. Click the Insert Standard Items link at the bottom of the dialog.

Each menu item has an Image property. Setting this property to an image causes the image to appear on the left side of the text for the menu option. You can see this property in use by looking at the standard items inserted in the preceding example. The File

Items can also have check marks beside them. This is done by changing the Checked property of the item to True. You can do this at design time or runtime, enabling you to manipulate the check marks on menus as necessary.

To implement a context menu for a form or any control on a form, drag a ContextMenuStrip to the form and add the menu items. Items are added and changed the same way as they are with the MenuStrip.

To hook a context menu to a control, set the control's ContextMenuStrip property to the ContextMenuStrip menu control you want to use. Then, when your program runs and you right-click in the control, the context menu will pop up.

Menus can be adjusted at runtime using code. Context menus, for instance, may need to vary depending on the state of your form. The following walk-through shows how to add a new menu item to a context menu and how to clear the menu items.

Create a new Windows application. On the blank Form1 for the project, drag over a MenuStrip control. Using the menu designer, type in a top-level menu option of File. Under that option, type in options for Open and Save.

Now place a button on the form. Double-click the button to get its Click event, and place the following code into the event:

Dim NewItem As New ToolStripMenuItem
NewItem.Text = "Save As"
' Set any other properties of the menu item you like.

FileToolStripMenuItem.DropDownItems.Add(NewItem)
AddHandler NewItem.Click, _
     AddressOf Me.NewMenuItem_Click

Add the event handler referenced in this code at the bottom of the form's code:

Private Sub NewMenuItem_Click(ByVal sender As System.Object, _
                              ByVal e As System.EventArgs)
   MessageBox.Show("New menu item clicked!")
End Sub

If you now run the program and look at the menu, it will only have File and Save options. Clicking the button will cause a new Save As item to be added to the menu, and it will be hooked to the event routine called NewMenuItem_Click.

These two controls open the standard dialog control that enables users to select files on the system. They are quite similar except for the buttons and labels that appear on the actual dialog box when it is shown to the user. Each prompts the user for a file on the system by allowing the user to browse the files and folders available.

Use the following properties to set up the dialog boxes:

The following code opens the standard dialog box, asking the user to select a file that currently exists on the system, and simply displays the choice in a message box upon return:

OpenFileDialog1.InitialDirectory = "C:"
OpenFileDialog1.Filter = "Text files|*.txt|All files|*.*"
OpenFileDialog1.FilterIndex = 1
OpenFileDialog1.RestoreDirectory = True
If OpenFileDialog1.ShowDialog() = Windows.Forms.DialogResult.OK Then
    MessageBox.Show("You selected """ & OpenFileDialog1.FileName & """")
End If

As the name implies, this control gives the user a dialog box from which to select a color. Use the following properties to set up the dialog boxes as follows:

ColorDialog1.Color = TextBox1.BackColor
ColorDialog1.AllowFullOpen = True
If ColorDialog1.ShowDialog()= Windows.Forms.DialogResult.OK Then
    TextBox1.BackColor = ColorDialog1.Color
End If

This control displays the standard dialog box, allowing a user to select a font. Use the following properties to set up the dialog boxes:

Using these properties looks like this:

FontDialog1.Font = TextBox1.Font
FontDialog1.ShowColor = True
FontDialog1.ShowEffects = True
FontDialog1.FixedPitchOnly = False
If FontDialog1.ShowDialog()= Windows.Forms.DialogResult.OK Then
    TextBox1.Font = FontDialog1.Font
End If

There are three more common dialog controls: PrintDialog, PrintPreviewDialog, and PageSetup-Dialog. They can all be used to control the output of a file to the printer, and you can use these in conjunction with the PrintDocument component to run and control print jobs.