Pelnor Help Add-in.

Transcription

1 Pelnor Help Add-in

2 Pelnor Software Index HelpAddIn 1 Pelnor Help Add-in UserControl... 1 Node Editor...7 URL Link Dialog...10 Inner Document Link Selection Dialog Help Document Options Documentation Options Form...16 Save Dialog Application Configuration...20 PelnorHelpProvider 22 Pelnor Help Provider Pelnor Help Provider Properties Control Specific Help Properties...26 Custom Tab Control Configuration File PelnorWPFHelpProvider 28 Pelnor WPF Help Provider Pelnor WPF Help Provider Properties Pelnor WPF Help Provider Dependency Properties...31 Custom Tab Control Configuration File... 32

3 HelpAddIn Pelnor Help Add-in UserControl Click on a control for more information. Pelnor Help Add-in UserControl This control provides the description editing and document output options for the Pelnor Help Add-in. As controls are selected in the Forms designer their corresponding descriptions will be loaded and displayed. Undo Button This button undoes the most recent edit in the selected description. Search Button Page 1 of 32

4 This button opens the text search dialog for the selected RTF control description. Redo Button This button redoes the most recent change that was undone with the Undo button. Friendly Name Textbox This textbox displays a user friendly name for the selected control. So instead of "btnsave" the user can be presented with a name like "Save Document Button" The friendly name text will default to the currently selected controls name. Usage The Friendly Name will be displayed as a header for the controls descriptions in the documents output by the Pelnor Help Add-in. s Tab Control This tab control displays the descriptions associated with the currently selected control. Each tab represents a single description. Use The descriptions displayed in the tab control will be used in the documentation output by the Pelnor Help Add-in. Each tab header will be used as a section name for the associated description. Zoom Level Dropdown This dropdown displays the current zoom level for the selected description. Numeric values may be selected from the dropdown or custom values may be typed in. 100 is the default. Save Dropdown Button Save Changes This selection opens the Save Dialog. Create PDF Page 2 of 32

5 This selection opens the PDF version of the Documentation Options Dialog. Create XPS This selection opens the XPS version of the Documentation Options Dialog. Create HTML Help Project This selection opens the HTML Help version of the Help Project Dialog. Create Win Help Project This selection opens the Win Help version of the Help Dialog. New Button This button adds a new description to the descriptions tab control. A prompt for the new tab name will be displayed when the button is selected. Delete Button This button will delete the currently selected description in the descriptions tab control. Rename Button This button opens a dialog to rename the currently selected description in the descriptions tab control. Node Edit Button This button opens the Node Editor dialog. Help Button This button opens the Pelnor Help Add-in help file. Font Dropdown Button Font Dialog Page 3 of 32

6 This selection opens the Font Dialog Box. Bold This selection will set the currently selected text to bold. Italic This selection will set the currently selected text to italic. Underline This selection will set the currently selected text to underline. Regular This selection will set the currently selected text to regular. Numeric Bullets Button This button adds a numeric bulleted list to the selected description. Example: 1. Test 1 2. Test 2 3. Test 3 Bullets Button This button adds a bulleted list to the selected description. Example: Test 1 Test 2 Test 3 Align Left Button This button aligns the currently selected text to the left edge. EXAMPLE Page 4 of 32

7 Align Right Button This button aligns the currently selected text to the right edge. EXAMPLE Align Middle Button This button aligns the currently selected text the middle of the page. EXAMPLE Indent Right Button This button indents the current line in the description text to the right. Indent Left Button This button indents the current line in the description text to the left. Image Button This button opens a dialog to insert an image into the current description. The image will be added at the location of the cursor. Table Dropdown Create Table This selection adds a new table to the current description at the cursors location. A dialog will prompt for the number of rows and columns for the new table. Insert Row This selection inserts a new row in the currently selected table. Insert Column Page 5 of 32

