Standard Components

The following is a quick survey of the components immediately available in the Windows Forms Toolbox by default. ^[1]

^[1] .NET provides many more components that can be used with WinForms applications, but a survey of all those is beyond the scope of this book.

Standard Dialogs

WinForms provides several standard dialog components that act as wrappers on the standard dialogs in the Windows shell. ^[2] All the standard print- related components ”PageSetupDialog, PrintDialog, PrintPreviewDialog, and PrintDocument ”are covered in Chapter 7: Printing.

^[2] Because the need for previewing print output is prevalent , WinForms provides a standard PrintPreviewDialog even though the Windows shell does not.

Figures D.2, D.3, D.4, D.5, and D.6 show the four remaining standard dialogs as provided by the ColorDialog, FontDialog, OpenFileDialog, SaveFileDialog, and FolderBrowserDialog components.

Figure D.2. A Sample Usage of the ColorDialog Component

Figure D.3. A Sample Usage of the FontDialog Component

Figure D.4. A Sample Usage of the OpenFileDialog Component

Figure D.5. A Sample Usage of the SaveFileDialog Component

Figure D.6. A Sample Usage of the FolderBrowserDialog Component

Generally, you're most concerned with the Color property of ColorDialog, the Font property of FontDialog, and the FileName property of OpenFileDialog and SaveFileDialog. However, all the dialogs provide other properties you'll want to examine, including the DefaultExt and Filter properties of OpenFileDialog and SaveFileDialog. Here's an example of the standard dialog components assuming that each of the components was created by dropping it onto a design surface:

 // Use the ColorDialog void chooseColor_Click(object sender, EventArgs e) {   // Set initial color   this.colorDialog1.Color = this.BackColor;   // Ask the user to pick a color   if( this.colorDialog1.ShowDialog() == DialogResult.OK ) {     // Pull out the user's choice     this.BackColor = this.colorDialog1.Color;   } } // Use the FontDialog void chooseFont_Click(object sender, EventArgs e) {   // Set initial font   this.fontDialog1.Font = this.Font;   // Ask the user to pick a font   if( this.fontDialog1.ShowDialog() == DialogResult.OK ) {     // Pull out the user's choice     this.Font = this.fontDialog1.Font;   } } // Use the OpenFileDialog (used just like the SaveFileDialog) void chooseFileToOpen_Click(object sender, EventArgs e) {   // Set initial file name   this.openFileDialog1.FileName = this.fileNameTextBox.Text;   // Ask the user to pick a file   if( this.openFileDialog1.ShowDialog() == DialogResult.OK ) {     // Pull out the user's choice     this.fileNameTextBox.Text = this.openFileDialog1.FileName;   } }

All the standard dialogs, including the print-related dialogs (except for PrintPreviewDialog), are limited to only modal operation via ShowDialog because that's what the shell dialogs support. Only PrintPreviewDialog, which is provided in WinForms but not provided in the shell, supports the modeless Show method.

Notify Icons

Another service provided by the Windows shell is the notification tray, where applications can put their own icons to interact with the user, as shown in Figure D.7. The NotifyIcon component has the following interesting properties and events:

Visible property : whether or not the icon is shown on the tray
Icon property : the icon to show
Text property : the tooltip over the icon
ContextMenu property : the menu to show when the user right-clicks on the icon
Click event : when the user clicks on the icon or selects from the context menu
Double-Click event : when the user double-clicks on the icon
MouseDown, MouseMove, and MouseUp events : custom interaction with the user

Figure D.7. A Sample Usage of the NotifyIcon Component

Figure D.7 shows a notify icon implemented with the following code. It sets the tooltip text and icon at run time based on the user clicking and choosing menu items from a context menu:

 // Icons Icon northIcon = new Icon(@"C:\...\ARW02UP.ICO"); Icon eastIcon = new Icon(@"C:\...\ARW02RT.ICO"); Icon southIcon = new Icon(@"C:\...\ARW02DN.ICO"); Icon westIcon = new Icon(@"C:\...\ARW02LT.ICO"); // Helper void SetDirection(string direction) {  // Set the tooltip   compassNotifyIcon.Text = direction;   // Set the icon  switch( direction ) {     case "North":  compassNotifyIcon.Icon = northIcon;  break;     case "East":  compassNotifyIcon.Icon = eastIcon;  break;     case "South":  compassNotifyIcon.Icon = southIcon;  break;     case "West":  compassNotifyIcon.Icon = westIcon;  break;   } }  // Context menu item: North   void northMenuItem_Click(object sender, EventArgs e) {  SetDirection("North");  }   // Context menu item: East, South, and West elided   // Click handler   void compassNotifyIcon_Click(object sender, EventArgs e) {  switch( compassNotifyIcon.Text ) {     case "North": SetDirection("East"); break;     case "East": SetDirection("South"); break;     case "South": SetDirection("West"); break;     case "West": SetDirection("North"); break;   }  }

