These two properties let you specify the default Accept and Cancel buttons. The Accept button is the one that's automatically activated when you press Enter, no matter which control has the focus at the time; it is usually the button with the OK caption. Likewise, the Cancel button is the one that's automatically activated when you hit the Esc key; it is usually the button with the Cancel caption. To specify the Accept and Cancel buttons on a form, locate the AcceptButton and CancelButton properties of the form and select the corresponding controls from a drop-down list, which contains the names of all the buttons on the form. For more information on these two properties, see the section "Forms versus Dialog Boxes," later in this chapter.

This property determines how the control is scaled, and its value is a member of the AutoScaleMode enumeration: None (automatic scaling is disabled); Font (the controls on the form are scaled relative to the size of the font); Dpi, which stands for dots per inch (the controls on the form are scaled relative to the display resolution); and Inherit (the controls are scaled according to the AutoScaleMode property of their parent class). The default value is Font; if you change the form's font size, the controls on it are scaled to the new font size. As a result, the entire form is resized.

The AutoScroll property is a True/False value that indicates whether scroll bars (as shown in Figure 6.2) will be automatically attached to the form if the form is resized to a point that not all its controls are visible. Use this property to design large forms without having to worry about the resolution of the monitor on which they'll be displayed. Scrolling forms are not very common, but they're easy to implement. The AutoScroll property is used in conjunction with two other properties (described a little later in this section): AutoScrollMargin and AutoScrollMinSize. Note that the AutoScroll property applies to a few controls as well, including the Panel and SplitContainer controls. For example, you can create a form with a fixed and a scrolling pane by placing two Panel controls on it and setting the AutoScroll property of one of them (the Panel control you want to scroll) to True.

Figure 6.2. If the controls don't fit in a form's visible area, scroll bars can be attached automatically.

The AutoScroll property is rarely used with data-entry forms, but it's used routinely to display large images. You'll see how to create a scrolling form for displaying large images later in this chapter in the section on anchoring and docking controls.

This property is available from within your code only (you can't set this property at design time but it can be set at runtime from within your code), and it indicates the number of pixels that the form was scrolled up or down. Its initial value is zero, and it takes on a value when the user scrolls the form (provided that the AutoScroll property is True). Use this property to find out the visible controls from within your code or to scroll the form from within your application's code to bring a specific control into view.

This is a margin, expressed in pixels, that's added around all the controls on the form. If the form is smaller than the rectangle that encloses all the controls adjusted by the margin, the appropriate scroll bar(s) will be displayed automatically.

This property lets you specify the minimum size of the form before the scroll bars are attached. If your form contains graphics that you want to be visible at all times, set the Width and Height members of the AutoScrollMinSize property to the dimensions of the graphics. (Of course, the graphics won't be visible at all times, but the scroll bars indicate that there's more to the form than can fit in the current window.) Notice that this isn't the form's minimum size; users can make the form even smaller. To specify a minimum size for the form, use the MinimumSize property, described later in this section.

Let's say the AutoScrollMargin property of the form is 180×150. If the form is resized to fewer than 180 pixels horizontally or 150 pixels vertically, the appropriate scroll bars will appear automatically as long as the AutoScroll property is True. If you want to enable the AutoScroll feature when the form's width is reduced to anything fewer than 250 pixels, set the AutoScrollMinSize property to (250, 0). In this example, setting AutoScrollMinSize.Width to anything less than 180, or AutoScrollMinSize.Height to anything less than 150, will have no effect on the appearance of the form and its scroll bars.

The FormBorderStyle property determines the style of the form's border; its value is one of the FormBorderStyle enumeration members, which are shown in Table 6.2. You can make the form's title bar disappear altogether by setting the form's FormBorderStyle property to FixedToolWindow, the ControlBox property to False, and the Text property (the form's caption) to an empty string. However, a form like this can't be moved around with the mouse and will probably frustrate users.

Create a simple form and try out the various settings of the FormBorderStyle property to find out how this property affects the appearance of the form.

This property is also True by default. Set it to False to hide the control box icon and disable the Control menu. Although the Control menu is rarely used, Windows applications don't disable it. When the ControlBox property is False, the three buttons on the title bar are also disabled. If you set the Text property to an empty string, the title bar disappears altogether.

These two properties, which specify whether the Minimize and Maximize buttons will appear on the form's title bar, are True by default. Set them to False to hide the corresponding buttons on a form's title bar.

These two properties read or set the minimum and maximum size of a form. When users resize the form at runtime, the form won't become any smaller than the dimensions specified by the MinimumSize property or any larger than the dimensions specified by the MaximumSize property. The MinimumSize property is a Size object, and you can set it with a statement like the following:

Me.MinimumSize = New Size(400, 300)

Or you can set the width and height separately:

Me.MinimumSize.Width = 400
Me.MinimumSize.Height = 300

The MinimumSize.Height property includes the height of the form's title bar; you should take that into consideration. If the minimum usable size of the form is 400×300, use the following statement to set the MinimumSize property:

Me.MinimumSize = New Size(400, 300 + SystemInformation.CaptionHeight)

The default value of both properties is (0, 0), which means that no minimum or maximum size is imposed on the form and the user can resize it as desired.

This property enables the form to capture all keystrokes before they're passed to the control that has the focus. Normally, when you press a key, the KeyPress event of the control with the focus is triggered (as well as the KeyUp and KeyDown events), and you can handle the keystroke from within the control's appropriate handler. In most cases, you let the control handle the keystroke and don't write any form code for that.