8 This selection adds a new column to the selected table. Delete Cells This selection opens a dialog with options to delete the currently selected cell, row, or column. Cell Border Width This selection opens a dialog that allows the selection of cell border widths. Cell Border Color This selection opens a dialog that allows the selection of cell border colors. Cell Color This selection opens a dialog that allows the selection of the current cells background color. Link Button Dropdown Inner Document This selection allows hyperlinks to be created that point to other descriptions within the current Pelnor Help Add-in documentation. The Inner Document Link Dialog will prompt for the link text and target description. URL This selection allows hyperlinks to be created targeting URL locations. The URL Link Dialog will prompt for the hyperlink text and URL target. Example: Google Page 6 of 32

9 Node Editor Click on a control for more information. Node Editor The Node Editor lets you view, add, and delete nodes. You can also re-arrange the order in which the nodes will appear in the output documentation. View s Button This button will display the s associated with the selected node in the Node Treeview. Node Treeview Page 7 of 32

10 The Node Treeview allows you to navigate all of the description nodes for the current Solution. There are five types of nodes and each is associated with a specific icon. This the Solution node icon. The Solution node has no descriptions itself but does have a title page. This is the root node of the entire hierarchy. This node can contain both Project and General Information nodes as its children. This is the Project node icon. The Project node has no descriptions itself but does have a title page. There may be multiple projects in each solution. This node can contain both Form and General Information nodes as children. This is the General Information node icon. The General Information node has descriptions only and is not associated with a screenshot. This is the Form node. The Form node has s, can contain General and Control nodes. The Form node is associated with a screenshot. This is the Control node. The Control node has s of the control and is associated with the screenshot of its parent form. View Title Page Button This button will display the title page associated with the selected node. Only Solution and Project nodes have title pages. Move Node Up Button The Move Node Up button moves the selected node up within the branch it is displayed in. Move Node Down Button The Move Node Down button moves the selected node down within the branch it is displayed in. Page 8 of 32

11 Add General Node Button The Add General Node Button creates a new description only node in the currently selected nodes children. General nodes contain a list of descriptions but are not associated with program screenshots. Delete Node Button This button deletes the currently selected node. Page 9 of 32

12 URL Link Dialog Click on a control for more information. URL Link Dialog This dialog lets you choose the text description and URL destination for hyperlinks included in the output documentation. URL Textbox This textbox will contain the URL target for the hyperlink. This will typically be a web address. Cancel Button This button cancels the hyperlink insertion and closes the dialog. OK Button This button accepts the information entered for and URL and creates the hyperlink. Textbox This textbox will contain the displayed text of the hyperlink. Page 10 of 32

13 Inner Document Link Selection Dialog Click on a control for more information. Inner Document Link Selection Dialog This dialog lets you create hyperlinks to other descriptions contained within the solutions created documentation. Treeview This treeview will let you navigate the solution documentation to select a target for your hyperlink. Only descriptions may be linked to. The icon denotes a description that is a valid link target. Page 11 of 32

14 Link Textbox This textbox will contain the visible text for the hyperlink. OK Button This button accepts the link text label and target location. The new link will be inserted at the point of the mouse cursor in current description text. Cancel Button This button cancels the link insertion and closes the dialog. Page 12 of 32

15 Help Document Options Click on a control for more information. Help Document Options This form is used to select the Help Project creation options and save directory. Depending on the menu option used to open the form it will create either HTML Help projects or Win Help projects. Include Document Index Checkbox This checkbox indicates that the output documents will include an Index. Once checked an index title Page 13 of 32

16 can be entered in the Index Title textbox. Index Title Textbox The text placed here will be used as a Title for the Index page. This textbox only becomes enabled once the Include Document Index has been checked. Form Page Links Checkbox During the Help project creation each control will also have a separate page built for its descriptions. Control descriptions are also listed after those of the form on the forms page. Checking this box indicates that Control links on the form screenshot will point to the control description on the form page. Uncheck this box and the Control links on the form screenshot will point to the control description only page. Compile Help Project Checkbox Checking this box indicates that the help project will be compiled after it is created to produce the.chm file. Open Help Checkbox Checking this box will open the help project if it has been built by checking the Compile Help Project checkbox. This box will not be enabled unless the Compile Help Project checkbox is checked. Header Image Textbox To include an image in the header of the Help project document pages enter the image path here. You can also browse to the Image using the Browse button. Header Image Button Clicking this button opens a dialog that will allow you to browse to an image to use in the header. Once selected the image path will be displayed in the Header Image Path textbox. Page 14 of 32

