This help controller provides an easy way of displaying HTML help in your application. It provides a sophisticated system for showing help that includes a hierarchical contents listing, index, keyword search and bookmarking.
It is similar to the Microsoft Windows HTML Help Viewer, but unlike that viewer it is available and uses the same help file format on all platforms. The native Windows help viewer is available in WxRuby by using the Wx::HelpController class, which will create an OS-native viewer on Windows and an HtmlHelpController on Linux/GTk and OS X. However, unless you have a strong preference for using the native control on Windows, you are recommended to use this class, as it means you can provide your help file(s) in a single format only.
The help system is based on books (see). A book is a logical section of documentation (for example “User’s Guide” or “Programmer’s Guide” or “Ruby Reference” or “Class Reference”). The help controller can handle as many books as you want.
Wx::HtmlHelpController library uses a reduced version of Microsoft’s
HTML Workshop format. This consists of standard HTML 4.0 files, plus a
set of three files (.hhp, .hhc, .hhk) that are a project header file, a
help contents file and a help index file, respectively. These are all
simple text files that are easily authored or generated using any of a
wide variety of tools.
A HtmlHelpController can use an .hhp header file directly as an argument to add_book to open documentation.
You can make a regular zip archive of these files, plus the HTML and any image files, for wxHTML (or helpview) to read; and the .zip file can optionally be renamed to .htb.
Header file must contain these lines (and may contain additional lines which are ignored) :
Contents file=[filename.hhc] Index file=[filename.hhk] Title=[title of your book] Default topic=[default page to be displayed.htm]
All filenames (including the Default topic) are relative to the location of .hhp file.
Localization note In addition, .hhp file may contain the line
which specifies what charset (e.g. “iso8859_1”) was used in contents and index files. Please note that this line is incompatible with MS HTML Help Workshop and it would either silently remove it or complain with some error.
The contents file lists the hierarchical structure of the help
documentation. The contents file has HTML syntax and it can be parsed by
regular HTML parser. It contains exactly one list
(<ul>....</ul> statement), with <li> elements
containing an <object> of type
text/sitemap for each node of the
<ul> <li> <object type="text/sitemap"> <param name="Name" value="@topic name@"> <param name="ID" value=@numeric_id@> <param name="Local" value="@filename.htm@"> </object> <li> <object type="text/sitemap"> <param name="Name" value="@topic name@"> <param name="ID" value=@numeric_id@> <param name="Local" value="@filename.htm@"> </object> ... </ul>
You can modify the value attributes of param tags.
topic name is name
of chapter/topic as is displayed in the contents listing,
is the HTML page name (relative to .hhp file) and
optional – it is used only when you use the HtmlHelpController#display()
method to show a specific part of the help documentation.
Items in the list may be nested to produce a hierarchical tree-like organisation of content topics. To do this, one <li> statement may contain one or more <ul> sub-statements in the .hhc file:
<ul> <li> <object type="text/sitemap"> <param name="Name" value="Top node"> <param name="Local" value="top.htm"> </object> <ul> <li> <object type="text/sitemap"> <param name="Name" value="subnode in topnode"> <param name="Local" value="subnode1.htm"> </object> ... </ul> <li> <object type="text/sitemap"> <param name="Name" value="Another Top"> <param name="Local" value="top2.htm"> </object> ... </ul>
The index file is a listing of keywords, associated with locations that describe those keywords. Index files have same format as contents file except that ID params are ignored and sublists are not allowed.
HtmlHelpController uses HtmlWindow to display the HTML content pages of the help documentation. Therefore, it understand the large subset of HTML 4.0 that is understood by that widget.
One “feature” to note is that it does not support anchors specified
using the modern
id attribute used on any HTML element. Only
old-fashioned named anchors (using the
name attribute on an
Distributing help using the file format described above means distributing a reasonably number of files (at least the header file, contents page and the actual documentation), and maintaining the directory organisation. It can be more convenient to bundle all the content and index files together into a single file.
A help file bundle can be created by zipping up the .hhp, .hhc, .hhk plus the HTML content files and any images into a single standard .zip archive. WxRuby can then load help from this single archive file instead of from an .hhp file. If you prefer, the .zip file can be renamed .htb (‘HTml help Book’) to indicate that it contains help documentation.
The .chm (Compiled Help) format that is generated by Microsoft’s Help Workshop is a similar concept. However, this file format is not compatible with WxRuby’s Wx::HtmlHelpController. These .chm files can be read by the native Microsoft Help Viewer, which is accessible in WxRuby by using the HelpController class, on Windows only.
There are several tools that can be used to automate the creation of .hhp, .hhc, .hhk and .html files for use with the help viewer.
You can use Tex2RTF, a utility included with the wxWidgets distribution to produce these files when generating HTML from Latex. To do so, set htmlWorkshopFiles to true in your tex2rtf.ini file.
The files can also be generated from Docbook XML documentation, by using the htmlhelp.xsl stylesheet.
If you prefer to use a GUI, Microsoft offers a free HTML Help Workshop for authoring Help documentation.
Although we do not know of any tool to automatically create the contents and index files from Ruby’s RDoc system, it should be relatively straightforward to adapt RDoc’s output for use with HtmlHelpController.
The WxWidgets documentation recommends the use of preprocessed .hhp.cached version of projects. These can be either created on-the-fly (see set_temp_dir) or you can use hhp2cached utility from utils/hhp2cached directory in the WxWidgets distribution to create it and distribute the cached version together with helpfiles.
HtmlHelpController.instance(Integer style = HF_DEFAULT_STYLE)
Returns a new HtmlHelpController if one hasn’t already been created, or returns the previously created one if there is such.
Users typically expect only a single help window to be running for any particular application, with the help shown and hidden as required. To avoid showing multiple help windows within a single application, use this method in preference to new .
style defines optional styles for the help window; the options are described below in the new method. Note that the style argument will only be processed in the first call to this method – subsequent calls will return a controller with the original style.
HtmlHelpController.new(Integer style = HF_DEFAULT_STYLE)
Constructor. To avoid a proliferation of help frames, you may prefer to use the instance class method instead to display help.
style is combination of these flags:
||Help frame has toolbar.|
||Help frame has toolbar with flat buttons (aka coolbar).|
||Help frame has contents panel.|
||Help frame has index panel.|
||Help frame has search panel.|
||Help frame has bookmarks controls.|
||Allow user to open arbitrary HTML document.|
||Toolbar contains “print” button.|
||Contents pane does not showbook nodes. All books are merged together and appear as single book to theuser.|
||All nodes in contents panehave a book icon. This is how Microsoft’s HTML help viewer behaves.|
||Book nodes in contents pane havea book icon, book’s sections have a folder icon. This is the default.|
||Both book nodes andnodes of top-level sections of a book (i.e. chapters) have a book icon,all other sections (sections, subsections, ...) have a folder icon.|
Boolean add_book(String book_file, Boolean show_wait_msg)
Adds book into the list of loaded books. This must be called at least once before displaying any help.
book_file may be either .hhp file or ZIP archive that contains arbitrary number of .hhp files in top-level directory. This ZIP archive must have the .zip or .htb extension (the latter stands for “HTML book”). See above for more information about the format of the help files.
File.expand_pathmay be useful here.
HtmlHelpFrame create_help_frame(HtmlHelpData data)
This protected virtual method may be overridden so that the controller uses slightly different frame. See samples/html/helpview sample for an example.
Displays page x. This is THE important function – it is used to display the help in application.
You can specify the page in many ways:
Looking for the page runs in these steps:
This alternative form is used to search help contents by numeric IDs.
Displays help window and focuses contents panel.
Displays help window and focuses index panel.
Boolean keyword_search(String keyword, HelpSearchMode mode = HELP_SEARCH_ALL)
Displays help window, focuses search panel and starts searching. Returns true if the keyword was found. Optionally it searches through the index (mode = HELP_SEARCH_INDEX), default the content (mode = HELP_SEARCH_ALL).
Important: KeywordSearch searches only pages listed in .hhc file(s). You should list all pages in the contents file.
read_customization(ConfigBase cfg, String path = '')
Reads the controller’s setting (position of window, etc.)
Sets the path for storing temporary files – cached binary versions of index and contents files. These binary forms are much faster to read. Default value is empty string (empty string means that no cached data are stored). Note that these files are not deleted when program exits.
Once created these cached files will be used in all subsequent executions of your application. If cached files become older than corresponding .hhp file (e.g. if you regenerate documentation) it will be refreshed.
Sets format of title of the frame. Must contain exactly one ”\%s” (for title of displayed HTML page).
use_config(ConfigBase config, String rootpath = '')
Associates config object with the controller.
If there is associated config object, HtmlHelpController automatically reads and writes settings (including HtmlWindow’s settings) when needed.
The only thing you must do is create Config object and call UseConfig.
If you do not use UseConfig, HtmlHelpController will use default Config object if available (for details see ConfigBase#get and ConfigBase#set).
write_customization(ConfigBase cfg, String path = '')
Stores controllers setting (position of window etc.)
[This page automatically generated from the Textile source at Wed Sep 09 02:21:12 +0100 2009]