Some forms perform certain actions when you hit a specific key (the F5 key for refreshing the form being a very common example), no matter which control on the form has the focus. If you want to use these keystrokes in your application, you must set the KeyPreview property to True. Doing so enables the form to intercept all keystrokes, so you can process them from within the form's keystroke event handlers. To handle a specific keystroke at the form's level, set the form's KeyPreview property to True and insert the appropriate code in the form's KeyDown or KeyUp event handler (the KeyPress event isn't fired for the function and other non-character keys).

The same keystrokes are then passed to the control with the focus, unless you kill the keystroke by setting its SuppressKeystroke property to True when you process it on the form's level. For more information on processing keystrokes at the form level and using special keystrokes throughout your application, see the Contacts project later in this chapter as well as the TextPad project discussed in Chapter 5, "The Basic Window Controls."

This property gets or sets the style of the sizing handle to display in the lower-right corner of the form. You can set it to a member of the SizeGripStyle enumeration: Auto (the size grip is displayed as needed), Show (the size grip is displayed at all times), or Hide (the size grip is not displayed, but users can still resize the form with the mouse).

The StartPosition property, which determines the initial position of the form when it's first displayed, can be set to one of the members of the FormStartPosition enumeration: CenterParent (the form is centered in the area of its parent form), CenterScreen (the form is centered on the monitor), Manual (the position of the form is determined by the Location property), WindowsDefaultLocation (the form is positioned at the Windows default location), and WindowsDefaultBounds (the form's location and bounds are determined by Windows defaults). The Location property allows you to set the form's initial position at design time or to change the form's location at runtime.

This property is a True/False setting that lets you specify whether the form will remain on top of all other forms in your application. Its default value is False, and you should change it only on rare occasions. Some dialog boxes, such as the Find & Replace dialog box of any text-processing application, are always visible, even when they don't have the focus. For more information on using the TopMost property, see the discussion of the TextPad project in Chapter 5. You can also add a professional touch to your application by providing a CheckBox control that determines whether a form should remain on top of all other forms of the application.

Use the Size property to set the form size at design time or at runtime. Normally, the form width and height are controlled by the user at runtime. This property is usually set from within the form Resize event handler to maintain a reasonable aspect ratio when the user resizes the form. The Form object also exposes the Width and Height properties for controlling its size.

Although the Tab key is the Windows method of moving to the next control on the form, most users will find it more convenient to use the Enter key for that purpose. The Enter key is the most important one on the keyboard, and applications should handle it intelligently. When the user presses Enter in a single-line TextBox, for example, the obvious action is to move the focus to the following control. I included a few statements in the KeyDown event handlers of the TextBox controls to move the focus to the following one:

Private Sub txtAddress1_KeyDown(...) Handles txtAddress1.KeyDown
    If e.KeyData = Keys.Enter Then
        e.SuppressKeyPress = True
        txtAddress2.Focus()
    End If
End Sub

