Advanced Visual Basic (Visual Studio 2008) - Project 4

Adding a Menu, About dialog and Help System to Database Snooper

Project 4

As it currently stands, the Database Snooper program is incomplete. A primary feature of virtually all Windows applications is a comprehensive "online" help system. Help systems come in a couple of strengths: A Help File provides a standard level of user assistance, while Context Sensitive Help provides a more readily available level of user aid that is integrated into your application. This project will add both a Help File and Context Sensitive Help to the Database Snooper program.

The Fourth Project

This project will be an enhancement of the last project (DatabaseSnooper).

Open your DatabaseSnooper project in Visual Studio 2008.

The common way to access an application’s Help File is via the Contents or Index item under its Help dropdown menu. In an effort to maintain the Windows Program Design Philosophy that gives all windows applications a consistent look and feel, you will now add a menu structure to your project which will include both File and Help menu items.

Adding a MenuStrip control to the form

Double-click on the MenuStrip item in the Menus & Toolbars section of the Control Toolbox to add a MenuStrip control (MenuStrip1) to the Component Tray.  Once added to your project, the MenuStrip control appears in the Component Tray at the bottom of the design window, like this:

To have your form use this menu, be sure the the MainMenuStrip property of frmDatabaseSnooper is set to MenuStrip1—which it should have been set to automatically when you added the MenuStrip control.  Click once on the MenuStrip1 control in the Component Tray to selected it.  The new blank menu should appear in the upper left corner of the form, like this.  Note: You may need to stretch the form bigger vertically and move all the controls down to make room for MenuStrip1 at the top:

Create the menu structure outlined below.  Note: To insert a Separator (the line between menu items), right-click on the menu item where the separator is to go and choose Separator from the Insert submenu off the context menu.

Menu Table
Level 1 Text	Level 2 Text	Name
&File		(default name)
	&Open Database	mnuOpen
	(Insert Separator)
	E&xit	mnuExit
&Help		(default name)
	&Contents	mnuContents
	(Insert Separator)
	&About	mnuAbout

The finished Help part of the menu should look like this:

I leave it to you to supply functionality to the menu items under the File dropdown menu (Open Database and Exit). Do so before continuing.

Creating a About Dialog box

To create an About Dialog we will need to add another Form to our project.  Select Add Windows Form... from the Project drop down menu, and the Add New Item dialog will appear:

Make sure the About Box template is selected, then type frmAbout.vb in the Name text box, as shown above, and click the Add button. You should now see the new frmAbout.vb form in your Solution Explorer window:

The frmAbout.vb form should look like this in the Designer window:

An About dialog can contain a variety of information, but at a minimum any About dialog should include the following items:

1. The name of the program and the programmer (you)
2. A brief description of the program and what it does
3. Copyright information
4. Version information
5. A warning disclaimer: So you can't be sued when your application destroys someone's computer

Take a look at the code view of the frmAbout.vb form.   Specifically, the code that is already in the form's Load event procedure:

Do not modify the above code!  The My.Application.Info class provides you with some pre-existing properties that you can set at design time.  They include Title, AssemblyName, Copyright, CompanyName, ProductName, Description, etc. These property values will automatically populate your About dialog box at run time.  To set these properties, do the following:

Display the project properties window by right-clicking on your project (DatabaseSnooper) at the top of the Solution Explorer window and select Properties:

With the Application tab selected on the top left, click the Assembly Information button, circled in the above illustration, to display the Assembly Information dialog:

Fill in all the property values on the Assembly Information dialog and click the OK button.  The following illustration is an example of the About dialog for my version of Database Snooper. 

The amount of effort you want to put into creating your About dialog is up to you.  But it should contain, as a minimum, the five items listed previously.  Finish creating your About dialog box before going on.

Showing and closing your About dialog box

To show the About dialog (frmAbout), add this code to the mnuAbout_Click event procedure of the frmDatabaseSnooper form:

Dim frmAbout As New frmAbout()
frmAbout.ShowDialog()

We use the ShowDialog method to display the About dialog instead of the normal Show method.  This displays the About dialog as a modal dialog with our frmDatabaseSnooper form as its parent form.  This forces the user to close the About dialog before they can interact with the program again—just like a messagebox.

Testing the About dialog

Save the project now.  Run the program.  Pull down the Help menu and click on About.  Does the about dialog work?

Using HTML Help Workshop to create a Help File for Database Snooper

Note: For installing HTML Help Workshop at home or work.  HTML Help Workshop does not come with Microsoft Visual Studio.  You can download the latest version of HTML Help Workshop from here at the msdn.microsoft website. 

