Bridging the Gap between Developers and Help Authors with ComponentOne DynamicHelp

Applies To:

Studio for WinForms

Author:

Suelinda Webster

Published On:

9/11/2008

The 2008 v2 release of ComponentOne Studio Enterprise introduced a new product, ComponentOne DynamicHelp for WinForms. 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.

This article shows how the developer can set up Authoring mode for the Help author to visually map topics to UI elements on the application. This method saves time and eliminates the errors that are more likely to occur when repeatedly passing the topic/control map between developer and Help author.

Read on to see how you can work seamlessly together with Help authors and increase productivity with DynamicHelp for WinForms.

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 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. 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 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, select the ellipsis button beside the HelpSource property to 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 find 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 are going to add all of the code we will need 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 of course:

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.

We don't have the controls associated with the Help file, and we don't have context information for the Help file, yet. 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.

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 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

Start by clicking the "Select control" button, which is the first button to the left of the authoring panel toolbar, and then selecting 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, which is the next button over, and this will 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. Now each node will have a Help topic linked to it, so the topic map should be saved.

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.

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.

ComponentOne DynamicHelp bridges the gap between developers and Help authors by simplifying the process of creating the topic/control mapping in an application. Rather that passing the topic/control map back and fourth 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.

Free Download

MESCIUS inc.

comments powered by Disqus