Timer

The example in Figure D.7 uses mouse clicks to do some primitive animation of the notify icon, but a more fun implementation would do animation itself. Because animation is simply a matter of changing an image after a certain amount of time has elapsed, our code to change the image is halfway there. All that's needed is a way to be notified when a certain amount of time has elapsed, a perfect job for the Timer component.

The Timer component notifies a listener via the Tick event based on two properties. The Enabled property must be set to true for the Tick event to fire. The Interval property is the number of milliseconds to wait between Tick events. The following example uses a timer to animate the notify icon:

 // Notify icon click handler void compassNotifyIcon_Click(object sender, EventArgs e) {  // Toggle animation   timer1.Enabled = !timer1.Enabled;   timer1.Interval = 1000; // Animate once/second  }  // Timer Tick event handler   void timer1_Tick(object sender, EventArgs e) {  switch( compassNotifyIcon.Text ) {     case "North": SetDirection("East"); break;     case "East": SetDirection("South"); break;     case "South": SetDirection("West"); break;     case "West": SetDirection("North"); break;   }  }

Image List

All this animation brings to mind the task of managing images, and that's what the ImageList component is for. An image list is a collection of images of the same size, color depth, and transparency color (as determined by the Size, ColorDepth, and TransparencyColor properties). The images themselves are in the Images collection and can contain any number of Image objects. You can edit the Images collection directly using Image Collection Editor, as shown in Figure D.8.

Figure D.8. Image Collection Editor

To use the ImageList after the images have been populated in the collection editor, you pull them by index from the Images collection property:

 void SetDirection(string direction) {   int index = -1;   switch( direction ) {     case "North": index = 0; break;     case "East": index = 1; break;     case "South": index = 2; break;     case "West": index = 3; break;   }   // Set background from the image list  this.BackgroundImage = backgroundImageList.Images[index];  }

What's nice about this code is that all the related images come from a single place. However, the ImageList component has some limitations:

You can't edit an image after it's been added; you must remove the old image and add the edited image.
You can have only a fixed size of up to 256 pixels in either dimension.
Image Collection Editor is difficult to use for images larger than 16 pixels in either direction.
You must access images by index; you can't access them by name.
Images are available only as type Image and not directly as type Icon, so if you need the Icon type you must convert it from Image.

These limitations, however, don't stop the image list from being useful. Chapter 8: Controls explains how to use image lists to set the images for toolbars and other controls that need small, fixed-size , related images.

Main Menus and Context Menus

The MainMenu component shows the menu at the top of a form and provides events when the user selects an item. The ContextMenu component, shown in Figure D.9, provides a menu to be associated with a control and invoked using the context mouse button (most often the right mouse button). Both the MainMenu and the ContextMenu components are covered in Chapter 2: Forms.

Figure D.9. A Sample Usage of the ContextMenu Component

Error Provider, Help Provider, and Tooltips

The ErrorProvider component gives you a way to notify users that a control has invalid data currently entered, as shown in Figure D.10.

Figure D.10. A Sample Usage of the ErrorProvider Component

HelpProvider supports the handling of the F1 key and ? button on a dialog. Figure D.11 shows an example of the pop-up help supported by the help provider.

Figure D.11. A Sample Usage of the HelpProvider Component

As yet another way to show pop-up information, Figure D.12 shows the ToolTip component, which pops up when a user hovers the mouse over a control.

Figure D.12. A Sample Usage of the ToolTip Component

The error provider, the help provider, and the tooltip component are especially useful when you're building forms to be used as dialogs, so these components are discussed in detail in Chapter 3: Dialogs.