To create a Help file in HTML Help Workshop, we begin by building several HTML documents.  In fact, creating enough HTML documents to build a mini-website is commonly required.  Since this isn't an HTML class, I've provided several HTML documents that you will need to create the help file.  You'll find them inside the c:\shared\hhw folder (Note: If you are working on this project from home, you may download these files by clicking this link). 

Exit Visual Studio 2008 for this part of the exercise.  Right-click on the My Computer icon on the desktop and choose Explore to open the Windows Explorer window.  Navigate to, and open, the c:\shared\hhw folder.  You should see the following files inside it:

Double-click on the index.htm file, to view it in Internet Explorer:

This will be the Main page of the Help file for Database Snooper.  This example is relatively simple, but the level of complexity is up to you.  At the bottom of the page are several Links to three other pages that describe different functions of the Database Snooper program.  Click on them now to see what they look like.  At the bottom of each page is a [Home] link that takes you back to the index.htm page (shown above).  We will take these four HTML documents and build our Help file with the HTML Help Workshop application. 

Close the Internet Explorer and Windows Explorer windows.  Run the HTML Help Workshop application—you will find it on the Programs menu inside the HTML Help Workshop folder.  Choose New on the File drop-down menu and the New dialog should appear: 

Select the Project item and click the OK button.  This launches the New Project wizard:

We are not converting a WinHelp project file (WinHelp is the older—still supported—method of creating help files), so leave that check box unchecked and click the Next button to display the Destination dialog:

Use the Browse button and browse to the c:\shared\hhw folder.  Type DatabaseSnooper in the File Name text box for the project file name and click the Open button.  The Destination dialog should now look similar to the above illustration, with the full path to the new DatabaseSnooper.hhp file displayed.  Now click the Next button to display the Existing Files dialog:

We will be creating our Table of Contents and Index files later so leave those checkboxes unchecked.  But we already have our HTML files, so put a checkmark in front of HTML files (.htm) and click the Next button to display the HTML Files dialog:

Use the Add button and select each of the HTML documents in the c:\shared\hhw folder.  Note: Be sure to select the index.htm document first.  The first file in the list is assumed by HTML Help Workshop to be the Main HTML file in the project (like the home page). The order in which you select the other three files does not matter.  Then click the Next button, and finally, click the Finish button on the final dialog that appears—If you see a messagebox asking if you want to overwrite any existing files, do so.  Your HTML Help Workshop window should now look like this:

Notice under the [OPTIONS] section that the Default Topic file is index.htm, that is because it was the first HTML file we added in the HTML Files dialog.  Before creating our Table of Contents and Index files, let's take a look at what the help file will look like if we compile it right now.  Click on the Compile HTML File button—circled on the above illustration—on the toolbar to display the Create a Compiled File dialog:

The name for your HTML Help Project file (DatabaseSnooper.hhp) is selected automatically.  Click the Compile button.  When compilation is complete, you should see this summary of the compile in the right panel of the HTML Help Workshop screen:

Now click the View Compiled File button on the toolbar (it is next to the Compile button) to display the View Compiled File dialog:

Use the Browse button and select your compiled Help file (it has a .chm extension).  Your View Compiled File dialog should match the illustration above.  Click on the View button.  When the Help Window opens you may need to resize it to see it all.  Test the links at the bottom of the page to make sure they work.  This should remind you of when we opened the index.htm file in Internet Explorer earlier.  As you can see, creating the basic Help File components for HTML Help Workshop just requires the HTML documents of a small website.  Close the help window when you are finished testing it.

Creating a Table of Contents file in HTML Help Workshop

A Table of Contents is a common component for your help file.  Creating one in HTML Help Workshop is pretty easy.  On the HTML Help Workshop screen, click on the Contents tab at the top of the left panel to display the Table of Contents Not Specified dialog:

Make sure the Create a new contents file option is selected and click the OK button.  On the Save As dialog accept the default name, Table of Contents.hhc, and click the Save button.  You should now see an empty Contents pane, with a column of buttons down the left side, like this:

To start adding items to the empty Contents pane, click on the Insert a Heading, button (circled above), to display the Table of Contents Entry dialog:

In the Entry Title text box type: Introducing Database Snooper, then click the OK button.  The new folder entry appears at the top of the Contents pane:

Now let's insert a page inside this folder.  Make sure the folder is selected and click the Insert a Page button (circled above).  The following message box should appear.  To put this new page inside the Introducing Database Snooper folder be sure to click on the No button:

The Table of Contents Entry dialog for the new page appears:

Type Features for the title of the new page in the Entry Title text box.  Headings (folders) that you add to the contents pane do not need to have an associated HTML file or URL.  But Pages you add to the contents pane must have an associated HTML file or URL.  Click on the Add button below the Entry Title text box and then use the Browse button on the next dialog to select the index.htm file as the HTML file to associate with this new page.  Then your Table of Contents Entry dialog should look exactly like the illustration above.  Now click the OK button. 