17 Cancel Button This button cancels the Help document creation and closes the form. Create Help Button This button opens the folder selection dialog. The Help Project creation will create many files and several directories. This dialog will let you select or create the directory these files will go into. Project Selection Treeview The project selection treeview allows displays the projects available for inclusion in the Help Project. By default all projects are checked. Uncheck them to exclude them from the documentation. Page 15 of 32

18 Documentation Options Form Click on a control for more information. Documentation Options Form This form is used to select documentation creation options and file location. Depending on the menu option used to open the form it will create either PDF or XPS documentation. Page 16 of 32

19 Project Selection Treeview The project selection treeview allows displays the projects available for inclusion in the documentation. By default all projects are checked. Uncheck them to exclude them from the documentation. Include Document Index Checkbox This checkbox indicates that the output documents will include an Index. Once checked an index title can be entered in the Index Title textbox. Index Title Textbox The text placed here will be used as a Title for the Index page. This textbox only becomes enabled once the Include Document Index has been checked. Include Control ID Numbers Checkbox This option will add numbers to the controls on the form screenshot and to their corresponding description. This helps identify control descriptions on printed documentation. Footer Image Textbox To include an image in the footer of the documentation pages enter the image path here. You can also browse to the Image using the Browse button. Footer Image Button Clicking this button opens a dialog that will allow you to browse to an image to use in the document footer. Once selected the image path will be displayed in the Footer Image Path textbox. Open Documentation File Page 17 of 32

20 Checking this box will open the documentation file after it has been built using the Create PDF or XPS button. Cancel Button This button cancels the document creation and closes the form. Create Document Button This button opens a dialog that lets you choose the location to save the new documentation file to. Page 18 of 32

21 Save Dialog Click on a control for more information. Save Dialog This dialog lets you choose which projects to save changes for. By default all projects will be checked. Yes Button Saves the checked projects in the checklist. Save Check List The available projects to be saved will be listed here. Projects with a check will be saved. All projects will be checked by default. No Button This button will discard all changes and close the dialog. Page 19 of 32

22 Application Configuration App Config The Pelnor Help Add-in has a configuration file located in its install directory. This file is named HelpAddIn.exe.config. This file has settings you can change to alter the behavior of the Add-in. AutomaticalyAddPelnorHelpProviderToWinForms This setting determines if the Pelnor Help Add-in will automatically add the control PelnorHelpProvider to the active form. This action occurs when a form element is selected and no PelnorHelpProvider control exists on the form. Acceptable values for this property are "true" and "false". AutomaticallyAddPelnorHelpProviderReference This setting determines if the Pelnor Help Add-in will automatically add a reference to the PelnorHelpProvider control to the active project. This action occurs when a form element is selected and the AutomaticallyAddPelnorHelpProviderToWinForms option is set to "true". Acceptable values for this property are "true" and "false". HTMLHelpExecutablePath This setting points to the path of the Microsoft HTML Help Workshop executable. This file should be named hhc.exe. The default install path for this program is: "C:\Program Files\HTML Help Workshop\hhc.exe". With this path specified the Pelnor Help Add-in will be able to run this executable to automatically compile the help project after it is built. The option to automatically compile is found on the Help Project Configuration screens Compile Checkbox. HTMLHelpStyleSheet This setting points to the Cascading Style Sheet file that will be used by the output HTML Help projects. The default setting for this value points to the file "HTMLHelpStyle.css" found in the Pelnor Help Add-in install folder. Valid values for this setting are system paths to.css files. WinHelpExecutablePath This setting points to the path of the Microsoft HTML Help Workshop executable. This file should be named hcw.exe. The default install path for this program is: "C:\Program Files\Help Workshop\hcw.exe". Page 20 of 32

