samples/help/demo.cpp

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        demo.cpp
   3 // Purpose:     wxHelpController demo
   4 // Author:      Karsten Ballueder
   5 // Modified by:
   6 // Created:     04/01/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Karsten Ballueder, Julian Smart
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 // ============================================================================
  13 // declarations
  14 // ============================================================================
  15
  16 // ----------------------------------------------------------------------------
  17 // headers
  18 // ----------------------------------------------------------------------------
  19
  20 // For compilers that support precompilation, includes "wx/wx.h".
  21 #include "wx/wxprec.h"
  22
  23 #ifdef __BORLANDC__
  24 #   pragma hdrstop
  25 #endif
  26
  27 // for all others, include the necessary headers (this file is usually all you
  28 // need because it includes almost all "standard" wxWindows headers
  29 #ifndef WX_PRECOMP
  30 #   include "wx/wx.h"
  31 #endif
  32
  33 #   include "wx/image.h"
  34 #   include "wx/help.h"
  35 #   include "wx/cshelp.h"
  36
  37 #if wxUSE_TOOLTIPS
  38 #   include "wx/tooltip.h"
  39 #endif
  40
  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.
  44
  45 #define USE_HTML_HELP 1
  46
  47 // Use old-style HTML help if 1
  48 #define USE_OLD_HTML_HELP 0
  49
  50 #if !wxUSE_HTML
  51 #undef USE_HTML_HELP
  52 #define USE_HTML_HELP 0
  53 #endif
  54
  55 #if USE_HTML_HELP
  56 #include <wx/filesys.h>
  57 #include <wx/fs_zip.h>
  58
  59 #if USE_OLD_HTML_HELP
  60 #include "wx/generic/helpwxht.h"
  61 #endif
  62
  63 #include "wx/html/helpctrl.h"
  64 #endif
  65
  66 #if wxUSE_MS_HTML_HELP
  67 #include "wx/msw/helpchm.h"
  68 #endif
  69
  70 // ----------------------------------------------------------------------------
  71 // ressources
  72 // ----------------------------------------------------------------------------
  73 // the application icon
  74 #if defined(__WXGTK__) || defined(__WXMOTIF__)
  75     #include "mondrian.xpm"
  76 #endif
  77
  78 // ----------------------------------------------------------------------------
  79 // private classes
  80 // ----------------------------------------------------------------------------
  81
  82 // Define a new application type, each program should derive a class from wxApp
  83 class MyApp : public wxApp
  84 {
  85 public:
  86     // override base class virtuals
  87     // ----------------------------
  88
  89     // this one is called on application startup and is a good place for the app
  90     // initialization (doing it here and not in the ctor allows to have an error
  91     // return: if OnInit() returns false, the application terminates)
  92     virtual bool OnInit();
  93 };
  94
  95 // Define a new frame type: this is going to be our main frame
  96 class MyFrame : public wxFrame
  97 {
  98 public:
  99     // ctor(s)
 100     MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
 101
 102     wxHelpController& GetHelpController() { return m_help; }
 103
 104 #if USE_HTML_HELP
 105 #if USE_OLD_HTML_HELP
 106     wxHelpControllerHtml& GetHtmlHelpController() { return m_htmlHelp; }
 107 #endif
 108     wxHtmlHelpController& GetAdvancedHtmlHelpController() { return m_advancedHtmlHelp; }
 109 #endif
 110 #if wxUSE_MS_HTML_HELP
 111     wxCHMHelpController& GetMSHtmlHelpController() { return m_msHtmlHelp; }
 112 #endif
 113
 114     // event handlers (these functions should _not_ be virtual)
 115     void OnQuit(wxCommandEvent& event);
 116     void OnHelp(wxCommandEvent& event);
 117     void OnHtmlHelp(wxCommandEvent& event);
 118     void OnAdvancedHtmlHelp(wxCommandEvent& event);
 119     void OnMSHtmlHelp(wxCommandEvent& event);
 120
 121     void OnContextHelp(wxHelpEvent& event);
 122     void OnShowContextHelp(wxCommandEvent& event);
 123
 124     void ShowHelp(int commandId, wxHelpControllerBase& helpController);
 125
 126 private:
 127    wxHelpController         m_help;
 128
 129 #if USE_HTML_HELP
 130 #if USE_OLD_HTML_HELP
 131    wxHelpControllerHtml     m_htmlHelp;
 132 #endif
 133    wxHtmlHelpController     m_advancedHtmlHelp;
 134 #endif
 135
 136 #if wxUSE_MS_HTML_HELP
 137     wxCHMHelpController     m_msHtmlHelp;
 138 #endif
 139
 140     // any class wishing to process wxWindows events must use this macro
 141    DECLARE_EVENT_TABLE()
 142 };
 143
 144 // ----------------------------------------------------------------------------
 145 // constants
 146 // ----------------------------------------------------------------------------
 147
 148 // IDs for the controls and the menu commands
 149 enum
 150 {
 151     // menu items
 152     HelpDemo_Quit = 1,
 153     HelpDemo_Help_Index,
 154     HelpDemo_Help_Classes,
 155     HelpDemo_Help_Functions,
 156     HelpDemo_Help_Help,
 157     HelpDemo_Help_Search,
 158     HelpDemo_Help_ContextHelp,
 159
 160     HelpDemo_Html_Help_Index,
 161     HelpDemo_Html_Help_Classes,
 162     HelpDemo_Html_Help_Functions,
 163     HelpDemo_Html_Help_Help,
 164     HelpDemo_Html_Help_Search,
 165
 166     HelpDemo_Advanced_Html_Help_Index,
 167     HelpDemo_Advanced_Html_Help_Classes,
 168     HelpDemo_Advanced_Html_Help_Functions,
 169     HelpDemo_Advanced_Html_Help_Help,
 170     HelpDemo_Advanced_Html_Help_Search,
 171
 172     HelpDemo_MS_Html_Help_Index,
 173     HelpDemo_MS_Html_Help_Classes,
 174     HelpDemo_MS_Html_Help_Functions,
 175     HelpDemo_MS_Html_Help_Help,
 176     HelpDemo_MS_Html_Help_Search,
 177
 178     HelpDemo_Help_KDE,
 179     HelpDemo_Help_GNOME,
 180     HelpDemo_Help_Netscape,
 181     // controls start here (the numbers are, of course, arbitrary)
 182     HelpDemo_Text = 1000,
 183 };
 184
 185 // ----------------------------------------------------------------------------
 186 // event tables and other macros for wxWindows
 187 // ----------------------------------------------------------------------------
 188
 189 // the event tables connect the wxWindows events with the functions (event
 190 // handlers) which process them. It can be also done at run-time, but for the
 191 // simple menu events like this the static method is much simpler.
 192 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
 193     EVT_MENU(HelpDemo_Quit,  MyFrame::OnQuit)
 194     EVT_MENU(HelpDemo_Help_Index, MyFrame::OnHelp)
 195     EVT_MENU(HelpDemo_Help_Classes, MyFrame::OnHelp)
 196     EVT_MENU(HelpDemo_Help_Functions, MyFrame::OnHelp)
 197     EVT_MENU(HelpDemo_Help_Help, MyFrame::OnHelp)
 198     EVT_MENU(HelpDemo_Help_Search, MyFrame::OnHelp)
 199     EVT_MENU(HelpDemo_Help_ContextHelp, MyFrame::OnShowContextHelp)
 200
 201     EVT_HELP(-1, MyFrame::OnContextHelp)
 202
 203     EVT_MENU(HelpDemo_Html_Help_Index, MyFrame::OnHtmlHelp)
 204     EVT_MENU(HelpDemo_Html_Help_Classes, MyFrame::OnHtmlHelp)
 205     EVT_MENU(HelpDemo_Html_Help_Functions, MyFrame::OnHtmlHelp)
 206     EVT_MENU(HelpDemo_Html_Help_Help, MyFrame::OnHtmlHelp)
 207     EVT_MENU(HelpDemo_Html_Help_Search, MyFrame::OnHtmlHelp)
 208
 209     EVT_MENU(HelpDemo_Advanced_Html_Help_Index, MyFrame::OnAdvancedHtmlHelp)
 210     EVT_MENU(HelpDemo_Advanced_Html_Help_Classes, MyFrame::OnAdvancedHtmlHelp)
 211     EVT_MENU(HelpDemo_Advanced_Html_Help_Functions, MyFrame::OnAdvancedHtmlHelp)
 212     EVT_MENU(HelpDemo_Advanced_Html_Help_Help, MyFrame::OnAdvancedHtmlHelp)
 213     EVT_MENU(HelpDemo_Advanced_Html_Help_Search, MyFrame::OnAdvancedHtmlHelp)
 214
 215     EVT_MENU(HelpDemo_MS_Html_Help_Index, MyFrame::OnMSHtmlHelp)
 216     EVT_MENU(HelpDemo_MS_Html_Help_Classes, MyFrame::OnMSHtmlHelp)
 217     EVT_MENU(HelpDemo_MS_Html_Help_Functions, MyFrame::OnMSHtmlHelp)
 218     EVT_MENU(HelpDemo_MS_Html_Help_Help, MyFrame::OnMSHtmlHelp)
 219     EVT_MENU(HelpDemo_MS_Html_Help_Search, MyFrame::OnMSHtmlHelp)
 220
 221     EVT_MENU(HelpDemo_Help_KDE, MyFrame::OnHelp)
 222     EVT_MENU(HelpDemo_Help_GNOME, MyFrame::OnHelp)
 223     EVT_MENU(HelpDemo_Help_Netscape, MyFrame::OnHelp)
 224 END_EVENT_TABLE()
 225
 226 // Create a new application object: this macro will allow wxWindows to create
 227 // the application object during program execution (it's better than using a
 228 // static object for many reasons) and also declares the accessor function
 229 // wxGetApp() which will return the reference of the right type (i.e. MyApp and
 230 // not wxApp)
 231 IMPLEMENT_APP(MyApp)
 232
 233 // ============================================================================
 234 // implementation
 235 // ============================================================================
 236
 237 // ----------------------------------------------------------------------------
 238 // the application class
 239 // ----------------------------------------------------------------------------
 240
 241 // `Main program' equivalent: the program execution "starts" here
 242 bool MyApp::OnInit()
 243 {
 244 #if wxUSE_HTML
 245 #if wxUSE_GIF
 246     // Required for images in the online documentation
 247     wxImage::AddHandler(new wxGIFHandler);
 248
 249     // Required for advanced HTML help
 250 #if wxUSE_STREAMS && wxUSE_ZIPSTREAM && wxUSE_ZLIB
 251       wxFileSystem::AddHandler(new wxZipFSHandler);
 252 #endif
 253
 254 #endif
 255 #endif
 256
 257     // Create the main application window
 258     MyFrame *frame = new MyFrame("HelpDemo wxWindows App",
 259                                  wxPoint(50, 50), wxSize(450, 340));
 260
 261     frame->Show(TRUE);
 262     SetTopWindow(frame);
 263
 264     // initialise the help system: this means that we'll use doc.hlp file under
 265     // Windows and that the HTML docs are in the subdirectory doc for platforms
 266     // using HTML help
 267     if ( !frame->GetHelpController().Initialize("doc") )
 268     {
 269         wxLogError("Cannot initialize the help system, aborting.");
 270
 271         return FALSE;
 272     }
 273
 274 #if USE_HTML_HELP
 275     // initialise the standard HTML help system: this means that the HTML docs are in the
 276     // subdirectory doc for platforms using HTML help
 277 #if USE_OLD_HTML_HELP
 278     if ( !frame->GetHtmlHelpController().Initialize("doc") )
 279     {
 280         wxLogError("Cannot initialize the HTML help system, aborting.");
 281
 282         return FALSE;
 283     }
 284 #endif
 285
 286     // initialise the advanced HTML help system: this means that the HTML docs are in .htb
 287     // (zipped) form
 288     if ( !frame->GetAdvancedHtmlHelpController().Initialize("doc") )
 289     {
 290         wxLogError("Cannot initialize the advanced HTML help system, aborting.");
 291
 292         return FALSE;
 293     }
 294 #endif
 295
 296 #if wxUSE_MS_HTML_HELP
 297     if ( !frame->GetMSHtmlHelpController().Initialize("doc") )
 298     {
 299         wxLogError("Cannot initialize the MS HTML help system, aborting.");
 300
 301         return FALSE;
 302     }
 303 #endif
 304
 305     return TRUE;
 306 }
 307
 308 // ----------------------------------------------------------------------------
 309 // main frame
 310 // ----------------------------------------------------------------------------
 311
 312 // frame constructor
 313 MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
 314        : wxFrame((wxFrame *)NULL, -1, title, pos, size)
 315 {
 316     // set the frame icon
 317     SetIcon(wxICON(mondrian));
 318
 319     // create a menu bar
 320     wxMenu *menuFile = new wxMenu;
 321
 322     menuFile->Append(HelpDemo_Help_Index, "&Help Index...");
 323     menuFile->Append(HelpDemo_Help_Classes, "&Help on Classes...");
 324     menuFile->Append(HelpDemo_Help_Functions, "&Help on Functions...");
 325     menuFile->Append(HelpDemo_Help_ContextHelp, "&Context Help...");
 326     menuFile->Append(HelpDemo_Help_Help, "&About Help Demo...");
 327     menuFile->Append(HelpDemo_Help_Search, "&Search help...");
 328 #if USE_HTML_HELP
 329 #if USE_OLD_HTML_HELP
 330     menuFile->AppendSeparator();
 331     menuFile->Append(HelpDemo_Html_Help_Index, "HTML &Help Index...");
 332     menuFile->Append(HelpDemo_Html_Help_Classes, "HTML &Help on Classes...");
 333     menuFile->Append(HelpDemo_Html_Help_Functions, "HTML &Help on Functions...");
 334     menuFile->Append(HelpDemo_Html_Help_Help, "HTML &About Help Demo...");
 335     menuFile->Append(HelpDemo_Html_Help_Search, "HTML &Search help...");
 336 #endif
 337     menuFile->AppendSeparator();
 338     menuFile->Append(HelpDemo_Advanced_Html_Help_Index, "Advanced HTML &Help Index...");
 339     menuFile->Append(HelpDemo_Advanced_Html_Help_Classes, "Advanced HTML &Help on Classes...");
 340     menuFile->Append(HelpDemo_Advanced_Html_Help_Functions, "Advanced HTML &Help on Functions...");
 341     menuFile->Append(HelpDemo_Advanced_Html_Help_Help, "Advanced HTML &About Help Demo...");
 342     menuFile->Append(HelpDemo_Advanced_Html_Help_Search, "Advanced HTML &Search help...");
 343 #endif
 344
 345 #if wxUSE_MS_HTML_HELP
 346     menuFile->AppendSeparator();
 347     menuFile->Append(HelpDemo_MS_Html_Help_Index, "MS HTML &Help Index...");
 348     menuFile->Append(HelpDemo_MS_Html_Help_Classes, "MS HTML &Help on Classes...");
 349     menuFile->Append(HelpDemo_MS_Html_Help_Functions, "MS HTML &Help on Functions...");
 350     menuFile->Append(HelpDemo_MS_Html_Help_Help, "MS HTML &About Help Demo...");
 351     menuFile->Append(HelpDemo_MS_Html_Help_Search, "MS HTML &Search help...");
 352 #endif
 353
 354 #ifndef __WXMSW__
 355 #if !wxUSE_HTML
 356     menuFile->AppendSeparator();
 357     menuFile->Append(HelpDemo_Help_KDE, "Use &KDE");
 358     menuFile->Append(HelpDemo_Help_GNOME, "Use &GNOME");
 359     menuFile->Append(HelpDemo_Help_Netscape, "Use &Netscape");
 360 #endif
 361 #endif
 362     menuFile->AppendSeparator();
 363     menuFile->Append(HelpDemo_Quit, "E&xit");
 364
 365     // now append the freshly created menu to the menu bar...
 366     wxMenuBar *menuBar = new wxMenuBar;
 367     menuBar->Append(menuFile, "&File");
 368
 369     // ... and attach this menu bar to the frame
 370     SetMenuBar(menuBar);
 371
 372     // create a status bar just for fun (by default with 1 pane only)
 373     CreateStatusBar();
 374     SetStatusText("Welcome to wxWindows!");
 375
 376     // now create some controls
 377
 378     // a panel first - if there were several controls, it would allow us to
 379     // navigate between them from the keyboard
 380     wxPanel *panel = new wxPanel(this, -1, wxPoint(0, 0), wxSize(400, 200));
 381
 382     // and a static control whose parent is the panel
 383     (void)new wxStaticText(panel, -1, "Hello, world!", wxPoint(10, 10));
 384 }
 385
 386
 387 // event handlers
 388
 389 void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
 390 {
 391     // TRUE is to force the frame to close
 392     Close(TRUE);
 393 }
 394
 395 void MyFrame::OnHelp(wxCommandEvent& event)
 396 {
 397     ShowHelp(event.GetId(), m_help);
 398 }
 399
 400 void MyFrame::OnShowContextHelp(wxCommandEvent& event)
 401 {
 402     // This starts context help mode, then the user
 403     // clicks on a window to send a help message
 404     wxContextHelp contextHelp(this);
 405 }
 406
 407 void MyFrame::OnContextHelp(wxHelpEvent& event)
 408 {
 409     // In a real app, if we didn't recognise this ID, we should call event.Skip()
 410     wxString msg;
 411     msg.Printf(wxT("We should now display help for window %d"), event.GetId());
 412     wxMessageBox(msg);
 413     //wxToolTip::Enable(TRUE);
 414     //SetToolTip(msg);
 415 }
 416
 417 void MyFrame::OnHtmlHelp(wxCommandEvent& event)
 418 {
 419 #if USE_HTML_HELP && USE_OLD_HTML_HELP
 420     ShowHelp(event.GetId(), m_htmlHelp);
 421 #endif
 422 }
 423
 424 void MyFrame::OnAdvancedHtmlHelp(wxCommandEvent& event)
 425 {
 426 #if USE_HTML_HELP
 427     ShowHelp(event.GetId(), m_advancedHtmlHelp);
 428 #endif
 429 }
 430
 431 void MyFrame::OnMSHtmlHelp(wxCommandEvent& event)
 432 {
 433 #if wxUSE_MS_HTML_HELP
 434     ShowHelp(event.GetId(), m_msHtmlHelp);
 435 #endif
 436 }
 437
 438 /*
 439  Notes: ShowHelp uses section ids for displaying particular topics,
 440  but you might want to use a unique keyword to display a topic, instead.
 441
 442  Section ids are specified as follows for the different formats.
 443
 444  WinHelp
 445
 446    The [MAP] section specifies the topic to integer id mapping, e.g.
 447
 448    [MAP]
 449    #define intro       100
 450    #define functions   1
 451    #define classes     2
 452    #define about       3
 453
 454    The identifier name corresponds to the label used for that topic.
 455    You could also put these in a .h file and #include it in both the MAP
 456    section and your C++ source.
 457
 458    Note that Tex2RTF doesn't currently generate the MAP section automatically.
 459
 460  MS HTML Help
 461
 462    The [MAP] section specifies the HTML filename root to integer id mapping, e.g.
 463
 464    [MAP]
 465    #define doc1       100
 466    #define doc3       1
 467    #define doc2       2
 468    #define doc4       3
 469
 470    The identifier name corresponds to the HTML filename used for that topic.
 471    You could also put these in a .h file and #include it in both the MAP
 472    section and your C++ source.
 473
 474    Note that Tex2RTF doesn't currently generate the MAP section automatically.
 475
 476  Simple wxHTML Help and External HTML Help
 477
 478    A wxhelp.map file is used, for example:
 479
 480    0 wx.htm             ; wxWindows: Help index; additional keywords like overview
 481    1 wx204.htm          ; wxWindows Function Reference
 482    2 wx34.htm           ; wxWindows Class Reference
 483
 484    Note that Tex2RTF doesn't currently generate the MAP section automatically.
 485
 486  Advanced HTML Help
 487
 488    An extension to the .hhc file format is used, specifying a new parameter
 489    with name="ID":
 490
 491    <OBJECT type="text/sitemap">
 492    <param name="Local" value="doc2.htm#classes">
 493    <param name="Name" value="Classes">
 494    <param name="ID" value=2>
 495    </OBJECT>
 496
 497    Again, this is not generated automatically by Tex2RTF, though it could
 498    be added quite easily.
 499
 500    Unfortunately adding the ID parameters appears to interfere with MS HTML Help,
 501    so you should not try to compile a .chm file from a .hhc file with
 502    this extension, or the contents will be messed up.
 503  */
 504
 505 void MyFrame::ShowHelp(int commandId, wxHelpControllerBase& helpController)
 506 {
 507    switch(commandId)
 508    {
 509    case HelpDemo_Help_Classes:
 510    case HelpDemo_Html_Help_Classes:
 511    case HelpDemo_Advanced_Html_Help_Classes:
 512    case HelpDemo_MS_Html_Help_Classes:
 513       helpController.DisplaySection(2);
 514       //helpController.DisplaySection("Classes"); // An alternative form for most controllers
 515
 516       break;
 517    case HelpDemo_Help_Functions:
 518    case HelpDemo_Html_Help_Functions:
 519    case HelpDemo_Advanced_Html_Help_Functions:
 520    case HelpDemo_MS_Html_Help_Functions:
 521       helpController.DisplaySection(1);
 522       //helpController.DisplaySection("Functions"); // An alternative form for most controllers
 523       break;
 524    case HelpDemo_Help_Help:
 525    case HelpDemo_Html_Help_Help:
 526    case HelpDemo_Advanced_Html_Help_Help:
 527    case HelpDemo_MS_Html_Help_Help:
 528       helpController.DisplaySection(3);
 529       //helpController.DisplaySection("About"); // An alternative form for most controllers
 530       break;
 531
 532    case HelpDemo_Help_Search:
 533    case HelpDemo_Html_Help_Search:
 534    case HelpDemo_Advanced_Html_Help_Search:
 535    case HelpDemo_MS_Html_Help_Search:
 536    {
 537       wxString key = wxGetTextFromUser("Search for?",
 538                                        "Search help for keyword",
 539                                        "",
 540                                        this);
 541       if(! key.IsEmpty())
 542          helpController.KeywordSearch(key);
 543    }
 544    break;
 545
 546    case HelpDemo_Help_Index:
 547    case HelpDemo_Html_Help_Index:
 548    case HelpDemo_Advanced_Html_Help_Index:
 549    case HelpDemo_MS_Html_Help_Index:
 550       helpController.DisplayContents();
 551       break;
 552
 553    // These three calls are only used by wxExtHelpController
 554
 555    case HelpDemo_Help_KDE:
 556       helpController.SetViewer("kdehelp");
 557       break;
 558    case HelpDemo_Help_GNOME:
 559       helpController.SetViewer("gnome-help-browser");
 560       break;
 561    case HelpDemo_Help_Netscape:
 562       helpController.SetViewer("netscape", wxHELP_NETSCAPE);
 563       break;
 564
 565    default:
 566       break;
 567    }
 568 }
 569