Lab 8: Help and Error Handling

Learning Objectives for Lab 8

After completion of today's lab, you should be able to

Use Tool Tips in a Windows application
Provide context-sensitive and HTML help in a Windows application
Use an error-provider to help with error handling
Use Regular Expressions to help with input validation
Use the Validating Event to help with error handling

Providing Help

While we would all like to design systems that are so intuitive and self-evident that uses never need assistance, the reality is that for some users, a good help system needs to be made available.

Providing help can take many forms: user manuals and documentation, web site support, wizards or agents, context-sensitive help, pop-up tips, and any number of other means.

One way of designing help systems is in examining the types of questions users may ask:

What kinds of things can I do with this program?
What is this? What does this do?
How do I do this?
Why did this happen?
Where am I?

Software designers need to consider providing support each of these type of questions.

ToolTip

The Windows Forms ToolTip extender control can be used to display a short, specialized help message for individual controls to answer questions of the type: What is this? or What does this do?

To add tooltips to your controls, using the Toolbox, drag and drop a ToolTip provider onto your Form. Once a ToolTip provider has been added to the form, to set a tooltip for any particular control

Select the control that will display the ToolTip
In the Properties window for that control, set the ToolTip on toolTip1 value to an appropriate string of text

Tooltips are most often used to display the name or directions for graphical controls that lack text labels. A good example is a toolbar, which in Visual Studio.NET, provides its own mechanism for providing tooltips.

See Design guidelines for Tooltips.

Activity: Using Tooltips

Activity: - Create an Email Dialog Box

Create a new project named WindowsUI in solution Lab8
Change the name of the Form1 file to MainForm.cs
Change the text displayed in MainForm's title bar to Send Email
In the design view, drag and drop controls onto the MainForm to create the email form shown at the right.
Compile and test your program

Activity - Add a Tooltip Control

From the Toolbox, drag a ToolTip Control onto the Form. toolTip1 will be placed in the component tray.
In the Design View, click on the toTextBox and set the ToolTip on toolTip1 to "Enter the recipient's Email address"
Compile and test your program

Activity: Using Images with Buttons

For many users, images can often be faster and easier to recognize than text. Coming up with the right images can be tough however.

Activity - Add a image to the Send Email button

Right-click, download and save the email image (a gif file) to your project
In Designer view, select the SendEmailButton and set its Image property to the the file sendEmail.gif
Set the button's Text property to the empty string
Set the button's ToolTip to "Send Email"
Compile and test your program

Sending Email

While we do not need it for this prototype, .NET does allow for the sending of Email.

Add using System.Web.Mail; to your code
Include the following code in your SendEmailButton_Click event handler method

using System.Net.Mail;

   private void sendEmailButton_Click(object sender, System.EventArgs e) 
   {
       MailMessage mail = new MailMessage(fromTextBox.Text, toTextBox.Text);

       mail.Subject = subjectTextBox.Text;
       mail.Body = messageTextBox.Text;

       // your real server should go here, this will not work from lab
       // SmtpClient s = new SmtpClient("localhost");

       // s.Send(mail); 
   }

Whenever code has the potential to throw an error, consider placing it inside a try..catch statement.

Dynamic Tooltip contents

The text for tooltips may be set in code as well as with Visual Studio's designer.

   private void SendEmailButton_MouseEnter(object sender, System.EventArgs e) 
   {
      toolTip1.SetToolTip(sendEmailButton, "Send email to " + toTextBox.Text);
   }

Context-Sensitive Help

While tooltips can be considered a form of context-sensitive help, .NET provides another extender control for providing context-sensitive help when the user presses the F1 function key: the HelpProvider Component.

Activity - Add a HelpProvider component to your Form

From the Components Toolbox, drag and drop a HelpProvider Control onto the Form. helpProvider1 will be placed in the component tray.
In the Design View, click on the fromTextBox and set the HelpString on helpProvider1 to "Enter your Email address"
Compile and test your program by clicking in the fromTextBox and pressing F1

Status Bar

This works OK if the user knows about it. The Status Bar area can be used to display a brief context-sensitive message related to the screen item with the focus.

