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