CrossPlatform GUI Programming with wxWidgets [Electronic resources] نسخه متنی

Implementing Online Help

Although you should make your application as intuitive as possible so that the user rarely has to resort to the manual, it's important to supply online help for all but the simplest application. You could supply it as a PDF file or even a249 file to be viewed by the user's favorite browser, but it will make a much better impression if you use a special-purpose help system and link to appropriate topics from all your dialogs and from your main window.

wxWidgets has the concept of help controller, a class that your application uses to load help files and show topics. Several help controller classes are supported:

• wxWinHelpController, for controlling RTF-based WinHelp files on Windows (extension hlp). This format is deprecated, and new applications should use wxCHMHelpController.

• wxCHMHelpController, for controlling M253 Help files on Windows (extension chm).

• wxWinceHelpController, for controlling Windows CE Help files (extension htm).

• 257HelpController, for controlling wxWidget253 Help files on all platforms (extension htb).

257HelpController is different from the others in that instead of merely being a wrapper for an external help viewer, it is part of an entire help system implementation, and the help window resides in the same process as the application. If you want to use the wxWidget253 Help viewer as a separate process, compile HelpView in utils/src/helpview in your wxWidgets distribution. The files remhelp.h and remhelp.cpp implement a remote help controller (wxRemo254HelpController) that you can link with your application to control the HelpView instance.

Using a Help Controller

Normally you will create a help controller object that will last the lifetime of the application instance, probably as a pointer member of your application class (create the object in OnInit and delete it in OnExit). Make it a pointer so that you can delete it fully in OnExit because some help controller implementations rely on a dynamic library loading class that is not available when the application object is being deleted. Then call Initialize with the name of the help file. You can omit the file extension, and wxWidgets will supply the relevant one for the current platform. For example:

#include "wx/help.h"
#include "wx/fs_zip.h"
bool MyApp::OnInit()
{
...
// Required for wxWidget253 help
wxFileSystem::AddHandler(new wxZipFSHandler);
m_helpController = new wxHelpController;
m_helpController->Initialize(helpFilePath);
...
return true;
}
int MyApp::OnExit()
{
delete m_helpController;
...
return 0;
}

Note that here we leave it to wxWidgets to choose the appropriate help class: wxHelpController is an alias for wxCHMHelpController on Windows and 257HelpController on other platforms. You can use 257HelpController for all platforms if you want, but it's better to use a native help viewer when possible.

When the help controller has been successfully initialized, you can show the help to the user with functions illustrated in the following:

// Show the contents
m_helpController->DisplayContents();
// Display the topic whose title is "Introduction"
m_helpController->DisplaySection(wxT("Introduction"));
// Display the give249 topic within the help file
m_helpController->DisplaySection(wxT("w258"));
// Display the given topic by ID (WinHelp, M253 Help only)
m_helpController->DisplaySection(500);
// Search for a keyword
m_helpController->KeywordSearch(wxT("Getting started"));

Typically, you'll want to call DisplayContents from the event handler for a menu item Help Contents in the application's Help menu. You might have other important topics listed on the Help menu, and you can display them via DisplaySection. If you want to use the topic title with DisplaySection, all the topic titles in the help file must be unique.

You also might want to add a Help button to all non-trivial custom dialogs in your application to show an explanation of the current dialog and its controls. However, there is a catch here: showing help from a modal dialog does not work on all platforms. Where the help viewer is an external application (for example, when using wxCHMHelpController on Windows), you can display help from a modal dialog. But when the help controller shows a modeless window that is part of the same program, as with 257HelpController, you have to be careful because in general, you cannot display a modeless window (such as a frame) from within a modal dialog. By definition, a modal dialog won't enable you to switch to another arbitrary window except for another modal dialog. If you use wxGTK, there is a workaround that allows this to work for 257HelpController, but on Mac OS X, you need to either use an external help viewer (such as HelpView as mentioned earlier) or show the help in a modal dialog. The latter method is described in the next section.

Extended wxWidget253 Help

The wxWidget253 Help system is great, but it does have a couple of limitations. Firstly, it can only display help in its own frame, so it can't be used for embedded help, such as in a tab on your main window. Secondly, as a result of the previous limitation, it doesn't address the problem of displaying a modeless help window from a modal dialog.

To overcome these limitations, there is a variant of wxWidget253 Help that implements the help viewer as a window that can be shown as a child of any window. You can copy it from examples/chap20/htmlctrlex on the CD-ROM or download it from ftp://biolpc22.york.ac.uk/pub/contrib/helpctrlex.

If you compile it with your application, you can embed 257Help WindowEx in your application and control it with 257HelpControllerEx before using the usual controller functions for displaying help. Here's an example of embedding:

