Bridging the Gap between Developers and Help Authors with ComponentOne DynamicHelp™

 

Introduction

One of the most important aspects of any application is having a thorough and easy-to-use method for end-users to access Help about how the application works. For those developers creating Windows Forms applications, look no further. With ComponentOne DynamicHelp for WinForms, you can easily add context-sensitive Help to your project in mere minutes. It also allows you to easily change the Help sources or individual topics at run time. No need to rebuild your application when the Help file is modified. This article demonstrates how to add context-sensitive Help using a single .NET control, ComponentOne DynamicHelp.

About ComponentOne DynamicHelp

C1DynamicHelp is a Windows Forms control that allows developers to easily add robust, context-sensitive Help to their applications. This can be done either at design time or at run time using authoring mode. C1DynamicHelp's authoring mode enables developers to pass the application off to the Help authors so they can assign topics to controls.

Prerequisite

For this tutorial, you must have Microsoft Visual Studio 2008 or Visual Studio 2005 and ComponentOne Studio Enterprise installed. Free 30-day trials and yearly subscriptions of ComponentOne Studio Enterprise are available from the ComponentOne website.

Developer: Enabling ComponentOne DynamicHelp's Authoring Mode

The first few steps of setting up the .NET application for embedding Help are completed by the developer.

You really only need one line of code to enable authoring mode in C1DynamicHelp and another line to grab the topic map, but we are going to do a little more in this example. Code will be added to toggle authoring mode using the key combination Ctrl+Shift+A, and additional code will be added to remind you to save your Topic Map when you close the application, if you have not already done so.

Step 1: Create a Windows Forms Application

Open Microsoft Visual Studio 2008 or 2005, and select File | New Project from the main menu.

Select either Visual C# or VB.NET as your language. Select Windows Forms Application as the project type, and then enter a project name and Location. Click the OK button to proceed.

Step 2: Add Controls to the Windows Form

For this example, we are going to need the C1DynamicHelp control and a couple of UI controls to assign Help topics to. Before we add any controls to the form, we need to resize it so the controls we add are within readable dimensions. To do this, right-click on Form1 and select Properties. From the Properties window, locate the Size property and set its Width and Height sub-properties to 400 and 300 respectively.

Locate the C1DynamicHelp icon in the Visual Studio Toolbox, and double-click it to add it to your form.

The control will automatically dock to the right side of the form, and the "Help topic on c1DynamicHelp1" property will automatically be added to the form properties. Note: any newly added controls will also inherit this extender property.

Next, find the default TextBox control in the Visual Studio Toolbox, and double-click on it to add it to the form.

While the TextBox control is still selected, go to the Properties window and set the Text property to "Show topic on got focus."

Finally, find the TreeView control in the Visual Studio Toolbox and double-click to add it to the form.

With the TreeView selected, go to the Properties window and select the Nodes property. Click the ellipsis button to display the TreeNode Editor.

From the TreeNode Editor, add two Root nodes by clicking the Add Root button. Select the first root node and change the Name and Text property values to "Overview." Now select the second root node and change the Name and Text property values to "How to use."

The "How to use" node will need two child nodes, so click the Add Child button twice while that node is still selected. Select the first of these two child nodes and set the Name and Text Properties to "Design time." For the second child node, set the Name and Text Properties to "Runtime."

By default, the TextBox and TreeView controls will not be positioned or sized optimally, so resize and rearrange the controls similar to the screenshot below.

Step 3: Connect C1DynamicHelp to a Help Source

Place C1Sample.chm somewhere in your local project directory. You can find the *.chm file in the C:\Program Files\ComponentOne Studio.NET 2.0\C1DynamicHelp\Tutorials\Data directory by default.

Select the C1DynamicHelp control and click the SmartTag to open the C1DynamicHelp Tasks menu. From the Tasks menu, click the ellipsis button beside the HelpSource property. This will display a file selection dialog box. Browse to the C1Sample.chm file and add it as the Help source.

Step 4: Set Up Authoring Mode

