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