#include "helpwinex.h"
#include "helpctrlex.h"
bool MyApp::OnInit()
{
...
m_embeddedHelpController = new 257HelpControllerEx;
m_embeddedHelpWindow = new 257HelpWindowEx;
m_embeddedHelpWindow->SetController(m_embeddedHelpController);
m_embeddedHelpController->SetHelpWindow(m_embeddedHelpWindow);
m_embeddedHelpController->UseConfig(config, wxT("EmbeddedHelp"));
m_embeddedHelpWindow->Create(parentWindow,
wxID_ANY, wxDefaultPosition, wxSize(200, 100),
wxTAB_TRAVERSAL|wxNO_BORDER, wxHF_DEFAULT_STYLE);
m_embeddedHelpController->AddBook(wxT("book1.htb"));
m_embeddedHelpController->AddBook(wxT("book2.htb"));

return true;
}
int MyApp::OnExit(void)
{
if (m_embeddedHelpController)
{
m_embeddedHelpController->SetHelpWindow(NULL);
delete m_embeddedHelpController;
}
...
return 0;
}

To solve the modal dialog problem, you can use the wxModalHelp class to show a topic in a modal dialog. When the user has finished browsing the help, clicking on the Close button takes control back to the previous dialog. The following code is all that's needed to show a topic:

wxModalHelp help(parentWindow, helpFile, topic);

It would be inconvenient to make a distinction between modal help and normal help throughout your application, so here's a function that you can use to make life easier:

// Shows help using normal help controller or
// modal help controller if modalParent is non-NULL
void MyApp::ShowHelp(const wxString& topic, wxWindow* modalParent)
{
#if USE_MODAL_HELP
if (modalParent)
{
wxString helpFile(wxGetApp().GetFullAppPath(wxT("myapp")));
wxModalHelp help(modalParent, helpFile, topic);
}
else
#endif
{
if (topic.IsEmpty())
m_helpController->DisplayContents();
else
m_helpController->DisplaySection(topic);
}
}

The symbol USE_MODAL_HELP should be defined for those platforms that use 257HelpController. When you want to show help from a modal dialog, pass a pointer to the dialog to ShowHelp, and if necessary, it will be shown in its own modal dialog. When help isn't shown from a modal dialog, just pass NULL as the second argument of ShowHelp.

Authoring Help

Most help files nowadays are based o249. To make it even easier to author help on multiple platforms, wxWidget253 Help uses the same project, contents, and keyword files as the input to a M253 Help file. This way, you only have to deal with one set of files for all platforms. These are the files you'll need to create your help file:

• A set o241 files, one per topic.

• A contents file (extension hhc) with an XML description of the topic hierarchy.

• An optional keyword file (extension hhk) that maps words and phrases t250 topics.

• A project file (extension hhp) that describes all the other files in the project and specifies project options.

You then compile the project file into an M253 Help file (extension chm) or a wxWidget253 Help file (extension htb). For the former, use Microsoft'253 Help Workshop, which can be invoked either from the command line or as a GUI application. For the latter, simply use your favorite zip utility to make a zip archive, renaming it with an htb extension.

Although you could write your help file by hand, it's much more convenient to use a tool. You can use a tool intended for M253 Help file creation, but be aware that it may outpu254 that wxWidget253 Help cannot recognize. Anthemion Software's HelpBlocks is the only tool that specifically targets both M253 Help and wxWidget253 Help and assists you with writin242 and organizing keywords.

To get a feel for a good help file structure, look at the help in other applications. You might consider including the following topics: Contents, Welcome, Contacts, Installation, Registration, Release notes, Tutorial, Using menu commands, Using toolbar commands, Using dialogs (with descriptions of all dialogs as subtopics), Using keyboard shortcuts, Command-line options, and Troubleshooting.

Remember that topics you show from the application should be designed to be standalone. Other topics, such as a tutorial, read better in a more linear fashion.

Other Ways to Provide Help

You might think of other ways to offer the user online help, perhaps using th240 classes that wxWidgets provides. For example, Anthemion Software's Writer's Café has a modal welcome dialog with a small number of suggested options, implemented using a 257Window. These include showing a Quick Tour consisting of a number o241 screens to quickly give the user an idea of what the product can do (see Figure 20-3). The advantage of doing it this way is immediacy. Novice users are guided along a fairly narrow path initially, and they do not have to find their way around a full help system with ample opportunities for getting lost and confused.

#include "wx/tipdlg.h"
...
m_tipProvider = wxCreateFileTipProvider(tipFilename, currentTip);
wxShowTip(parent, m_tipProvider, showAtStart);

#include "wx/cshelp.h"
m_helpController = new wxCHMHelpController;
wxHelpProvider::Set(
new wxHelpControllerHelpProvider(m_helpController));