wxWidgets中帮助文档的使用

在Windows平台下，一般使用的是CHM格式的帮助文档，在wxWidgets中可以通过wxCHMHelpController类才操作MS HTML Help文档也就是CHM文件了；但是在Linux平台下，我们不能使用CHM格式的文件作为帮助文档，我们使用的是wxHTML格式的帮助文档可以通过wxHtmlHelpController类来操作wxHTML Help文档。其实在wxWidgets的头文件wx/help.h中有如下的系列定义：

// Name:        help.h
// Purpose:     wxHelpController base header
// Author:      wxWidgets Team
// Modified by:
// Created:
// Copyright:   (c) Julian Smart
// RCS-ID:      $Id: help.h 33948 2005-05-04 18:57:50Z JS $
// Licence:     wxWindows licence
/

#ifndef _WX_HELP_H_BASE_
#define _WX_HELP_H_BASE_

#include "wx/defs.h"

#if wxUSE_HELP

#include "wx/helpbase.h"

#ifdef __WXWINCE__
    #include "wx/msw/wince/helpwce.h"

    #define wxHelpController wxWinceHelpController
#elif defined(__WXPALMOS__)
    #include "wx/palmos/help.h"

    #define wxHelpController wxPalmHelpController
#elif defined(__WXMSW__)
    #include "wx/msw/helpchm.h"

    #define wxHelpController wxCHMHelpController
#else // !MSW

#if wxUSE_WXHTML_HELP
    #include "wx/html/helpctrl.h"
    #define wxHelpController wxHtmlHelpController
#else
    #include "wx/generic/helpext.h"
    #define wxHelpController wxExtHelpController
#endif

#endif // MSW/!MSW

#endif // wxUSE_HELP

#endif
    // _WX_HELP_H_BASE_

从头文件的定义中很明显的可以得到以下信息。如果在Windows平台，那么实际包含的是wx/msw/helpchm.h头文件，而且定义的wxHelpController实际上就是wxCHMHelpController类；如果在Linux平台，那么实际包含的是wx/html/helpctrl.h头文件，而且定义的wxHelpController实际上就是wxHtmlHelpController类。所以在实际的编程使用过程中，我们要只需要包含<wx/help.h>头文件，那么就可以根据我们当前的平台配置来自动选择适当的wxHelpController类了。

wxHTML格式的帮助文档，根据wxwidgets的帮助文档的描述，其实是使用微软的HTML Help Workshop project files (.hhp, .hhk, .hhc)文件来作为它的原生格式。一般使用的时候，都是将hhp、hhk、hhc、htm和相关的图片文件打包在一起形成一个ZIP格式的压缩包文件。下面对这几种格式的文件做一个说明：

hhp文件：帮助文档的头文件，包含一些很重要的信息。比如下面类似的格式：

[OPTIONS]
Compatibility=1.1 or later
Compiled file=doc.chm
contents file=doc.hhc	//指定帮助文档的主题文件
index file=doc.hhk		//指定帮助文档的索引文件
Binary Index=Yes
Enhanced decompilation=Yes
Full-text search=Yes
title=help-中文			//指定帮助文档的标题
Default Window=main	//指定帮助文档显示时的窗口
default topic=doc.htm	//指定帮助文档显示时的默认页面也就是内容页面，这里我的帮助文档只有一个htm页面文件
charset=gb2312		//指定contents file和index file使用的字符集，如果要显示中文的话这个地方一定要正确配置，否则会乱码

[WINDOWS]
main="doc","doc.hhc","doc.hhk","","",,,,,0x061420,300,0x3032,[0,0,800,600],,,,0,0,0,0

[FILES]			//指定当前帮助文档中包含的htm文件，这里只有一个htm文件，注意这里只需要列出htm文件就可以了
doc.htm				

hhk文件：帮助文档的主题文件，主题指的是在帮助文档窗口左侧的contents标签页中显示的内容，是一个XML格式的文件

hhc文件：帮助文档的索引文件，索引指的是在帮助文档窗口左侧的index标签页中显示的内容，是一个XML格式的文件

htm文件：帮助文档的页面文件，主要是html格式的网页文件，是HTML格式的网页文件