Now set up C1DynamicHelp so that it can be used in authoring mode. Select Form1 and locate the KeyPreview property in the Properties window. Set the KeyPreview property to "True."

Double-click on Form1, which will serve the purpose of adding the Form1_Load event and showing the code view. While the code view is displayed, we will add all of the code needed for the example, beginning with an override for the OnKeyDown event. We are overriding the OnKeyDown event so that a simple key combination, Ctrl+Shift+A, will toggle authoring mode. Add the following code somewhere outside of the Form1_Load event that we just added:

C#

// toggle authoring mode when the user hits Ctrl+Shift+A
override protected void OnKeyDown(KeyEventArgs e)
{
   if (e.KeyCode == Keys.A && e.Control && e.Shift)
   {
      c1DynamicHelp1.AuthoringMode = !c1DynamicHelp1.AuthoringMode;
   }
   base.OnKeyDown(e);
}

VB.NET

‘ toggle authoring mode when the user hits Ctrl+Shift+A
Protected Overrides Sub OnKeyDown(ByVal e As System.Windows.Forms.KeyEventArgs)
   If (e.KeyCode = Keys.A And e.Control And e.Shift) Then
      C1DynamicHelp1.AuthoringMode = Not C1DynamicHelp1.AuthoringMode
   End If
   MyBase.OnKeyDown(e)
End Sub

Now, go back to the Form1_Load event and add one line of code to tell C1DynamicHelp to grab the Topic Map that will be created later:

C#

private void Form1_Load(object sender, EventArgs e)
{
   c1DynamicHelp1.TopicMap.Refresh();
}

VB.NET