23 With this path specified the Pelnor Help Add-in will be able to run this executable to automatically compile the help project after it is built. The option to automatically compile is found on the Help Project Configuration screens Compile Checkbox Page 21 of 32

24 PelnorHelpProvider Pelnor Help Provider The Pelnor Help Provider serves two main purposes. First, it captures screenshots and control location data of your running application. Second, it can be used as a standard Help Provider to open help documentation for your application. When associated with a HTML help file created by the Pelnor Help Add-in, controls are automatically associated with their corresponding section in the help file. The developer is not required to point each control to its specific help topic manually. The Pelnor Help Provider is designed for use on Windows Forms and User Controls. When used with Forms the form KeyPreview Property should be set to True. Manual Component Placement To place the Pelnor Help Provider on a Form or UseControl you fist need a reference to the PelnorHelpProvider.dll. Go to your project, select References, Add-Reference, and navigate to the PelnorHelpProvider.dll. This will make the component available on your Toolbox. From the Toolbox the Pelnor Help Provider may be dragged onto your Form or UserControl. Automatic Component Placement The Pelnor Help Add-in has the ability to both add a reference to the PelnorHelpProvider.dll and place the component on the currently selected form. This action is done when the Add-in is open and a control on a Form or UserControl is selected in the visual designer. The automatic placement behavior is on by default. To alter this behavior refer to the Pelnor HelpAddin.exe.config file and adjust the AutomaticalyAddPelnorHelpProviderToWinForms or AutomaticallyAddPelnorHelpProviderReference settings. Usage Once the Pelnore Help Provider is placed on the form, run your program in debug mode. Open the form and press Alt-F1. This instructs the Help Provider to take a screenshot of the current form and each tab page within that form. Along with the screenshots all control locations on the form are recorded for use in the documentation. If Alt-F1 is in use by your program another key combination can be specified. The command to capture the form's image can also be called programmatically by calling the GenerateDocumentData command and passing it the Form or UserControl to document: this.pelnorhelpprovider1.generatedocumentdata(this); Page 22 of 32

25 Opening Help When your application is running you can open the associated help file by pressing F1. The HTML help file to open needs to be set on the Help Providers HelpNamespace property. Alternately you may also open the help file in code by calling the ShowPelnorHelp method and passing it the control to show help for: this.pelnorhelpprovider1.showpelnorhelp(this); Page 23 of 32

26 Pelnor Help Provider Properties The behavior of the Pelnor Help Provider can be modified at design time by modifying the controls properties. CreateTabImages This is boolean property. When set to true the Help Provider will cycle through the tabs of a tab control collecting a screenshot and control position information for each tab. Setting to false disables this behavior. CustomTabControlConfigFile This is the file path for a custom tab control configuration. By default the Pelnor Help Provider only knows how to work with the standard TabControl that ships with Visual Studio. If you are using a 3rd party tab control you can provide a description of its properties in the config file and the Pelnor Help Provider will use reflection to access it. For information on setting up the config file refer to the section: Custom Tab Control Configuration File. HelpNamespace This is used to specify the path to the HTML help file. HelpProviderParent This is the Form or UserControl that the Help Provider is sitting on. HotKey This is the key that will trigger the help provider to display the help file. When used in combination with the HelpKeyModifier while running in design mode the Pelnor Help Add-in will generate a screenshot and control position data for the form. HotKeyModifier When used in combination with the HelpKey while running in design mode the Pelnor Help Add-in will generate a screenshot and control position data for the form. PelnorAddInFormDirectory This is the path for where the form screenshots and control position data will be stored by the Pelnor Help Provider. This information will be filled in automatically when the control is first placed on a form. PelnorAddInFormName Page 24 of 32

