Context-sensitive help for menu items in Windows Forms

Question

I am implementing context-sensitive help for an existing WinForms app built in Visual Studio .NET. I have added a HelpProvider to the form and set the HelpNamespace property to a wonderful .chm that covers every control and menu item on the form. I have set the necessary HelpKeyword on all the controls that derive from Control and so far all is great: F1 works perfectly.

My problem is that I can't work out how to do it for menu items. These use the ToolStripMenuItem class, which does not derive from Control and so has no HelpKeyword property. How should I provide context-sensitive help for individual menu items? Mr. Google has not been very forthcoming.

Answer 1

Using F1 is not a common way of providing help for menu items. Menu items usually use ToolTip, or show some help text in StatusBar or usually their comprehensive helps comes with Help content of main page.

I prefer to use one of above mentioned solutions, but here for learning purpose, I'll show what you can do using HelpRequested event of the form.

To handle help for form and controls, you can rely on the HelpRequested event of the form and controls.

Here you can rely on Form event to solve the problem. Since you have a HelpProvider on form, you should know HelpProvider handles HelpRequested event of all controls internally and, for controls having ShowHelp set to true, it sets Handled to true and prevents bubbling the event up so you can not have your custom code for handling help event if ShowHelp is true. So you should set ShowHelp for controls to false and just use HelpProvider as a help key holder.

To solve the problem using the HelpRequested event of the form, you should follow these steps:

1. For ToolStripMenuItems, use the Tag property as the help key holder.
2. For other controls, if you use HelpProvider to assign HelpKey, don't forget to set ShowHelp to false.
3. Handle the HelpRequested event of the form.
4. In the body of event handler, check if there is an active menu item on your form, then use the Tag property of the active item to show help. If there is not any active menu, use the ActiveControl property of the form to show the help.

Example

Here is a step by step example of how you can show help for menu items using F1 key. To do so, follow these steps:

1. Create Form, Menu and Controls - Create a Form and put some controls and a MenuStrip having some menu and sub menus on the form.
2. Configuring HelpProvider - Put a HelpProvider control on form and for each control assign suitable key to HelpKeyword property of control. Also set ShowHelp for each control to false. We will handle help in code.
3. Configuring Help for Menu - For a ToolStripMenuItem use its Tag property to store the help keyword.

4. Creating a helper method to find descendants of the Menu - Add a class to your application having the following code. In the following code, I've introduced an extension method to get all sub ToolStripMenuItem of a MenuStrip:

   using System.Collections.Generic;
   using System.Linq;
   using System.Windows.Forms;
   public static class ToolStripMenuItemExtensions
   {
       public static List<ToolStripMenuItem> Descendants(this MenuStrip menu)
       {
           var items = menu.Items.OfType<ToolStripMenuItem>().ToList();
           return items.SelectMany(x => Descendants(x)).Concat(items).ToList();
       }
       public static List<ToolStripMenuItem> Descendants(this ToolStripMenuItem item)
       {
           var items = item.DropDownItems.OfType<ToolStripMenuItem>().ToList();
           return items.SelectMany(x => Descendants(x)).Concat(items).ToList();
       }
   }
   

5. Handling the Helprequested event to show help - Handle the HelpRequested event of the form and implement the algorithm which I described above using the following code:

   private void Form1_HelpRequested(object sender, HelpEventArgs hlpevent)
   {
       string keyword = "";
   
       var selectedMenuItem = this.menuStrip1.Descendants()
           .Where(x => x.Selected).FirstOrDefault();
       if (selectedMenuItem != null)
           keyword = selectedMenuItem.Tag?.ToString();
       else if (ActiveControl != null)
           keyword = helpProvider1.GetHelpKeyword(ActiveControl);
   
       if (!string.IsNullOrEmpty(keyword))
           Help.ShowHelp(this, "Help.chm", HelpNavigator.Index, keyword);
   }
   

Note

• For testing the solution you don't need a chm file having index and so on. You can simply show the helpkeyword in Text property of form. It means the solution is working and after that you can create suitable chm file.
• You can use one of the other overloads of ShowHelp method of Help class based on your requirement.
• There are HelpKeyword and HelpString extended properties for controls, pay attention which one you are using and get the same one in the HelpRequested event.
• Don't forget to set ShowHelp to false. If you forget this step, the event will be handled internally in Helpprovider.
• Don't forget to assign a help keyword to Tag property of menu items. To make it more friendly for future, you can simply create an extender provider that adds a help keyword property to menu items.