Your Contents pane should now look like the illustration above.  Add another heading (folder) by clicking the Insert a Heading button. Type View Options in the Entry Title text box and click the OK button.  Your Contents pane show now look like this:   

Notice that the new heading you added is actually inside Introducing Database Snooper heading.  To move it back to the left edge of the pane and take it out of the Introducing Database Snooper heading, click the Move Selection Left button which is circled in the above illustration.

You will now insert three new pages inside the View Options heading.  Click the Insert a Page button now.  Notice that you should not see the message box asking you if you want to insert this page at the beginning of the table of contents, like we did when we added the Features page to the Introducing Database Snooper heading (if you do see this message box choose No).   Add three new pages to the View Options folder with these settings:

Page #	Entry Title	Associated HTML file
1	Tables	tables.htm
2	Fields	fields.htm
3	Records	datagrid.htm

Your Contents pane should now match the following illustration:

Before adding the Index, let's test the new Table of Contents.  Select Save Project on the File drop-down. Then click the Compile HTML file button on the toolbar. When the compile is finished click the View compiled file button to view your new help file.  Notice the new Toolbar at the top of the Help window.  This toolbar will not appear until we have at least a Contents pane in our help project:

Click on the Show button to see the Contents pane:

Click on the plus (+) signs in front of the heading folders to open them and see the pages they contain.  Click on the pages to see their associated HTML documents in the right pane.  You can also click on the Hide button on the toolbar to hide the contents pane again.  With the Contents pane visible, close the help window.

Creating an Index file in HTML Help Workshop

By adding an Index, the user will be able to search for help by selecting from a list of key words that you specify.  An Index is another common component of help files, and most help files include one.  Creating an Index in HTML Help Workshop is not difficult.  On the HTML Help Workshop screen, click on the Index tab at the top of the left panel to display the Index Not Specified dialog:

Make sure the Create a new index file option is selected and click the OK button.  On the Save As dialog type Database Snooper Index.hhk for the index file name, and click the Save button.  You should now see an empty Index pane, with a column of buttons down the left side, that looks like this:

To start adding keywords to the empty Index pane, click on the Insert a keyword button now (circled above) to display the Index Entry dialog:

This dialog is identical to the Table of Contents Entry dialog.  In the case of index keywords, each keyword you add must have an associated HTML file or URL.  For the first keyword type, Tables. Use the Add button, below the Keyword text box, and selected the tables.htm file to associate with it.  Click the OK button.  Continue adding the follow keywords with these settings:

New Keyword #	Keyword	Associated HTML file
1	Fields	fields.htm
2	Records	datagrid.htm
3	Features	index.htm
4	Over View	index.htm

As you can see, most of this information duplicates what we added in the Contents pane.  When you are finished adding the above keywords, your Index pane should match the following illustration.  Use the Sort Keywords Alphabetically button (circled below) to sort your keywords alphabetically:

Select Save Project on the File drop-down. Then click the Compile HTML file button. When the compile is finished click the View compiled file button to view your new help file.  Click on the Index tab at the top of the left pane.  Notice one important difference between the Contents and Index panes is the ability to type a keyword to search the keyword list.  That can come in really handy for help files that use dozens of HTML documents and have Indexes that contain hundreds of keywords. 

Notice while you are viewing your newly compiled help file that the caption of the help window is the generic word Help.  This is because we haven't set the Title option yet.  Close the help window and return to the HTML Help Workshop screen. 

Click on the Project tab and click the Change Project Options button (circled above) to open the Options dialog:

With the General tab selected, type Database Snooper in the Title textbox and click the OK button.  Click Save Project on the File drop-down. Then click the Compile HTML file button. When the compile is finished click the View compiled file button to view your new help file.   The caption of the help window will now be Database Snooper.  Close the Help window and exit the HTML Help Workshop application.

Putting a copy of the finished Help file in the DatabaseSnooper folder and the \bin\Debug folder

We need to put a copy of the DatabaseSnooper.chm help file in the same folder as the compiled version of our program file, DatabaseSnooper.exe.  Because when we deploy an application that is where the help file is usually installed.  Right-click on the My Computer icon or the Start menu button and select Explore on the context menu.  Navigate to the c:\shared\hhw folder and open it.  Find your DatabaseSnooper.chm help file inside it, then right-click on it and select copy from the context menu.  Now open your My Documents\Visual Studio 2008\Projects\DatabaseSnooper folder.  Right-click inside the DatabaseSnooper folder and select paste to put a copy of your help DatabaseSnooper.chm file inside it.  Now navigate to the \bin\Debug folder here:

    ...\My Documents\Visual Studio 2008\Projects\DatabaseSnooper\bin\Debug

