1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxHelpController demo
4 // Author: Karsten Ballueder
8 // Copyright: (c) Karsten Ballueder, Julian Smart
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 // ============================================================================
14 // ============================================================================
16 // ----------------------------------------------------------------------------
18 // ----------------------------------------------------------------------------
20 // For compilers that support precompilation, includes "wx/wx.h".
21 #include "wx/wxprec.h"
27 // for all others, include the necessary headers (this file is usually all you
28 // need because it includes almost all "standard" wxWindows headers
33 # include "wx/image.h"
35 # include "wx/cshelp.h"
38 # include "wx/tooltip.h"
41 // define this to 1 to use HTML help even under Windows (by default, Windows
42 // version will use WinHelp).
43 // Please also see samples/html/helpview.
45 #define USE_HTML_HELP 1
47 // Use old-style HTML help if 1
48 #define USE_OLD_HTML_HELP 0
52 #define USE_HTML_HELP 0
56 #include <wx/filesys.h>
57 #include <wx/fs_zip.h>
60 #include "wx/generic/helpwxht.h"
63 #include "wx/html/helpctrl.h"
66 #if wxUSE_MS_HTML_HELP
67 #include "wx/msw/helpchm.h"
70 #if wxUSE_MS_HTML_HELP && wxUSE_WXHTML_HELP
71 #include "wx/msw/helpbest.h"
74 // ----------------------------------------------------------------------------
76 // ----------------------------------------------------------------------------
77 // the application icon
78 #if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__)
79 #include "mondrian.xpm"
82 // ----------------------------------------------------------------------------
84 // ----------------------------------------------------------------------------
86 // Define a new application type, each program should derive a class from wxApp
87 class MyApp
: public wxApp
90 // override base class virtuals
91 // ----------------------------
93 // this one is called on application startup and is a good place for the app
94 // initialization (doing it here and not in the ctor allows to have an error
95 // return: if OnInit() returns false, the application terminates)
96 virtual bool OnInit();
98 // do some clean up here
102 // Define a new frame type: this is going to be our main frame
103 class MyFrame
: public wxFrame
107 MyFrame(const wxString
& title
, const wxPoint
& pos
, const wxSize
& size
);
109 wxHelpController
& GetHelpController() { return m_help
; }
112 #if USE_OLD_HTML_HELP
113 wxHelpControllerHtml
& GetHtmlHelpController() { return m_htmlHelp
; }
115 wxHtmlHelpController
& GetAdvancedHtmlHelpController() { return m_advancedHtmlHelp
; }
117 #if wxUSE_MS_HTML_HELP
118 wxCHMHelpController
& GetMSHtmlHelpController() { return m_msHtmlHelp
; }
120 #if wxUSE_MS_HTML_HELP && wxUSE_WXHTML_HELP
121 wxBestHelpController
& GetBestHelpController() { return m_bestHelp
; }
124 // event handlers (these functions should _not_ be virtual)
125 void OnQuit(wxCommandEvent
& event
);
126 void OnHelp(wxCommandEvent
& event
);
127 void OnHtmlHelp(wxCommandEvent
& event
);
128 void OnAdvancedHtmlHelp(wxCommandEvent
& event
);
129 void OnMSHtmlHelp(wxCommandEvent
& event
);
130 void OnBestHelp(wxCommandEvent
& event
);
132 void OnShowContextHelp(wxCommandEvent
& event
);
133 void OnShowDialogContextHelp(wxCommandEvent
& event
);
135 void ShowHelp(int commandId
, wxHelpControllerBase
& helpController
);
138 wxHelpController m_help
;
141 #if USE_OLD_HTML_HELP
142 wxHelpControllerHtml m_htmlHelp
;
144 wxHtmlHelpController m_advancedHtmlHelp
;
147 #if wxUSE_MS_HTML_HELP
148 wxCHMHelpController m_msHtmlHelp
;
151 #if wxUSE_MS_HTML_HELP && wxUSE_WXHTML_HELP
152 wxBestHelpController m_bestHelp
;
155 // any class wishing to process wxWindows events must use this macro
156 DECLARE_EVENT_TABLE()
159 // A custom modal dialog
160 class MyModalDialog
: public wxDialog
163 MyModalDialog(wxWindow
*parent
);
167 DECLARE_EVENT_TABLE()
170 // ----------------------------------------------------------------------------
172 // ----------------------------------------------------------------------------
174 // IDs for the controls and the menu commands
180 HelpDemo_Help_Classes
,
181 HelpDemo_Help_Functions
,
183 HelpDemo_Help_Search
,
184 HelpDemo_Help_ContextHelp
,
185 HelpDemo_Help_DialogContextHelp
,
187 HelpDemo_Html_Help_Index
,
188 HelpDemo_Html_Help_Classes
,
189 HelpDemo_Html_Help_Functions
,
190 HelpDemo_Html_Help_Help
,
191 HelpDemo_Html_Help_Search
,
193 HelpDemo_Advanced_Html_Help_Index
,
194 HelpDemo_Advanced_Html_Help_Classes
,
195 HelpDemo_Advanced_Html_Help_Functions
,
196 HelpDemo_Advanced_Html_Help_Help
,
197 HelpDemo_Advanced_Html_Help_Search
,
199 HelpDemo_MS_Html_Help_Index
,
200 HelpDemo_MS_Html_Help_Classes
,
201 HelpDemo_MS_Html_Help_Functions
,
202 HelpDemo_MS_Html_Help_Help
,
203 HelpDemo_MS_Html_Help_Search
,
205 HelpDemo_Best_Help_Index
,
206 HelpDemo_Best_Help_Classes
,
207 HelpDemo_Best_Help_Functions
,
208 HelpDemo_Best_Help_Help
,
209 HelpDemo_Best_Help_Search
,
213 HelpDemo_Help_Netscape
,
214 // controls start here (the numbers are, of course, arbitrary)
215 HelpDemo_Text
= 1000,
218 // ----------------------------------------------------------------------------
219 // event tables and other macros for wxWindows
220 // ----------------------------------------------------------------------------
222 // the event tables connect the wxWindows events with the functions (event
223 // handlers) which process them. It can be also done at run-time, but for the
224 // simple menu events like this the static method is much simpler.
225 BEGIN_EVENT_TABLE(MyFrame
, wxFrame
)
226 EVT_MENU(HelpDemo_Quit
, MyFrame::OnQuit
)
227 EVT_MENU(HelpDemo_Help_Index
, MyFrame::OnHelp
)
228 EVT_MENU(HelpDemo_Help_Classes
, MyFrame::OnHelp
)
229 EVT_MENU(HelpDemo_Help_Functions
, MyFrame::OnHelp
)
230 EVT_MENU(HelpDemo_Help_Help
, MyFrame::OnHelp
)
231 EVT_MENU(HelpDemo_Help_Search
, MyFrame::OnHelp
)
232 EVT_MENU(HelpDemo_Help_ContextHelp
, MyFrame::OnShowContextHelp
)
233 EVT_MENU(HelpDemo_Help_DialogContextHelp
, MyFrame::OnShowDialogContextHelp
)
235 EVT_MENU(HelpDemo_Html_Help_Index
, MyFrame::OnHtmlHelp
)
236 EVT_MENU(HelpDemo_Html_Help_Classes
, MyFrame::OnHtmlHelp
)
237 EVT_MENU(HelpDemo_Html_Help_Functions
, MyFrame::OnHtmlHelp
)
238 EVT_MENU(HelpDemo_Html_Help_Help
, MyFrame::OnHtmlHelp
)
239 EVT_MENU(HelpDemo_Html_Help_Search
, MyFrame::OnHtmlHelp
)
241 EVT_MENU(HelpDemo_Advanced_Html_Help_Index
, MyFrame::OnAdvancedHtmlHelp
)
242 EVT_MENU(HelpDemo_Advanced_Html_Help_Classes
, MyFrame::OnAdvancedHtmlHelp
)
243 EVT_MENU(HelpDemo_Advanced_Html_Help_Functions
, MyFrame::OnAdvancedHtmlHelp
)
244 EVT_MENU(HelpDemo_Advanced_Html_Help_Help
, MyFrame::OnAdvancedHtmlHelp
)
245 EVT_MENU(HelpDemo_Advanced_Html_Help_Search
, MyFrame::OnAdvancedHtmlHelp
)
247 EVT_MENU(HelpDemo_MS_Html_Help_Index
, MyFrame::OnMSHtmlHelp
)
248 EVT_MENU(HelpDemo_MS_Html_Help_Classes
, MyFrame::OnMSHtmlHelp
)
249 EVT_MENU(HelpDemo_MS_Html_Help_Functions
, MyFrame::OnMSHtmlHelp
)
250 EVT_MENU(HelpDemo_MS_Html_Help_Help
, MyFrame::OnMSHtmlHelp
)
251 EVT_MENU(HelpDemo_MS_Html_Help_Search
, MyFrame::OnMSHtmlHelp
)
253 EVT_MENU(HelpDemo_Best_Help_Index
, MyFrame::OnBestHelp
)
255 EVT_MENU(HelpDemo_Help_KDE
, MyFrame::OnHelp
)
256 EVT_MENU(HelpDemo_Help_GNOME
, MyFrame::OnHelp
)
257 EVT_MENU(HelpDemo_Help_Netscape
, MyFrame::OnHelp
)
260 // Create a new application object: this macro will allow wxWindows to create
261 // the application object during program execution (it's better than using a
262 // static object for many reasons) and also declares the accessor function
263 // wxGetApp() which will return the reference of the right type (i.e. MyApp and
267 // ============================================================================
269 // ============================================================================
271 // ----------------------------------------------------------------------------
272 // the application class
273 // ----------------------------------------------------------------------------
275 // `Main program' equivalent: the program execution "starts" here
278 // Create a simple help provider to make SetHelpText() do something.
279 // Note that this must be set before any SetHelpText() calls are made.
280 //wxHelpProvider::Set(new wxSimpleHelpProvider);
281 wxHelpControllerHelpProvider
* provider
= new wxHelpControllerHelpProvider
;
282 wxHelpProvider::Set(provider
);
286 // Required for images in the online documentation
287 wxImage::AddHandler(new wxGIFHandler
);
289 // Required for advanced HTML help
290 #if wxUSE_STREAMS && wxUSE_ZIPSTREAM && wxUSE_ZLIB
291 wxFileSystem::AddHandler(new wxZipFSHandler
);
297 // Create the main application window
298 MyFrame
*frame
= new MyFrame("HelpDemo wxWindows App",
299 wxPoint(50, 50), wxSize(450, 340));
301 #if wxUSE_MS_HTML_HELP
302 provider
->SetHelpController(& frame
->GetMSHtmlHelpController());
304 provider
->SetHelpController(& frame
->GetHelpController());
310 // initialise the help system: this means that we'll use doc.hlp file under
311 // Windows and that the HTML docs are in the subdirectory doc for platforms
313 if ( !frame
->GetHelpController().Initialize("doc") )
315 wxLogError("Cannot initialize the help system, aborting.");
320 #if wxUSE_MS_HTML_HELP
321 if( !frame
->GetMSHtmlHelpController().Initialize("doc") )
323 wxLogError("Cannot initialize the MS HTML Help system.");
327 #if wxUSE_MS_HTML_HELP && wxUSE_WXHTML_HELP
328 // you need to call Initialize in order to use wxBestHelpController
329 if( !frame
->GetBestHelpController().Initialize("doc") )
331 wxLogError("Cannot initialize the best help system, aborting.");
336 // initialise the standard HTML help system: this means that the HTML docs are in the
337 // subdirectory doc for platforms using HTML help
338 #if USE_OLD_HTML_HELP
339 if ( !frame
->GetHtmlHelpController().Initialize("doc") )
341 wxLogError("Cannot initialize the HTML help system, aborting.");
347 // initialise the advanced HTML help system: this means that the HTML docs are in .htb
349 if ( !frame
->GetAdvancedHtmlHelpController().Initialize("doc") )
351 wxLogError("Cannot initialize the advanced HTML help system, aborting.");
358 // defined(__WXMSW__) && wxUSE_MS_HTML_HELP
359 wxString
path(wxGetCwd());
360 if ( !frame
->GetMSHtmlHelpController().Initialize(path
+ "\\doc.chm") )
362 wxLogError("Cannot initialize the MS HTML help system, aborting.");
374 delete wxHelpProvider::Set(NULL
);
379 // ----------------------------------------------------------------------------
381 // ----------------------------------------------------------------------------
384 MyFrame::MyFrame(const wxString
& title
, const wxPoint
& pos
, const wxSize
& size
)
385 : wxFrame((wxFrame
*)NULL
, 300, title
, pos
, size
)
387 // set the frame icon
388 SetIcon(wxICON(mondrian
));
391 wxMenu
*menuFile
= new wxMenu
;
393 menuFile
->Append(HelpDemo_Help_Index
, "&Help Index...");
394 menuFile
->Append(HelpDemo_Help_Classes
, "&Help on Classes...");
395 menuFile
->Append(HelpDemo_Help_Functions
, "&Help on Functions...");
396 menuFile
->Append(HelpDemo_Help_ContextHelp
, "&Context Help...");
397 menuFile
->Append(HelpDemo_Help_DialogContextHelp
, "&Dialog Context Help...\tCtrl-H");
398 menuFile
->Append(HelpDemo_Help_Help
, "&About Help Demo...");
399 menuFile
->Append(HelpDemo_Help_Search
, "&Search help...");
401 #if USE_OLD_HTML_HELP
402 menuFile
->AppendSeparator();
403 menuFile
->Append(HelpDemo_Html_Help_Index
, "HTML &Help Index...");
404 menuFile
->Append(HelpDemo_Html_Help_Classes
, "HTML &Help on Classes...");
405 menuFile
->Append(HelpDemo_Html_Help_Functions
, "HTML &Help on Functions...");
406 menuFile
->Append(HelpDemo_Html_Help_Help
, "HTML &About Help Demo...");
407 menuFile
->Append(HelpDemo_Html_Help_Search
, "HTML &Search help...");
409 menuFile
->AppendSeparator();
410 menuFile
->Append(HelpDemo_Advanced_Html_Help_Index
, "Advanced HTML &Help Index...");
411 menuFile
->Append(HelpDemo_Advanced_Html_Help_Classes
, "Advanced HTML &Help on Classes...");
412 menuFile
->Append(HelpDemo_Advanced_Html_Help_Functions
, "Advanced HTML &Help on Functions...");
413 menuFile
->Append(HelpDemo_Advanced_Html_Help_Help
, "Advanced HTML &About Help Demo...");
414 menuFile
->Append(HelpDemo_Advanced_Html_Help_Search
, "Advanced HTML &Search help...");
417 #if wxUSE_MS_HTML_HELP
418 menuFile
->AppendSeparator();
419 menuFile
->Append(HelpDemo_MS_Html_Help_Index
, "MS HTML &Help Index...");
420 menuFile
->Append(HelpDemo_MS_Html_Help_Classes
, "MS HTML &Help on Classes...");
421 menuFile
->Append(HelpDemo_MS_Html_Help_Functions
, "MS HTML &Help on Functions...");
422 menuFile
->Append(HelpDemo_MS_Html_Help_Help
, "MS HTML &About Help Demo...");
423 menuFile
->Append(HelpDemo_MS_Html_Help_Search
, "MS HTML &Search help...");
426 #if wxUSE_MS_HTML_HELP && wxUSE_WXHTML_HELP
427 menuFile
->AppendSeparator();
428 menuFile
->Append(HelpDemo_Best_Help_Index
, "Best &Help Index...");
433 menuFile
->AppendSeparator();
434 menuFile
->Append(HelpDemo_Help_KDE
, "Use &KDE");
435 menuFile
->Append(HelpDemo_Help_GNOME
, "Use &GNOME");
436 menuFile
->Append(HelpDemo_Help_Netscape
, "Use &Netscape");
439 menuFile
->AppendSeparator();
440 menuFile
->Append(HelpDemo_Quit
, "E&xit");
442 // now append the freshly created menu to the menu bar...
443 wxMenuBar
*menuBar
= new wxMenuBar
;
444 menuBar
->Append(menuFile
, "&File");
446 // ... and attach this menu bar to the frame
449 // create a status bar just for fun (by default with 1 pane only)
451 SetStatusText("Welcome to wxWindows!");
453 // now create some controls
455 // a panel first - if there were several controls, it would allow us to
456 // navigate between them from the keyboard
457 wxPanel
*panel
= new wxPanel(this, 301, wxPoint(0, 0), wxSize(400, 200));
458 //panel->SetHelpText(_("This panel just holds a static text control."));
459 panel
->SetHelpText(wxContextId(300));
461 // and a static control whose parent is the panel
462 wxStaticText
* staticText
= new wxStaticText(panel
, 302, "Hello, world!", wxPoint(10, 10));
463 staticText
->SetHelpText(_("This static text control isn't doing a lot right now."));
469 void MyFrame::OnQuit(wxCommandEvent
& WXUNUSED(event
))
471 // TRUE is to force the frame to close
475 void MyFrame::OnHelp(wxCommandEvent
& event
)
477 ShowHelp(event
.GetId(), m_help
);
480 void MyFrame::OnShowContextHelp(wxCommandEvent
& event
)
482 // This starts context help mode, then the user
483 // clicks on a window to send a help message
484 wxContextHelp
contextHelp(this);
487 void MyFrame::OnShowDialogContextHelp(wxCommandEvent
& event
)
489 MyModalDialog
dialog(this);
493 void MyFrame::OnHtmlHelp(wxCommandEvent
& event
)
495 #if USE_HTML_HELP && USE_OLD_HTML_HELP
496 ShowHelp(event
.GetId(), m_htmlHelp
);
500 void MyFrame::OnAdvancedHtmlHelp(wxCommandEvent
& event
)
503 ShowHelp(event
.GetId(), m_advancedHtmlHelp
);
507 void MyFrame::OnMSHtmlHelp(wxCommandEvent
& event
)
509 #if wxUSE_MS_HTML_HELP
510 ShowHelp(event
.GetId(), m_msHtmlHelp
);
514 void MyFrame::OnBestHelp(wxCommandEvent
& event
)
516 #if wxUSE_MS_HTML_HELP && wxUSE_HTML
517 ShowHelp(event
.GetId(), m_bestHelp
);
522 Notes: ShowHelp uses section ids for displaying particular topics,
523 but you might want to use a unique keyword to display a topic, instead.
525 Section ids are specified as follows for the different formats.
529 The [MAP] section specifies the topic to integer id mapping, e.g.
537 The identifier name corresponds to the label used for that topic.
538 You could also put these in a .h file and #include it in both the MAP
539 section and your C++ source.
541 Note that Tex2RTF doesn't currently generate the MAP section automatically.
545 The [MAP] section specifies the HTML filename root to integer id mapping, e.g.
553 The identifier name corresponds to the HTML filename used for that topic.
554 You could also put these in a .h file and #include it in both the MAP
555 section and your C++ source.
557 Note that Tex2RTF doesn't currently generate the MAP section automatically.
559 Simple wxHTML Help and External HTML Help
561 A wxhelp.map file is used, for example:
563 0 wx.htm ; wxWindows: Help index; additional keywords like overview
564 1 wx204.htm ; wxWindows Function Reference
565 2 wx34.htm ; wxWindows Class Reference
567 Note that Tex2RTF doesn't currently generate the MAP section automatically.
571 An extension to the .hhc file format is used, specifying a new parameter
574 <OBJECT type="text/sitemap">
575 <param name="Local" value="doc2.htm#classes">
576 <param name="Name" value="Classes">
577 <param name="ID" value=2>
580 Again, this is not generated automatically by Tex2RTF, though it could
581 be added quite easily.
583 Unfortunately adding the ID parameters appears to interfere with MS HTML Help,
584 so you should not try to compile a .chm file from a .hhc file with
585 this extension, or the contents will be messed up.
588 void MyFrame::ShowHelp(int commandId
, wxHelpControllerBase
& helpController
)
592 case HelpDemo_Help_Classes
:
593 case HelpDemo_Html_Help_Classes
:
594 case HelpDemo_Advanced_Html_Help_Classes
:
595 case HelpDemo_MS_Html_Help_Classes
:
596 case HelpDemo_Best_Help_Classes
:
597 helpController
.DisplaySection(2);
598 //helpController.DisplaySection("Classes"); // An alternative form for most controllers
601 case HelpDemo_Help_Functions
:
602 case HelpDemo_Html_Help_Functions
:
603 case HelpDemo_Advanced_Html_Help_Functions
:
604 case HelpDemo_MS_Html_Help_Functions
:
605 helpController
.DisplaySection(1);
606 //helpController.DisplaySection("Functions"); // An alternative form for most controllers
608 case HelpDemo_Help_Help
:
609 case HelpDemo_Html_Help_Help
:
610 case HelpDemo_Advanced_Html_Help_Help
:
611 case HelpDemo_MS_Html_Help_Help
:
612 case HelpDemo_Best_Help_Help
:
613 helpController
.DisplaySection(3);
614 //helpController.DisplaySection("About"); // An alternative form for most controllers
617 case HelpDemo_Help_Search
:
618 case HelpDemo_Html_Help_Search
:
619 case HelpDemo_Advanced_Html_Help_Search
:
620 case HelpDemo_MS_Html_Help_Search
:
621 case HelpDemo_Best_Help_Search
:
623 wxString key
= wxGetTextFromUser("Search for?",
624 "Search help for keyword",
628 helpController
.KeywordSearch(key
);
632 case HelpDemo_Help_Index
:
633 case HelpDemo_Html_Help_Index
:
634 case HelpDemo_Advanced_Html_Help_Index
:
635 case HelpDemo_MS_Html_Help_Index
:
636 case HelpDemo_Best_Help_Index
:
637 helpController
.DisplayContents();
640 // These three calls are only used by wxExtHelpController
642 case HelpDemo_Help_KDE
:
643 helpController
.SetViewer("kdehelp");
645 case HelpDemo_Help_GNOME
:
646 helpController
.SetViewer("gnome-help-browser");
648 case HelpDemo_Help_Netscape
:
649 helpController
.SetViewer("netscape", wxHELP_NETSCAPE
);
656 // ----------------------------------------------------------------------------
658 // Demonstrates context-sensitive help
659 // ----------------------------------------------------------------------------
661 BEGIN_EVENT_TABLE(MyModalDialog
, wxDialog
)
664 MyModalDialog::MyModalDialog(wxWindow
*parent
)
667 // Add the context-sensitive help button on the caption for MSW
669 SetExtraStyle(wxDIALOG_EX_CONTEXTHELP
);
672 wxDialog::Create(parent
, -1, wxString("Modal dialog"));
674 wxBoxSizer
*sizerTop
= new wxBoxSizer(wxVERTICAL
);
675 wxBoxSizer
*sizerRow
= new wxBoxSizer(wxHORIZONTAL
);
677 wxButton
* btnOK
= new wxButton(this, wxID_OK
, "&OK");
678 btnOK
->SetHelpText(_("The OK button confirms the dialog choices."));
680 wxButton
* btnCancel
= new wxButton(this, wxID_CANCEL
, "&Cancel");
681 btnCancel
->SetHelpText(_("The Cancel button cancels the dialog."));
683 sizerRow
->Add(btnOK
, 0, wxALIGN_CENTER
| wxALL
, 5);
684 sizerRow
->Add(btnCancel
, 0, wxALIGN_CENTER
| wxALL
, 5);
686 // Add explicit context-sensitive help button for non-MSW
688 sizerRow
->Add(new wxContextHelpButton(this), 0, wxALIGN_CENTER
| wxALL
, 5);
691 wxTextCtrl
*text
= new wxTextCtrl(this, -1, wxT("A demo text control"),
692 wxDefaultPosition
, wxSize(300, 100),
694 text
->SetHelpText(_("Type text here if you have got nothing more "
695 "interesting to do"));
696 sizerTop
->Add(text
, 0, wxEXPAND
|wxALIGN_CENTER_VERTICAL
|wxALL
, 5 );
697 sizerTop
->Add(sizerRow
, 0, wxALIGN_RIGHT
|wxALIGN_CENTER_VERTICAL
|wxALL
, 5 );
702 sizerTop
->SetSizeHints(this);