Activity - Add a StatusStrip to your Form

From the Menus and Toolbars Toolbox, drag a StatusStrip Control onto the Form.
Use the controls smart tag to
- add a StatusLabel to your StatusStrip
- Set the toolStripStatusLabel1's Text property to the empty string
Add the event handler methods for your fromTextBox to set the message in the Status Bar with the Focus enters and leaves the fromTextBox
Compile and test your program by bring the focus in and out of the fromTextBox

  private void fromTextBox_Enter(object sender, EventArgs e)
  {
    toolStripStatusLabel1.Text = "Press F1 for Help";
  }
  private void fromTextBox_Leave(object sender, EventArgs e)
  {
    toolStripStatusLabel1.Text = String.Empty;
  }

What's This? Help Button

One form of the What's This help button is a icon located on the title bar of a secondary window. In Visual Studio.Net it is used in combination with the HelpProvider control as another way to produce context-sensitive help.

Activity - Add a What's This help button

in Design View, select the MainForm and set the HelpButton property to True
Compile and test your program by clicking the Help button and then bringing up the help message for the fromTextBox

HTML Help Files

Using HTML Help files with a browser or as compiled help files has become another common way to provide online help.

We can create a quick-and-dirty version of HTML help in Visual Studio by

Adding a starting HTML help web page to a project
- For more than one web page, it is a good idea to create a Folder inside WindowsUI named "WebPages"
- Add an index.html page here to start to start the global help. This page may link to other pages inside the folder.
Selecting the helpProvider1 control and setting its HelpNameSpace property to point to the WebPages/index.html file we created
- Avoid using absolute addresses to your Web pages as you never can be sure the program is installed inside a specific folder
- In this simple example, set the HelpNameSpace to "../../WebPages/index.html"

Microsoft makes available a HTML Help SDK that you would want to download and install if you decide to make use of advanced HTML Help features

You can invoke the simple Help HTML page in a browser from a menu item or button by using the static method ShowHelp in .NET's Help class

   private void helpButton_Click(object sender, EventArgs e)
   {
     Help.ShowHelp(this, helpProvider1.HelpNamespace);
   }

Or, to invoke the user's default Web browser to display help from a Internet address, one could use the Process.Start method

     System.Diagnostics.Process.Start("http://www.cwu.edu/~gellenbe/index.php");

Data Validation

Validation of user input is a huge part of any user interface project. One advantage of using radio buttons, list boxes, combo boxes, DateTimePickers, etc. is that they constrain user input so that validation becomes less of an issue.

User input in text boxes, on the other hand, should be checked for legal values and any errors reported back to the user.

Activity: Require a "To" Email address

Add the boolean method isValidEmailAddress to require a "To" Email address before the email gets sent
Call this method from the event handler method for your sendEmailButton_Click method

   private bool isValidEmailAddress() 
   {
      if (toTextBox.Text.Length == 0) 
      {
         MessageBox.Show("Please enter the Email address to send to", "Send Email",
                           MessageBoxButtons.OK, MessageBoxIcon.Error);
       return false;
      } 
      else 
     {
        return true;
     }
   }

Error Provider

Message Boxes can get pretty annoying if there are too many of them. A cleaner approach to providing an error message for invalid user input is to use an ErrorProvider component.

Activity: Add an ErrorProvider component

From the Components toolbox, Drag and drop an ErrorProvider component onto your EmailForm
Modify the isValidEmailAddress method to use errorProvider1 to display the error

   private bool isValidEmailAddress() 
   {
     if (toTextBox.Text.Length == 0) 
     {
       errorProvider1.SetError(toTextBox, "E-mail address required");
       return false;
     } 
     else 
     {
       errorProvider1.SetError(toTextBox, "");
       return true;
     }
   }

Regular Expressions

Regular expressions are very useful for error checking user input

using System.Text.RegularExpressions;

      //Only allow cwu.edu e-mail addresses
      Regex regularExp = new Regex("^[A-Za-z0-9]+@cwu\\.edu$");
      
      if (!regularExp.IsMatch(toTextBox.Text.Trim())
         //error - incorrect e-mail entered