Right-click inside the Debug folder and select paste to put a copy of your help DatabaseSnooper.chm file inside it along with the DatabaseSnooper.exe file.

Adding the Help file to the Database Snooper program

Run Visual Studio 2008 and open your DatabaseSnooper project.  Add the following dimension statement to the Declarations section of frmDatabaseSnooper:

'Stores the path and filename of the Help file
Dim sHelpFile As String

In Visual Studio 2008 we have several intrinsic classes/objects—built-in, pre-created objects which are available within all your projects—which are very useful.  One of these classes/objects is called Application.  The Application class has several powerful methods that return information about the application.  For example, the StartUpPath method always returns the location of the application's executable file (DatabaseSnooper.exe).   Since we need to set the value of the sHelpFile string to the path and filename of our help file, the Application.StartUpPath method will come in very handy.  Type the following line of code into the frmDatabaseSnooper_Load event procedure:

'Set sHelpFile to the path & filename of
'    the help file.
sHelpFile = Application.StartUpPath & _
                  "\DatabaseSnooper.chm"

Now we can use the ShowHelp method of the intrinsic Help class to display our help file.  Add the following line of code to the mnuContents_Click event procedure:

'Display the help file
Help.ShowHelp(Me, sHelpFile)

Testing the program so far

Save the project now.  Run the program.  Select the Contents item on the Help menu.  Is your help file displayed?  

Using a HelpProvider component to add Context Sensitive Help

In it's most basic role, adding a HelpProvider component to your project's component tray—and settings its HelpNamespace property to the location of your DatabaseSnooper.chm help file—allows the user to access the help file by pressing the F1 function key.  But the addition of a HelpProvider component also adds four new properties to each of the controls on your form including the form itself.  These new properties will allow us to add context sensitive help to Database Snooper.  

Locate the HelpProvider item in the Components section of the control toolbox and double-click on it.  It will appear in your component tray, like this:

Leave the default name HelpProvider1 unchanged.  We need to set the HelpNamespace property of HelpProvider1 to the location of the DatabaseSnooper.chm help file.  Add the following code at the end of the frmDatabaseSnooper_Load event procedure (below the previous code you've added there):

'Set the HelpNamespace property of HelpProvider1
'    to the path and filename of the Help file.
HelpProvider1.HelpNamespace = sHelpFile

Take a look at the properties of the form, you should see these four new properties (the only one we will be modifying is the HelpString on HelpProvider property):

• HelpKeyword on HelpProvider1 — Specifies the help keyword associated with this control
• HelpNavigator on HelpProvider1 — Specifies the type of help associated with this control
• HelpString on HelpProvider1 — Specifies the help text for context sensitive help for this control
• ShowHelp on HelpProvider — Determines if help should be displayed for this control

For the addition of Context Sensitive Help, we will only be working with the HelpString on HelpProvider property.  Type the following help strings into the HelpString on HelpProvider property of the listed controls:

Controls	HelpString on HelpProvider1
lblDatabaseName	This Label displays the name of the currently opened database file
lstTables	This list box displays the names of the tables of the currently opened database (shown in the label above).  By selecting one of these tables with the mouse, the fields it contains, and their data types are shown on the Fields listbox to the right.
lstColumns	This list box displays the column names and their data types of the table that is selected in the listbox directly to the left.  By selecting a field from this list with the mouse, the records displayed in the data grid on the right are sorted by the field you select.
btnBigSmall	Use this button to make the form wider so that you can see more of the columns in the DataGridView.
DataGridView1	This data grid displays the records of the currently selected table from the Tables list box to the far left.  You may sort these records by selecting the field to sort by from the Fields list box to the left.

Adding the Help Button to the Database Snooper form

The final step requires the addition of the Help Button to the form.  While a help button—which appears as a question mark button next to the Close button in the upper right corner of the form—is normally only available on dialog boxes, we will be adding one to database snooper as part of the context sensitive help support.  Take a look at the properties of the form and set these properties like so:

Property	Value
Maximize Box	False
Minimize Box	False
Help Button	True

The downside of a Help Button is that you must disable the Minimize and Maximize buttons for it to show.  The upper right corner of your form in design view should now look like this:

Testing the finished program

Save the project now.  Run the program.  Notice the question mark (Help) button in the upper right corner of the form next to the close button?  Click on the help button.  The mouse pointer should change so that a big question mark (?) is attached to it.  Point at any of the controls on the form that had help text added to their HelpString on HelpProvider property and click on it.  Does a popup appear displaying the text you typed into its HelpString on HelpProvider property?   Does pressing the F1 key display your help file?

There are no further enhancements required for this project.