手动写这些文件的话，还是很麻烦的。而且在我们这个项目中已经有了一个用在Windows平台下的CHM格式的帮助文档文件，我们可以使用一个CHM to HTML Converter的工具来将CHM格式的文件转换成HTML格式的帮助文档，在转换的过程中会自动的生成hhp、hhk、hhc和htm文件的，转换之后的文件如果有不合适的地方可以直接使用文本编辑器打开相应的文档进行编辑的。比如我转换出来的hhp文件中就有一个地方有问题首先是charset字符集没有正确的配置导致显示帮助文档的时候主题和索引内容因为是中文而显示乱码；所以在使用工具转换完成之后请记得用记事本打开hhp文件来检查一个格式是否正确。随后我们可以将这些所有的hhp、hhk、hhc、htm以及包含的图片文件打包压缩成一个ZIP文件，这个ZIP文件就可以作为Linux下的帮助文档了。下面是在代码中使用的步骤：

头文件testhelp.h中包含以下内容：

#include <wx/cshelp.h>		//帮助文档驱动器
#include <wx/help.h>		//具体的帮助文档控制器声明
#include <wx/filesys.h>		//文件系统声明
#include <wx/fs_zip.h>		//压缩解压文件操作声明

class TestHelp:public wxDialog
{
	//......其他代码省略
private:
        wxHelpController m_wxHtmlHelper;		//帮助文档控制器
        wxHelpControllerHelpProvider m_HelperProvider;	
}

实现文件testhelp.cpp中的使用：

#include "testhelp.h"

bool TestHelp::OnInit(//......参数省略)
{
	wxHelpProvider::Set(&m_HelperProvider);		//设置帮助文档驱动器

	m_HelperProvider.SetHelpController(&m_wxHtmlHelper);		//设置帮助文档控制器

	wxFileSystem::AddHandler(new wxZipFSHandler);		//将ZIP压缩解压文件处理句柄添加到文件系统中，用于后续从ZIP帮助文档中解压文件

	//.......其他代码省略
}

void TestHelp::OnHelpBtnClick(wxCommandEvent &event)<span style="white-space:pre">	</span>//帮助按钮的单击事件，点击帮助按钮打开帮助文档
{
        wxUnusedVar(event);
        char    szProgramPath[512] = {0};
        getProgramPath(szProgramPath);
        wxString        strProgramPath(szProgramPath, *wxConvCurrent);
#ifdef WIN32		//如果是Windows平台我们使用CHM格式的帮助文档就可以了
	strProgramPath += _T("help.chm") ;
        ShellExecute( NULL, _T("open"), strProgramPath.c_str(), NULL, NULL, SW_SHOWMAXIMIZED ) ;
#else				//如果是Linux平台我们就使用wxHTML格式的帮助文档
	strProgramPath += _T("help.zip") ;
        if(!m_wxHtmlHelper.Initialize(strProgramPath))			//控制器初始化help.zip帮助文档，这一步初始化就包含了解析和加载帮助文档
        {
                wxMessageBox(wxT("init the wxHTML Helper failed!"), wxT("Tip"));
                return;
        }
        m_wxHtmlHelper.DisplayContents();				//将帮助文档显示出来，将焦点Focus至于帮助文档的contents部分
#endif
}

具体的使用就是这样了，这里我们的帮助文档显示的时候使用的是在hhp文件中指定的一个默认窗口，在这里我没有使用到wxHtmlHelpWindow类，这个类是可以定制帮助文档显示窗口的。在OnInit方法中可以加入如下的代码：

        //wxHtmlHelpWindow *m_helpwindow = new wxHtmlHelpWindow;
        
        //m_helpwindow->Create(this,wxID_ANY, wxDefaultPosition, wxSize(400,300), wxTAB_TRAVERSAL|wxNO_BORDER, wxHF_DEFAULT_STYLE);
                
        //m_wxHtmlHelper.SetHelpWindow(m_helpwindow);

不过很可惜，我在代码中加入了这段代码后帮助文档一直显示不出来，反而使用hhp文件里面指定的默认的窗口就显示出来了。我一直没有查找到是什么原因，如果有哪个看官知道怎么解决这个问题，请方便在下面留言回复一下，本人不胜感激！