If you use the KeyUp event handler instead, the result won't be any different, but an annoying beeping sound will be emitted with each keystroke. The beep occurs when the button is depressed, so you must intercept the Enter key as soon as it happens and not after the control receives the notification for the KeyDown event. The control will still catch the KeyUp event and it will beep because it's a single-line TextBox control (the beep is an audible warning that the specific key shouldn't be used in a single-line TextBox control). To avoid the beep sound, the code "kills" the keystroke by setting the SuppressKeystroke property to True.

Real World Scenario: Processing Keys from within Your Code

The code shown in the preceding KeyDown event handler will work, but you must repeat it for every TextBox control on the form. A more convenient approach is to capture the Enter keystroke in the form's KeyDown event handler and process it for all TextBox controls. First, you must figure out whether the control with the focus is a TextBox control. The property Me.ActiveControl returns a reference to the control with the focus. To find out the type of the active control and compare it to the TextBox control's type, use the following If statement:

If Me.ActiveControl.GetType Is GetType(TextBox) Then
' process the Enter key
End If

Once you can figure out the active control's type, you need a method of simulating the Tab keystroke from within your code so you don't have to code every TextBox control's KeyDown event. An interesting method of the Form object is the ProcessTabKey method, which imitates the Tab keystroke. Calling the ProcessTabKey method is equivalent to pressing the Tab key from within your code. The method accepts a True/False value as an argument, which indicates whether it will move the focus to the next control in the tab order (if True) or to the previous control in the tab order.

Start by setting the form's KeyPreview property to True and then insert the following statements in the form's KeyDown event handler:

If e.KeyCode = Keys.Enter Then
    If Me.ActiveControl.GetType Is GetType(TextBox) Then

e.SuppressKeyPress = True
        If e.Shift Then
            Me.ProcessTabKey(False)
        Else
            Me.ProcessTabKey(True)
        End If
    End If
End If

The last topic demonstrated in this example is how to capture certain keystrokes regardless of the control that has the focus. We'll use the F10 keystroke to display the total number of contacts entered so far. Assuming that you have already set the form's KeyPreview property to True, enter the following code in the form's KeyDown event:

If e.Keycode = keys.F10 Then
   MsgBox("There are " & MyContacts.Count.ToString & " contacts in the database")
   e.Handled = True
End If

Listing 6.1 shows the complete handler for the form's KeyDown event, which also allows you to move to the next or previous contact by using the Alt+Plus or Alt+Minus keys, respectively.

Public Sub Form1_KeyDown(ByVal sender As Object,
            ByVal e As System.WinForms.KeyEventArgs)
                        Handles Form1.KeyUp
   If e.Keycode = Keys.F10 Then
      MsgBox("There are " & MyContacts.Count.ToString &
             " contacts in the database")
      e.Handled = True
   End If
   If e.KeyCode = Keys.Subtract And e.Modifiers = Keys.Alt Then
      bttnPrevious.PerformClick
   End If
   If e.KeyCode = Keys.Add And e.Modifiers = Keys.Alt Then
      bttnNext.PerformClick
   End If
   If e.KeyCode = Keys.Enter Then
       If Me.ActiveControl.GetType Is GetType(TextBox) Then
           e.SuppressKeyPress = True
           If e.Shift Then
               Me.ProcessTabKey(False)
           Else
               Me.ProcessTabKey(True)

End If
       End If
   End If
End Sub

The Anchor property lets you attach one or more edges of the control to corresponding edges of the form. The anchored edges of the control maintain the same distance from the corresponding edges of the form.

Place a TextBox control on a new form, set its MultiLine property to True, and then open the control's Anchor property in the Properties window. You will see a rectangle within a larger rectangle and four pegs that connect the small control to the sides of the larger box (see Figure 6.6). The large box is the form, and the small one is the control. The four pegs are the anchors, which can be either white or gray. The gray anchors denote a fixed distance between the control and the edge of the form. By default, the control is placed at a fixed distance from the upper-left corner of the form. When the form is resized, the control retains its size and its distance from the upper-left corner of the form.

Figure 6.6. The settings for the Anchor property

Let's say you're designing a simple form with a TextBox control that must fill the width of the form, be anchored to the top of the form, and leave some space for a few buttons at the bottom. You also want your form to maintain this arrangement regardless of its size. Make the TextBox control as wide as the form (allowing, perhaps, a margin of a few pixels on either side). Then place a couple of buttons at the bottom of the form and make the TextBox control tall enough that it stops above the buttons. This is the form of the Anchor sample project.

Now open the TextBox control's Anchor property and make all four anchors gray by clicking them. This action tells the Form Designer to resize the control accordingly, so that the distances between the sides of the control and the corresponding sides of the form remain the same as those you set at design time. Select each button on the form and set their Anchor properties in the Properties window: Anchor the left button to the left and bottom of the form and the right button to the right and bottom of the form.

Resize the form at design time without running the project and you'll see that all the controls are resized and rearranged on the form at all times. Figure 6.7 shows the Anchor project's main form in two different sizes.

Figure 6.7. Use the Anchor property of the various controls to design forms that can be resized gracefully at runtime.

Yet, there's a small problem: If you make the form very narrow, there will be no room for both buttons across the form's width. The simplest way to fix this problem is to impose a minimum size for the form. To do so, you must first decide the form's minimum width and height and then set the MinimumSize property to these values. You can also use the AutoScroll properties, but it's not recommended that you add scroll bars to a small form like ours. Use the AutoScroll properties for large forms with many controls that can't be resized with the form.

In addition to the Anchor property, most controls provide a Dock property, which determines how a control will dock on the form. The default value of this property is None.

Create a new form, place a multiline TextBox control on it, and then open the Dock property for the control. The various rectangular shapes are the settings of the property. If you click the middle rectangle, the control will be docked over the entire form: It will expand and shrink both horizontally and vertically to cover the entire form. This setting is appropriate for simple forms that contain a single control, usually a TextBox, and sometimes a menu. Try it out.

Let's create a more complicated form with two controls (see the Docking sample project at www.sybex.com/go/masteringvb2010). The form shown in Figure 6.8 contains a TreeView control on the left and a ListView control on the right. The two controls display folder and file data on an interface that's very similar to that of Windows Explorer. The TreeView control displays the directory structure, and the ListView control displays the selected folder's files.

Figure 6.8. Filling a form with two controls

Place a TreeView control on the left side of the form and a ListView control on the right side of the form. Then dock the TreeView to the left and the ListView to the right. If you run the application now, as you resize the form, the two controls remain docked to the two sides of the form—but their sizes don't change. If you make the form wider, there will be a gap between the two controls. If you make the form narrower, one of the controls will overlap the other.

End the application, return to the Form Designer, select the ListView control, and set its Dock property to Fill. This time, the ListView will change size to take up all the space to the right of the TreeView. The ListView control will attempt to fill the form, but it won't take up the space of another control that has been docked already. The TreeView and ListView controls are discussed in the tutorial "The TreeView and ListView Controls," which you can download from www.sybex.com/go/masteringvb2010. That's why I've populated them with some fake data at design time. In the tutorial, you'll learn how to populate these two controls at runtime with folder names and filenames, respectively, and build a custom Windows Explorer.

Real World Scenario: Scrolling PictureBox

An interesting technique I should mention here is how to create a scrolling form for displaying large images. The basic requirement is that the image can't take up the entire form; you need some space for a menu, a few buttons, or other controls to interact with the form. The image must be displayed on a PictureBox control with its SizeMode property set to AutoSize. This setting causes the PictureBox to adjust to the size of the image it contains. Place the various controls you need for your interface on the form, as shown here, and then place a Panel on the form. Anchor the Panel to all four edges of the form so that it's resized along with the form. Then set its AutoScroll property to True. Finally, place a PictureBox control on the Panel and align its upper-left corner with the upper-left corner of the Panel control. Do not anchor or dock this control, because its size will be determined by the size of the image it contains, not by its container's size. Now assign a large image to the PictureBox control (you can use any of the images in the Sample Pictures folder).

If you run the application now, you will see as much of the upper-left corner of the image as can fit on the Panel control. You can resize the form to see more of the image or scroll it around with the two scroll bars to bring any segment of the image into view. This technique allows you to display an image of any size on a form of any (usually smaller) size.

When more than one form is displayed, the user can switch from one to the other by using the mouse or by pressing Alt+Tab. Each time a form is activated, the Activated event takes place. Likewise, when a form is activated, the previously active form receives the Deactivate event. Insert the code you want to execute when a form is activated (set certain control properties, for example) and when a form loses the focus or is deactivated in these two event handlers. These two events are the equivalents of the Enter and Leave events of the various controls. Notice that there's an inconsistency in the names of the two events: the Activated event takes place after the form has been activated, whereas the Deactivate event takes place right before the form is deactivated.

The FormClosing event is fired when the user closes the form by clicking its Close button. If the application must terminate because Windows is shutting down, the same event will be fired. Users don't always quit applications in an orderly manner, and a professional application should behave gracefully under all circumstances. The same code you execute in the application Exit command must also be executed from within the FormClosing event. For example, you might display a warning if the user has unsaved data, you might have to update a database, and so on. Place the code that performs these tasks in a subroutine and call it from within your menu's Exit command as well as from within the FormClosing event's handler.

You can cancel the closing of a form by setting the e.Cancel property to True. The event handler in Listing 6.2 displays a message box informing the user that the data hasn't been saved and gives them a chance to cancel the action and return to the application.

Public Sub Form1_FormClosing (...) Handles Me.FormClosing
    Dim reply As MsgBoxResult
    reply = MsgBox("Document has been edited. " &
             "OK to terminate application, Cancel to " &
             "return to your document.", MsgBoxStyle.OKCancel)
    If reply = MsgBoxResult.Cancel Then
       e.Cancel = True
    End If
End Sub

The e argument of the FormClosing event provides the CloseReason property, which reports how the form is closing. Its value is one of the following members of the CloseReason enumeration: FormOwnerClosing, MdiFormClosing, None, TaskManagerClosing, WindowsShutDown, ApplicationExitCall, and UserClosing. The names of the members are self-descriptive, and you can query the CloseReason property to determine how the window is closing.

The Resize event is fired every time the user resizes the form by using the mouse. In the past, programmers had to insert quite a bit of code in the Resize event's handler to resize the controls and possibly rearrange them on the form. With the Anchor and Dock properties, much of this overhead can be passed to the form itself. If you want the two sides of the form to maintain a fixed ratio, however, you have to resize one of the dimensions from within the Resize event handler. Let's say the form's width-to-height ratio must be 3:4. Assuming that you're using the form's height as a guide, insert the following statement in the Resize event handler to make the width equal to three-fourths of the height:

Private Form1_Resize (...) Handles Me.Resize
   Me.Width = (0.75 * Me.Height)
End Sub

The Resize event is fired continuously while the form is being resized. If you want to keep track of the initial form's size and perform all the calculations after the user has finished resizing the form, you can use the ResizeBegin and ResizeEnd events, which are fired at the beginning and after the end of a resize operation, respectively. Store the form's width and height to two global variables in the ResizeBegin event and use these two variables in the ResizeEnd event handler to adjust the positions of the various controls on the form.

The Scroll event is fired by forms that have the AutoScroll property set to True when the user scrolls the form. The second argument of the Scroll event handler exposes the OldValue and NewValue properties, which are the displacements of the form before and after the scroll operation. This event can be used to keep a specific control in view when the form's contents are scrolled.

The AutoScroll property is handy for large forms, but it has a serious drawback: It scrolls the entire form. In most cases, you want to keep certain controls in view at all times. Instead of a scrollable form, you can create forms with scrollable sections by exploiting the AutoScroll properties of the Panel and/or the SplitContainer controls. You can also reposition certain controls from within the form's Scroll event handler. Let's say you have placed a few controls on a Panel container and you want to keep this panel at the top of a scrolling form. The following statements in the form's Scroll event handler reposition the panel at the top of the form every time the user scrolls the form:

Private Sub Form1_Scroll(...) Handles Me.Scroll
    Panel1.Top = Panel1.Top + (e.NewValue - e.OldValue)
End Sub

This event takes place every time the form must be refreshed, and we use its handler to execute code for any custom drawing on the form. When you switch to another form that partially or totally overlaps the current one and then switch back to the first form, the Paint event will be fired to notify your application that it must redraw the form. The form will refresh its controls automatically, but any custom drawing on the form won't be refreshed automatically. This event is discussed in more detail in the tutorial "Drawing and Painting with Visual Basic 2008," where the Framework's drawing methods are presented. You can download the tutorial from www.sybex.com/go/masteringvb2010.

The preferred method for two forms to communicate with each other is through public variables. These variables are declared in the form's declarations section, outside any procedure, with the keyword Public. If the following declarations appear in Form1, the variable NumPoints and the array DataValues can be accessed by any procedure in Form1 as well as from within the code of any form belonging to the same project:

Public NumPoints As Integer
Public DataValues(100) As Double

To access a public variable declared in Form1 from within another form's code, you must prefix the variable's name by the name of the form, as in the following:

Form1.NumPoints = 99
Form1.DataValues(0) = 0.3395022

In effect, the two public variables have become properties of the form in which they were declared. You can use the same notation to access the controls on another form. If Form1 contains the TextBox1 control, you can use the following statement to read its text:

Form1.TextBox1.Text

The controls on a form can be accessed by the code in another form because the default value of the Modifiers property of the controls on a form is Friend, which means that all components in a solution can access them. Other settings of the Modifiers property are Public (any application can access the control) and Private (the control is private to the form to which it belongs and cannot be accessed from code outside its own form). There are two more values, Protected and Protected Friend, which apply to inherited forms, a topic that's not covered in this book.

If a button on Form1 opens the auxiliary form Form2, you can set selected controls to specific values before showing the auxiliary form. The following statements should appear in a button's or menu item's Click event handler:

Form2.TextBox1.Text = "some text"
Form2.DateTimePicker1.Value = Today
Form2.Show()

You can also create a variable to represent another form and access the auxiliary form through this variable. Let's say you want to access the resources of Form2 from within the code of Form1. Declare the variable auxForm to represent Form2 and then access the resources of Form2 with the following statements:

Dim auxForm As Form2
auxForm.TextBox1.Text = "some text"
auxForm.DateTimePicker1.Value = Today
auxForm.Show

It's time to write an application that puts together the topics discussed in this section. The MultipleForms project, available for download from www.sybex.com/go/masteringvb2010, consists of a main form, an auxiliary form, and a dialog box. All three components of the application interface are shown in Figure 6.13. The buttons on the main form display both the auxiliary form and the dialog box.

Figure 6.13. The MultipleForms project interface

Let's review the various operations you want to perform — they're typical for many situations, not for only this application. At first, you must be able to invoke both the auxiliary form and the dialog box from within the main form; the Show Auxiliary Form and Show Dialog Box buttons do this. The main form contains a variable declaration: strProperty. This variable is, in effect, a property of the main form and is declared as public with the following statement:

Public strProperty As String = "Mastering VB 2010"

The main form calls the auxiliary form's Show method to display it in a modeless manner. The auxiliary form button with the caption Read Shared Variable In Main Form reads the strProperty variable of the main form with the following statement:

Private Sub bttnReadShared_Click(...) Handles bttnReadShared.Click
   MsgBox(MainForm.strProperty, MsgBoxStyle.OKOnly,
               "Public Variable Value")
End Sub

Using the same notation, you can set this variable from within the auxiliary form. The following event handler prompts the user for a new value and assigns it to the shared variable of the main form:

Private Sub bttnSetShared_Click(...) Handles bttnSetShared.Click
   Dim str As String
   str = InputBox("Enter a new value for strProperty")
   MainForm.strProperty = str
End Sub

The two forms communicate with each other through public properties. Let's make this communication a little more elaborate by adding an event. Every time the auxiliary form sets the value of the strProperty variable, it raises an event to notify the main form. The main form, in turn, uses this event to display the new value of the string on the TextBox control as soon as the code in the auxiliary form changes the value of the variable and before it's closed.

To raise an event, you must declare the event name in the form's declaration section. Insert the following statement in the auxiliary form's declarations section:

Event strPropertyChanged()

Now add a statement that fires the event. To raise an event, call the RaiseEvent statement and pass the name of the event as an argument. This statement must appear in the Click event handler of the Set Shared Variable In Main Form button, right after setting the value of the shared variable. As soon as the user clicks the button, the auxiliary form notifies the main form by raising the strPropertyChanged event. Listing 6.4 shows the revised event handler.

Private Sub bttnSetShared_Click(...) Handles bttnSetShared.Click
   Dim str As String
   str = InputBox("Enter a new value for strProperty")
   MainForm.strProperty = str
   RaiseEvent strPropertyChanged
End Sub

The event will be raised, but it will go unnoticed if you don't handle it from within the main form's code. To handle the event, you must create a variable that represents the auxiliary form with the WithEvents keyword:

Dim WithEvents FRM As New AuxiliaryForm()

The WithEvents keyword tells VB that the variable is capable of raising events and that VB should listen for events from the specific form. If you expand the drop-down list with the objects in the code editor, you will see the name of the FRM variable, along with the other controls you can program. Select FRM in the list and then expand the list of events for the selected item. In this list, you will see the strPropertyChanged event. Select it and the definition of an event handler will appear. Enter these statements in this event's handler:

Private Sub FRM_strPropertyChanged() Handles FRM.strPropertyChanged
   TextBox1.Text = strProperty
   Beep()
End Sub

It's a simple handler, but it's adequate for demonstrating how to raise and handle custom events on the form level. If you want, you can pass arguments to the event handler by including them in the declaration of the event. To pass the original and the new value through the strPropertyChanged event, use the following declaration:

Event strPropertyChanged(ByVal oldValue As String,
                         ByVal newValue As String)

If you run the application now, you'll see that the value of the TextBox control in the main form changes as soon as you change the property's value in the auxiliary form. You can actually change the value of the variable several times before closing the auxiliary form, and each time the current value will be displayed on the main form.

Of course, you can update the TextBox control on the main form directly from within the auxiliary form's code. Use the expression MainForm.TextBox1 to access the control and then manipulate it as usual. Events are used to perform some actions on a form when an action takes place. The benefit of using events, as opposed to accessing members of another form from within your code, is that the auxiliary form need not know anything about the form that called it. The auxiliary form raises the event, and it's the calling form's responsibility to handle it. Moreover, the event handler in the main form may perform other actions in addition to setting a control's value; it may submit something to a database, log the action, and perform any other operation suited for the application at hand.

Let's see now how the main form interacts with the dialog box. What goes on between a form and a dialog box is not exactly interaction; it's a more timid type of behavior. The form displays the dialog box and waits until the user closes the dialog box. Then it looks at the value of the DialogResult property to find out whether it should even examine the values passed back by the dialog box. If the user has closed the dialog box with the Cancel (or an equivalent) button, the application ignores the dialog box settings. If the user closed the dialog box with the OK button, the application reads the values and proceeds accordingly.

Before showing the dialog box, the code of the Show Dialog Box button sets the values of certain controls on the dialog box. In the course of the application, it usually makes sense to suggest a few values in the dialog box so that the user can accept the default values by pressing the Enter key. The main form reads a date on the dialog box's controls and then displays the dialog box with the statements given in Listing 6.5.

Protected Sub Button3_Click(...) Handles Button3.Click
' Preselects the date 4/11/1980
   AgeDialog.cmbMonth.Text = "4"
   AgeDialog.cmbDay.Text = "11"
   AgeDialog.CmbYear.Text = "1980"
   AgeDialog.ShowDialog()
   If AgeDialog.DialogResult = DialogResult.OK Then
      MsgBox(AgeDialog.cmbMonth.Text & " " &
             AgeDialog.cmbDay.Text & "," &
             AgeDialog.cmbYear.Text)
   Else
      MsgBox("OK, we'll protect your vital personal data")

End If
End Sub

To close the dialog box, you can click the OK or Cancel button. Each button sets the DialogResult property to indicate the action that closed the dialog box. The code behind the two buttons is shown in Listing 6.6.

Protected Sub bttnOK_Click(...) Handles bttnOK.Click
   Me.DialogResult = DialogResult.OK
End Sub

Protected Sub bttnCancel_Click(...) Handles bttnCancel.Click
   Me.DialogResult = DialogResult.Cancel
End Sub

Because the dialog box is modal, the code in the Show Dialog Box button is suspended at the line that shows the dialog box. As soon as the dialog box is closed, the code in the main form resumes with the statement following the one that called the ShowDialog method of the dialog box. This is the If statement in Listing 6.5 that examines the value of the DialogResult property and acts accordingly.

The ShowControls project (shown in Figure 6.14) demonstrates the basic methods of the Controls property. Download the ShowControls project from www.sybex.com/go/masteringvb2010, open it, and add any number of controls on the main form. You can place a panel to act as a container for other controls as well. Just don't remove the button at the top of the form (the Scan Controls On This Form button); it contains the code to list all the controls.

Figure 6.14. Accessing the controls on a form at runtime

The code behind the Scan Controls On This Form button enumerates the elements of the form's Controls collection. The code doesn't take into consideration containers within containers. This would require a recursive routine, which would scan for controls at any depth. The code that iterates through the form's Controls collection and prints the names of the controls in the Output window is shown in Listing 6.7.

Private Sub Button1_Click(...) Handles Button1.Click
    Dim Control As Windows.Forms.Control
    For Each Control In Me.Controls
        Debug.WriteLine(Control.ToString)
        If Control.GetType Is GetType(System.Windows.Forms.Panel) Then
            Dim nestedControl As Windows.Forms.Control
            For Each nestedControl In Control.Controls
                Debug.WriteLine("   " & nestedControl.ToString)
            Next
        End If
    Next
End Sub

The form shown in Figure 6.15 produced the following (partial) output (the controls on the Panel are indented to stand out in the listing):

Panel1:          System.Windows.Forms.Panel,
BorderStyle:     System.Windows.Forms.BorderStyle.FixedSingle
    CheckBox4:   System.Windows.Forms.CheckBox, CheckState: 0
    CheckBox3:   System.Windows.Forms.CheckBox, CheckState: 0
HScrollBar1:     System.Windows.Forms.HScrollBar,
                 Minimum: 0, Maximum: 100, Value: 0
CheckedListBox1: System.Windows.Forms.CheckedListBox,
                 Items.Count: 3, Items[0]: Item 1
TextBox2:        System.Windows.Forms.TextBox,
                 Text: TextBox2

To find out the type of individual controls, call the GetType method. The following statement examines whether the control in the first element of the Controls collection is a TextBox:

If Me.Controls(0).GetType Is GetType(System.Windows.Forms.TextBox) Then
   MsgBox("It's a TextBox control")
End If

Notice the use of the Is operator in the preceding statement. The equals operator would cause an exception because objects can be compared only with the Is operator. (You're comparing instances, not values.)

To access other properties of the control represented by an element of the Controls collection, you must first cast it to the appropriate type. If the first control of the collection is a TextBox control, use the CType() function to cast it to a TextBox variable and then request its SelectedText property:

If Me.Controls(0).GetType Is GetType(System.Windows.Forms.TextBox) Then
   Debug.WriteLine(CType(Me.Controls(0), TextBox).SelectedText)
End If

The If statement is necessary, unless you can be sure that the first control is a TextBox control. If you omit the If statement and attempt to convert the control to a TextBox, a runtime exception will be thrown if the object Me.Controls(0) isn't a TextBox control.

To demonstrate how to handle controls at runtime from within your code, I included the DynamicForm project (Figure 6.15) on www.sybex.com/go/masteringvb2010. It's a simple data-entry window for a small number of data points. The user can specify at runtime the number of data points she wants to enter, and the number of TextBoxes on the form is adjusted automatically.

The control you see at the top of the form is the NumericUpDown control. All you really need to know about this control is that it displays an integer in the range specified by its Minimum and Maximum properties and allows users to select a value. It also fires the ValueChanged event every time the user clicks one of the two arrows or types another value in its edit area. This event handler's code adds or removes controls on the form so that the number of text boxes (as well as the number of corresponding labels) matches the value on the control. Listing 6.8 shows the handler for the ValueChanged event of the NumericUpDown1 control.

Figure 6.15. The DynamicForm project

Private Sub NumericUpDown1_ValueChanged(...)  Handles NumericUpDown1.ValueChanged
    Dim TB As New TextBox()
    Dim LBL As New Label()
    Dim i, TBoxes As Integer
    '   Count all TextBox controls on the Form
    For i = 0 To Me.Controls.Count - 1
        If Me.Controls(i).GetType Is
                    GetType(System.Windows.Forms.TextBox) Then
            TBoxes = TBoxes + 1
        End If
    Next
    ' Add new controls if number of controls on the Form is less
    ' than the number specified with the NumericUpDown control
    If TBoxes < NumericUpDown1.Value Then
        TB.Left = 100: TB.Width = 120
        TB.Text = ""
        For i = TBoxes To CInt(NumericUpDown1.Value) - 1
            TB = New TextBox()
            LBL = New Label()
            If NumericUpDown1.Value = 1 Then
                TB.Top = 20: TB.TabIndex = 0
            Else
                TB.Top = Me.Controls(Me.Controls.Count - 2).Top + 25
            End If
           ' Set the trivial properties of the new controls
           LBL.Left = 20: LBL.Width = 80
           LBL.Text = "Data Point " & i
           LBL.Top = TB.Top + 3
           TB.Left = 100: TB.Width = 120

TB.Text = ""
           ' add controls to the form
           Me.Controls.Add(TB)
           Me.Controls.Add(LBL)
           TB.TabIndex = Convert.ToInt32(NumericUpDown1.Value)
           ' and finally connect their GotFocus/LostFocus events
           ' to the appropriate handler
           AddHandler TB.Enter,
                     New System.EventHandler(AddressOf TBox_Enter)
           AddHandler TB.Leave,
                     New System.EventHandler(AddressOf TBox_Leave)
        Next
    Else
        For i = Me.Controls.Count - 1 To Me.Controls.Count -
                    2 * (TBoxes - CInt(NumericUpDown1.Value)) Step −2
            Me.Controls.Remove(Controls(i))
            Me.Controls.Remove(Controls(i - 1))
        Next
    End If
End Sub

The code is lengthy but straightforward; most of the statements just set the basic properties of the Label and TextBox controls on the form. Ignore the AddHandler statements for now; they're discussed in the following section. First, the code counts the number of TextBoxes on the form; then it figures out whether it should add or remove elements from the Controls collection. To remove controls, the code iterates through the last n controls on the form and removes them. The number of controls to be removed is the following, where TBoxes is the total number of controls on the form minus the value specified in the NumericUpDown control:

2 * (TBoxes - NumericUpDown1.Value)

If the value entered in the NumericUpDown control is less than the number of TextBox controls on the form, the code removes the excess controls from within a loop. At each step, it removes two controls, one of them a TextBox and the other a Label control with the matching caption. (That's why the loop variable is decreased by two.) The code also assumes that the first two controls on the form are the Button and the NumericUpDown controls. If the value entered by the user exceeds the number of TextBox controls on the form, the code adds the necessary pairs of TextBox and Label controls to the form.

To add controls, the code initializes a TextBox (TB) and a Label (LBL) variable. Then, it sets their locations and the label's caption. The left coordinate of all labels is 20, their width is 80, and their Text property (the label's caption) is the order of the data item. The vertical coordinate is 20 pixels for the first control, and all other controls are 3 pixels below the control on the previous row. After a new control is set up, it's added to the Controls collection with one of the following statements:

Me.Controls.Add(TB)    ' adds a TextBox control
Me.Controls.Add(LBL)   ' adds a Label control

To use the values entered by the user on the dynamic form, we must iterate the Controls collection, extract the values in the TextBox controls, and read their values. Listing 6.9 shows how the Process Values button scans the TextBox controls on the form and performs some basic calculations with them (counting the number of data points and summing their values).

Private Sub Button1_Click(...) Handles Button1.Click
    Dim TBox As TextBox
    Dim Sum As Double = 0, points As Integer = 0
    Dim iCtrl As Integer
    For iCtrl = 0 To Me.Controls.Count - 1
        If Me.Controls(iCtrl).GetType Is
                GetType(System.Windows.Forms.TextBox) Then
            TBox = CType(Me.Controls(iCtrl), TextBox)
            If IsNumeric(TBox.Text) Then
                Sum = Sum + Val(TBox.Text)
                points = points + 1
            End If
        End If
    Next
    MsgBox("The sum of the " & points.ToString &
           " data points is " & Sum.ToString)
End Sub

Real World Scenario: Handling Repeated Data Items

Dynamic forms are actually quite common even in business-line applications. There are situations where users are expected to enter or review multiple items of information on a single form. If each data item consists of several fields (such as names, ages, and the like), your best bet is to design a form like the following one.

This form, which is part of the DynamicDataEntry project, is a more typical example of a dynamic form, which allows users to enter an unknown number of dependant members (or any other entity, for that matter). Although you can create an auxiliary form where the user can enter each entry, the form shown here works better because it allows the user to focus on a single form.

Initially the form is populated with the appropriate controls for entering a single member. Users can click the "Add new member" link to create a new entry. On the left you see the form in its initial state and on the right you see the same form after adding four members. The "Remove member" link removes the last member from the form. Users can enter any number of dependant members on this form by adding new entries. If the number of entries exceeds the height of the form, a scroll bar appears. Notice that the scroll bar scrolls the entries for the members and not the fixed items on the form, which are the two links at the top and the Done Entering Members button at the bottom. You can change the structure of each entry to enable other types of data (such as room types in a hotel reservation system, a student's courses and grades, the statistics of various teams, and so on).

I will not present the full code for the application here; it is well documented and you can examine it on your own. The individual entries are made up of a number of controls, all on a Panel control. This allows you to use the same name for the controls. There's no naming conflict since the controls belong to a different Panel. All individual panels are placed on another larger Panel control, which is anchored to all four sides of the form and resizes nicely along with the form. The AutoScroll property on this Panel control was set to True so that the appropriate scroll bars appear automatically should the user have a large number of members to enter.

Adding and removing entries is quite straightforward. I will show you only the code that iterates through all entries and processes them:

For Each ctrl As Control In Me.Controls("pnlAllMembers").Controls
    If ctrl.GetType Is GetType(System.Windows.Forms.Panel) Then
        Name = ctrl.Controls("txtName").Text
        Age = CType(ctrl.Controls("cbAge"), ComboBox).SelectedItem
        If CType(ctrl.Controls("rdMale"), RadioButton).Checked
                            Then sex = "Male"
        If CType(ctrl.Controls("rdFemale"), RadioButton).Checked
                            Then sex = "Female"
        message &= "NAME: " & Name & vbCrLf &
                   "AGE: " & Age & vbCrLf &
                   "SEX: " & sex & vbCrLf &

"-----------------------------" & vbCrLf
    End If
Next

The outer loop goes through the controls on the pnlAllMembers Panel control, which is the large panel with the entries. If the current control is a Panel, we can process it. Normally, all child controls on the pnlAllMembers Panel will be also Panel controls; you may choose to add other control as well. Then the code accesses each individual control by name. txtName is the name of the TextBox control for the member's name and it's always the same regardless of the entry to which it belongs. The code gradually builds a string with the data of the dependant members and displays them. A real-world application would submit the same data to a database, convert it to XML format, and store it locally or process the data in some other meaningful way. You can open the DynamicDataEntry project and examine its code, which is actually quite short considering all the flexibility.

If you make the form wide, the various entries will still be lined up in a single column, leaving most of the form empty. How about entering some code in the form's resizing events to display the entries in multiple columns depending on the width of the form?

When a menu item is selected by the user, it triggers a Click event. To program a menu item, insert the appropriate code in the item's Click event handler. The Exit command's code would be something like the following:

Sub menuExit(...) Handles menuExit.Click
   End
End Sub

If you need to execute any cleanup code before the application ends, place it in the CleanUp() subroutine and call this subroutine from within the Exit item's Click event handler:

Sub menuExit(...) Handles menuExit.Click
   CleanUp()
   End
End Sub

The same subroutine must also be called from within the FormClosing event handler of the application's main form because some users might terminate the application by clicking the form's Close button.

An application's Open menu command contains the code that prompts the user to select a file and then open it. You will see many examples of programming menu commands in the following chapters. All you really need to know now is that each menu item is a ToolStripMenuItem object and each fires the Click event every time it's selected with the mouse or the keyboard. In most cases, you can treat the Click event handler of a ToolStripMenuItem object just like the Click event handler of a Button.

Another interesting event of the ToolStripMenuItem is the DropDownOpened event, which is fired when the user opens a menu or submenu (in effect, when the user clicks a menu item that leads to a submenu). In this event's handler, you can insert code to modify the submenu. The Edit menu of just about any application contains the ubiquitous Cut/Copy/Paste commands. These commands are not meaningful at all times. If the Clipboard doesn't contain text, the Paste command should be disabled. If no text is selected, the Copy and Cut commands should also be disabled. Here's how you could change the status of the Paste command from within the DropDownOpened event handler of the Edit menu:

If My.Computer.Clipboard.ContainsText Then
    PasteToolStripMenuItem.Enabled = True
Else
    PasteToolStripMenuItem.Enabled = True
End If

Likewise, to change the status of the Cut and Copy commands, use the following statements in the DropDownOpened event of the ToolStripMenuItem that represents the Edit menu:

If txtEditor.SelectedText.Trim.Length > 0 Then
    CopyToolStripMenuItem.Enabled = True
    CutToolStripMenuItem.Enabled = True
Else
    CopyToolStripMenuItem.Enabled = False
    CutToolStripMenuItem.Enabled = False
End If

Menus provide a convenient way to display a large number of choices to the user. They allow you to organize commands in groups, according to their functions, and are available at all times. Opening menus and selecting commands with the mouse, however, can be an inconvenience. When using a word processor, for example, you don't want to have to take your hands off the keyboard and reach for the mouse. To simplify menu access, Windows forms support access keys and shortcut keys.

A common technique in menu design is to create long and short versions of a menu. If a menu contains many commands and most of the time only a few of them are needed, you can create one menu with all the commands and another with the most common ones. The first menu is the long one, and the second is the short one. The last command in the long menu should be Short Menu, and when selected, it should display the short version. The last command in the short menu should be Long Menu (or Full Menu), and it should display the long version.

Figure 6.18 shows a long and a short version of the same menu from the LongMenu project. The short version omits infrequently used commands and is easier to handle.

Figure 6.18. The two versions of the Format menu of the LongMenu application

To implement the LongMenu command, start a new project and create a menu with the options shown in Figure 6.18. Listing 6.11 is the code that shows/hides the long menu in the MenuSize command's Click event.

Private Sub mnuSize_Click(...) Handles mnuSize.Click
    If mnuSize.Text = "Short Menu" Then
        mnuSize.Text = "Long Menu"
    Else
        mnuSize.Text = "Short Menu"
    End If
    mnuUnderline.Visible = Not mnuUnderline.Visible
    mnuStrike.Visible = Not mnuStrike.Visible
    mnuSmallCaps.Visible = Not mnuSmallCaps.Visible
    mnuAllCaps.Visible = Not mnuAllCaps.Visible
End Sub

The subroutine in Listing 6.11 doesn't do much. It simply toggles the Visible property of certain menu commands and changes the command's caption to Short Menu or Long Menu, depending on the menu's current status.

I conclude the discussion of menu design with a technique for building dynamic menus, which grow and shrink at runtime. Many applications maintain a list of the most recently opened files in the File menu. When you first start the application, this list is empty, and as you open and close files, it starts to grow.

The RunTimeMenu project, available for download from www.sybex.com/go/masteringvb2010, demonstrates how to add items to and remove items from a menu at runtime. The main menu of the application's form contains the Run Time Menu submenu, which is initially empty.

The two buttons on the form add commands to and remove commands from the Run Time Menu. Each new command is appended at the end of the menu, and the commands are removed from the bottom of the menu first (the most recently added commands are removed first). To change this order and display the most recent command at the beginning of the menu, use the Insert method instead of the Add method to insert the new item. Listing 6.12 shows the code behind the two buttons that add and remove menu items.

Private Sub bttnAddItem_Click(...) Handles bttnAddItem.Click
   Dim Item As New ToolStripMenuItem
   Item.Text = "Run Time Option" &
             RunTimeMenuToolStripMenuItem.DropDownItems.Count.ToString
   RunTimeMenuToolStripMenuItem.DropDownItems.Add(Item)
   AddHandler Item.Click, New System.EventHandler(AddressOf OptionClick)
End Sub

Private Sub bttnRemoveItem_Click(...) Handles bttnRemoveItem.Click
   If RunTimeMenuToolStripMenuItem.DropDownItems.Count > 0 Then
       Dim mItem As ToolStripItem
       Dim items As Integer =
                   RunTimeMenuToolStripMenuItem.DropDownItems.Count
       mItem = RunTimeMenuToolStripMenuItem.DropDownItems(items - 1)
   RunTimeMenuToolStripMenuItem.DropDownItems.Remove(mItem)
   End If
End Sub

The Remove button's code uses the Remove method to remove the last item in the menu by its index after making sure the menu contains at least one item. The Add button adds a new item and sets its caption to Run Time Option n, where n is the item's order in the menu. In addition, it assigns an event handler to the new item's Click event. This event handler is the same for all the items added at runtime; it's the OptionClick() subroutine. All the runtime options invoke the same event handler — it would be quite cumbersome to come up with a separate event handler for different items. In the single event handler, you can examine the name of the ToolStripMenuItem object that invoked the event handler and act accordingly. The OptionClick() subroutine used in Listing 6.13 displays the name of the menu item that invoked it. It doesn't do anything, but it shows you how to figure out which item of the Run Time Menu was clicked.

Private Sub OptionClick(...)
    Dim itemClicked As New ToolStripMenuItem
    itemClicked = CType(sender, ToolStripMenuItem)
    MsgBox("You have selected the item " & itemClicked.Text)
End Sub

Nearly every Windows application provides a context menu that the user can invoke by right-clicking a form or a control. (It's sometimes called a shortcut menu or pop-up menu.) This is a regular menu, but it's not anchored on the form. It can be displayed anywhere on the form or on specific controls. Different controls can have different context menus, depending on the operations you can perform on them at the time.

To create a context menu, place a ContextMenuStrip control on your form. The new context menu will appear on the form just like a regular menu, but it won't be displayed there at runtime. You can create as many context menus as you need by placing multiple instances of the ContextMenuStrip control on your form and adding the appropriate commands to each one. To associate a context menu with a control on your form, set the ContextMenu property for that control to the name of the corresponding context menu.

Designing a context menu is identical to designing a regular menu. The only difference is that the first command in the menu is always ContextMenuStrip and it's not displayed along with the menu.