Private Sub Form1_Load(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles MyBase.Load
   C1DynamicHelp1.TopicMap.Refresh()
End Sub

Finally, add a Form1_Closing event to give a user-friendly reminder to save the Topic Map that gets generated in authoring mode:

C#

private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{
   if (c1DynamicHelp1.TopicMap.HasChanges)
   {
      DialogResult result = MessageBox.Show(
         "Would you like to save the changes you made to control/topic map?",
         "C1DynamicHelp Tutorial", MessageBoxButtons.YesNoCancel , 
         MessageBoxIcon.Question);
      if (result == DialogResult.Yes)
         c1DynamicHelp1.TopicMap.Save();
      else if (result == DialogResult.Cancel)
         e.Cancel = true;
   }
}

For C# only, after you add the above code, go back to the design view and add the event handler for the FormClosing event through the Properties window. From the Properties window, click the lightning bolt icon, which will display a list of form events. Find FormClosing in the list, and select Form1_FormClosing from the drop-down to add the event handler.

VB.NET

Private Sub Form1_FormClosing(ByVal sender As System.Object, 
    ByVal e As System.Windows.Forms.FormClosingEventArgs)_
 Handles MyBase.FormClosing
   If (C1DynamicHelp1.TopicMap.HasChanges) Then
      Dim dr As DialogResult
      dr = MessageBox.Show(_
          "Would you like to save the changes you made to control/topic map?",_
          "C1DynamicHelp Tutorial", MessageBoxButtons.YesNoCancel, _
          MessageBoxIcon.Question)
      If (dr = DialogResult.Yes) Then
         C1DynamicHelp1.TopicMap.Save()
      ElseIf (dr = DialogResult.Cancel) Then
         e.Cancel = True
      End If
   End If
End Sub

For VB.NET, the event handler is included in the event code above.

At this point, we don't have the controls associated with the Help file, and we don't have context information for the Help file. The next section will show you how to create the topic map and associate it with the TextBox and TreeView nodes that we just added to our application. This is where the Help author enters.

Help Author: Using C1DynamicHelp's Authoring Mode

The last few steps of linking the Help topics to the controls are completed by the Help author.

Using authoring mode, a Help author can visually link the controls with their corresponding topics in the Help file, and then pass the generated XML file to the developer.

Step 1: Run the Application

Run the application and press the Ctrl+Shift+A keys together to activate authoring mode. You will see the authoring panel appear at the top of the DynamicHelp window.

Step 2: Map a Topic to the TextBox Control

To map a topic to the TextBox control, click the "Select control" button from the toolbar, and then select the TextBox control. You will see text selected in the Control field of the authoring panel change to textBox1 : TextBox.

Next, click the "Attach topic to control" button from the toolbar to display the Select Help Topic dialog box.

From the list on the Table of Contents tab, select the "Glossary of Terms" topic. Locate the group of checkboxes labeled Events in the upper-right corner of the dialog box, and make sure that the "Use default events" and "Mouse hover" checkboxes are unchecked. Only "Got focus" should be checked. Click OK.

The Glossary of Terms topic will be displayed when the TextBox gets focus.

Step 3: Map Topics to the TreeView Control

We are now going to map topics to each node of the TreeView. Note that in Visual Studio we could have used the "HelpTopic on C1DynamicHelp1" property to assign a Help topic to the TextBox, and we use the same property to set a Help topic for the entire TreeView, but you must use authoring mode to visually set the Help Topic for each individual TreeView Node. Any control that inherits from the .NET base class Control receives the "HelpTopic on C1DynamicHelp1" property when C1DyanmicHelp is added to the form. However, since each individual TreeView Node does not inherit from the Control class, authoring mode is the only way to visually assign a Help topic to a node.

Click the "Select control" button, and select the "Overview" node in the TreeView.

Then click the "Attach topic to control" button.

Again, you will see the Select Help Topic dialog box, with the Table of Contents tab preselected. From the table of contents, select the Overview topic, uncheck "Use default events" and "Mouse hover," and then click the OK button.

Repeat the steps described in the paragraph above, except this time select the "How to use" node and map it to the "How to use C1DynamicHelp" topic.

Continue the steps above two more times to assign the "Design time" node to the "Design time support" topic and the "Runtime" node to the "Runtime support" topic. Each node now has a Help topic linked to it. Save the topic map.

Click the diskette icon to save the topic map.

Your topic map should now be saved to the same location as the source Help file we linked to C1DynamicHelp, C1Sample.chm. The topic map will be named C1Sample.chm.xml and will look like this:

<Dictionary>
  <item>
    <key>Form1\c1DynamicHelp1\ControlCapture\groupBox1\controlTree</key>
    <value>WordDocuments/overview.htm</value>
    <events useDefaultEvents="False">1</events>
  </item>
  <item>
    <key>Form1\treeView1\Overview</key>
    <value>WordDocuments/overview.htm</value>
    <events useDefaultEvents="False">1</events>
  </item>
  <item>
    <key>Form1\treeView1\How to use\Design time</key>
    <value>WordDocuments/designtimesupport.htm</value>
    <events useDefaultEvents="False">1</events>
  </item>
  <item>
    <key>Form1\treeView1\How to use\Runtime</key>
    <value>WordDocuments/runtimesupport.htm</value>
    <events useDefaultEvents="False">1</events>
  </item>
  <item>
    <key>Form1\textBox1</key>
    <value>WordDocuments/glossaryofterms.htm</value>
    <events useDefaultEvents="False">1</events>
    <onload>True</onload>
  </item>
  <item>
    <key>Form1\treeView1\How to use</key>
    <value>WordDocuments/howtousec1dynamichelp.htm</value>
    <events useDefaultEvents="False">1</events>
  </item>
</Dictionary>

Step 4: View the Finished Product

First, here are a few things to keep in mind when you use C1DynamicHelp in your own applications. The source *.chm and the *.xml topic map should be kept in the same directory. When you are ready to release your application to customers, you should disable authoring mode. For the sample application, this would involve commenting out all of the code that we added other than the line in the Form1_Load event.

Now run the sample application without activating authoring mode. Select the TextBox control and the various nodes of the TreeView and notice that the topics we mapped in authoring mode are displayed.

Summary

ComponentOne DynamicHelp bridges the gap between developers and Help authors by simplifying the process of creating the topic/control mapping in an application. Rather than passing the topic/control map back and forth after every small change in project development, the developer can focus on creating a good application and the Help author can focus on writing good documentation without having to worry about context IDs.

• Add context-sensitive Help to your .NET applications today: Free Download