27 This name will be used to associate descriptions form the Pelnor Help Add-in with the screenshots and control locations from the Pelnor Help Provider. This information will be filled in automatically when the control is first placed on a form. Page 25 of 32

28 Control Specific Help Properties When a Help Provider is present on a form, help specific properties are added to each control on that form. The standard descriptions and usages for the properties HelpKeyword, HelpNavigator, HelpSring, and ShowHelp can be found in Microsoft's MSDN documentation here: MSDN HelpProvider. HelpKeyword The Pelnor Help Provider alters the behavior of this property if it is left blank. When left blank the Pelnor Help Provider will automatically point to the corresponding description found in the HTML Help File created by the Pelnor Help Add-in. By default this field is blank so this behavior will be automatic. UseFormPage This boolean property determines what part of the HTML documentation will be opened when Help is launched for this control. When set to True, the help file will open to the controls description on the Forms help page. When set to False, the help file will open to a description that is for only the Control. In either case the same description information for the control is displayed. Page 26 of 32

29 Custom Tab Control Configuration File By default the Pelnor Help Provider will take screenshots and get control position data from each tab in a Windows.Forms.TabControl. To extend this behavior to 3rd party tab controls we must specify them in a config file. The path to this config file will be set in the Help Provider's CustomTabControlConfigFile property. An example config file is presented here: <?xml version="1.0" encoding="utf-8"?> <configuration> <PaginControls> <ControlData ParentControl="System.Windows.Forms.TabControl" Collection="TabPages" SelectionMethod="SelectTab"/> <ControlData ParentControl="ComponentFactory.Krypton.Navigator.KryptonNavigator" Collection="Pages" SelectionProperty="SelectedPage"/> </PaginControls> </configuration> ParentControl This is the full name of the tab control. For the default Visual Studio tab control this value is set to: "System.Windows.Forms.TabControl" Collection This is the name of the collection that the tab control keeps its individual tabs in. For the default tab control this collection is: "TabPages" SelectionMethod If your tab control has a method for setting the current tab specify its name here. For the standard tab control this method is: "SelectTab" SelectionProperty Some tab controls let you set the currently selected tab with a property. One such control is the KryptonNavigator published by ComponentFactory. For this tab control we would set the SelectionProperty to: "SelectedPage" Page 27 of 32

30 PelnorWPFHelpProvider Pelnor WPF Help Provider Pelnor WPF Help Provider The Pelnor WPF Help Provider serves two main purposes. First, it captures screenshots and control location data of your running application. Second, it can be used as a standard Help Provider to open help documentation for your WPF application. When associated with a HTML help file created by the Pelnor Help Add-in, controls are automatically associated with their corresponding section in the help file. The developer is not required to point each control to its specific help topic manually. The Pelnor Help Provider is designed for use with the Windows Presentation Foundation (WPF). Manual Control Placement To place the Pelnor WPF Help Provider on a Window you fist need a reference to the PelnorWPFHelpProvider.dll. Go to your project, select References, Add-Reference, and navigate to the PelnorWPFHelpProvider.dll. This will make the component available for your WPF application. Begin by adding a namespace for the Pelnor WPF Help Provider: xmlns:my="clr-namespace:pelnorwpfhelpprovider;assembly=pelnorwpfhelpprovider " Then add the WPF Help Provider to your window with: <my:helpprovidercontrol> Once the component is added it will default its PelnorAddInFormDirectory property and provide GUID IDs for your controls by setting the ControlID property. Usage Once the Pelnor WPF Help Provider is placed on the window, run your program in debug mode. Open the window and press Alt-F1. This instructs the WPF Help Provider to take a screenshot of the current window and each tab page within that window. Along with the screenshots all control locations on the form are recorded for use in the documentation. If Alt-F1 is in use by your program another key combination can be specified. The command to capture the window's image can also be called programmatically by calling the GenerateDocumentData command and passing it the window to document: this.wpfhelpprovider.generatedocumentdata(this); Opening Help Page 28 of 32

