Configure UniHelp
After adding all of the required UniHelp components to your REALbasic project, you now need to configure it to run with your custom settings.
The first thing you need to do is add the following required line of code to your App.Open event, creating a new instance of the UniHelpEngine class by calling the UniHelp global property (located in the UniHelpGlobals module):
You configure your UniHelp settings in the UniHelpEngine.UniHelpEngine Constructor method. If you use HelpLogic to publish your help pages for use with UniHelp, then HelpLogic automatically generates the configuration code needed for this Contructor method. Simply open the "Code_for_UniHelp.txt" file (that was published along with your help pages) and copy and paste your customized configuration code from there into the UniHelpEngine Constructor method.
Purchase a UniHelp Component License to receive FREE access to a special UniHelp Edition of HelpLogic for easily creating your UniHelp compatible help pages and settings! Or purchase a UniHelp Source Code License, which includes a full version of HelpLogic. HelpLogic is the award-winning help authoring solution for Mac OS X and Windows XP/Vista. For complete details, please see the Using FREE HelpLogic page.
Even though HelpLogic will help configure all of these settings for you, here's a brief description of each setting, so that you understand what each property does.
If you are happy with UniHelp's default window settings at a 700 pixel width and a 400 pixel height, placed in the center of the screen, then define AutoSet = TRUE (and any custom settings will be ignored). If you want to customize UniHelp's window size and screen position, then simply define AutoSet = FALSE.
The four properties listed above are global properties located in the UniHelpGlobals module, enabling you to assign, retrieve and save these properties for present and future use by your application. UniHelp records its window width, height, and placement into these properties whenever it is resized, moved, deactivated, or closed, so you can save these values in your application's preferences file if you wish. Then the next time your application is launched, you can simply retrieve the saved values from your preferences file and assign them to these global properties so that UniHelp "remembers" it's window settings the next time it is displayed.
Customize the color of the icons that UniHelp displays in the Table of Contents. The graphic file names are self-explanatory. "bookblue" is the blue book icon, "bookred" is the red book icon, "docgreen" is the green page icon, etc.
The FontName property allows you to choose what default font is used in UniHelp's Table of Contents, Index, and Search list. Always choose a common font that you know both Mac and Windows computers have. We recommend using Arial or Verdana as the main font choice. Just in case a user does not have the main FontName installed, the AltFont property specifies an alternative default font. So again, use a common font for the AltFont. If the user does not have either the main font or alternative font, then UniHelp will use the system font instead.
The FontSize property assigns the default text size of UniHelp UI Elements, such as the TOC, Index, and Search list. You can choose a value within the range of 9-16. We recommend 11, but for larger text that's very easy to read, try 12, 13 or 14. Don't worry too much about picking the right size since this is simply the default setting. The UniHelp Viewer includes buttons (in the bottom status bar) that enable the user to adjust the text size themselves.
You have the option to perform full text searches within UniHelp. In the UniHelpEngine.Constructor, if you set UseFullTextSearch=TRUE, then UniHelp searches will search the TOC and the full text content of your help pages, providing very comprehensive search results. If you set UseFullTextSearch=FALSE, then UniHelp searches will only search the TOC Topic Names, Keywords & Description in the TOC XML, which performs faster and provides you, the developer, with greater control over the search results.
You have the option to show highlighted search matches in the displayed help pages within UniHelp's search engine. In the UniHelpEngine.Constructor, if you set ShowSearchHighlights=TRUE (and UseFullTextSearch=TRUE), then search matches will be highlighted in search-related help pages. If UseFullTextSearch=FALSE, then ShowSearchHighlights is ignored.
The ShowPrintButton boolean property enables the OPTIONAL Print feature. REALbasic's HTMLViewer control does not support native printing, but printing can be achieved by alternative methods on Windows (JavaScript) and Mac OS X (MBS Plugins). In the UniHelpEngine's Constructor, setting ShowPrintButton=TRUE will enable Printing, showing the Print Button in the UniHelp Viewer. Setting ShowPrintButton=FALSE will disable Printing, removing the Print Button from the UniHelp Viewer. If set to TRUE, then clicking the Print Button will fire the UniHelpGlobals.UHPrint method.
If you plan on using UHScript Links in your HTML help pages, then you need to assign an UHScriptObject. For details on what UHScript links are and how to properly configure this UHScriptObject line, see the UHScript Links page (within the "Advanced Topics" chapter). Using UHScript links in your HTML help pages is completely OPTIONAL.
If you've published your help files in a Virtual Volume, then set UseVirtualVolume = True, and then configure the VVInitialize method call (see next couple lines) to point to the location of your Virtual Volume file. UniHelp 3 and higher no longer uses the obsolete PrepareVV method from UniHelp 2. All basic configuration is now done soley within the UniHelpEngine constructor.
For additional information and troubleshooting help with Virtual Volumes, please see the Using Virtual Volumes page.
If you're using a standard help folder and set UseVirtualVolume = False, then you'll need to assign the HelpFolder property with the FolderItem of your help folder, so that UniHelp can find it.
The HomePage property is the help file that you want users to see if they click on the Home button in the UniHelp navigation toolbar. This is usually the introduction page of your help system. The only requirement is that this HomePage string needs to be the filename of a file that's located in your help folder's root directory. The HelpTitle property is the name of your help system that you want to appear in the UniHelp window's title bar.