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