31 When your application is running you can open the associated help file by pressing F1. The HTML help file to open needs to be set on the WPF Help Providers HelpNamespace property. Alternately you may also open the help file in code by calling the ShowPelnorHelp method and passing it the FrameworkElement to show help for: this.wpfhelpprovider.showpelnorhelp(this.button1); Page 29 of 32

32 Pelnor WPF Help Provider Properties The behavior of the Pelnor WPF Help Add Provider can be modified at design time by modifying the controls properties. CreateTabImages This is boolean property. When set to true the WPF Help Provider will cycle through the tabs of a tab control collecting a screenshot and control position information for each tab. Setting to false disables this behavior. CustomTabControlConfigFile This is the file path for a custom tab control configuration. By default the Pelnor WPF Help Provider only knows how to work with the standard WPF TabControl that ships with Visual Studio. If you are using a 3rd party tab control you can provide a description of its properties in the config file and the Pelnor WPF Help Provider will use reflection to access it. For information on setting up the config file refer to the section: Tab Control Configuration File. HelpNamespace This is used to specify the path to the HTML help file. PelnorAddInFormDirectory This is the path for where the form screenshots and control position data will be stored by the Pelnor WPF Help Provider. This information will be filled in automatically when the control is first placed on a window. Page 30 of 32

33 Pelnor WPF Help Provider Dependency Properties When a WPF Help Provider is present on a window, help specific properties can be added to each FrameworkElement on that window. The standard descriptions and usages for the properties HelpKeyword, HelpNavigator, HelpSring, and ShowHelp can be found in Microsoft's MSDN documentation here: MSDN HelpProvider. HelpKeyword The Pelnor WPF Help Provider alters the behavior of this property if it is left blank. When left blank the Pelnor WPF Help Provider will automatically point to the corresponding description found in the HTML Help File created by the Pelnor Help Add-in. By default this field is blank so this behavior will be automatic. UseFormPage This boolean property determines what part of the HTML documentation will be opened when Help is launched for this control. When set to True, the help file will open to the controls description on the Forms help page. When set to False, the help file will open to a description that is for only the Control. In either case the same description information for the control is displayed. UsePelnorAddInHelpFile Boolean value specifies that the FrameworkElement is using a HTML Help file created with the Pelnor Help Add-in. If not specified the value is assumed to be true. Set to false if pointing to a help file not created with the Pelnor Help Add-in. ControlID This property is used by the Pelnor WPF Help Provider to uniquely identify each control in the WPF window. The Pelnor WPF Help Provider will fill this property in automatically once it is added to a window. Any controls placed on the window containing the help provider will also have this property defaulted. Page 31 of 32

34 Custom Tab Control Configuration File By default the Pelnor WPF Help Provider will take screenshots and get control position data from each tab in a Windows.Controls.TabControl. To extend this behavior to 3rd party tab controls we must specify them in a config file. The path to this config file will be set in the WPF Help Provider's CustomTabControlConfigFile property. An example config file is presented here: <?xml version="1.0" encoding="utf-8"?> <configuration> <PaginControls> <ControlData ParentControl="System.Windows.Controls.TabControl" Collection="Items" SelectionProperty="SelectedItem" SelectCurrentlySelectedTabBool="IsSelected"/> </PaginControls> </configuration> ParentControl This is the full name of the tab control. For the default Visual Studio tab control this value is set to: "System.Windows.Controls.TabControl" Collection This is the name of the collection that the tab control keeps its individual tabs in. For the default tab control this collection is: "Items" SelectionMethod If your tab control has a method for setting the current tab specify its name here. For the standard tab control this method is: "SelectedIndex" SelectionProperty Some tab controls let you set the currently selected tab with a property. For the standard tab control this methos is: "SelectedItem" CurrentlySelectedTabBool This property is a boolean value that indicates when a tab is selected. For the standard tab control this property is: "IsSelected" Page 32 of 32