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 for a more complex help viewer.
  39
  40 #define USE_HTML_HELP 1
  41
  42 #if !wxUSE_HTML
  43 #undef USE_HTML_HELP
  44 #define USE_HTML_HELP 0
  45 #endif
  46
  47 #if USE_HTML_HELP
  48
  49 #include <wx/filesys.h>
  50 #include <wx/fs_zip.h>
  51
  52 #include "wx/generic/helpwxht.h"
  53 #include "wx/html/helpctrl.h"
  54 #endif
  55
  56 // ----------------------------------------------------------------------------
  57 // ressources
  58 // ----------------------------------------------------------------------------
  59 // the application icon
  60 #if defined(__WXGTK__) || defined(__WXMOTIF__)
  61     #include "mondrian.xpm"
  62 #endif
  63
  64 // ----------------------------------------------------------------------------
  65 // private classes
  66 // ----------------------------------------------------------------------------
  67
  68 // Define a new application type, each program should derive a class from wxApp
  69 class MyApp : public wxApp
  70 {
  71 public:
  72     // override base class virtuals
  73     // ----------------------------
  74
  75     // this one is called on application startup and is a good place for the app
  76     // initialization (doing it here and not in the ctor allows to have an error
  77     // return: if OnInit() returns false, the application terminates)
  78     virtual bool OnInit();
  79 };
  80
  81 // Define a new frame type: this is going to be our main frame
  82 class MyFrame : public wxFrame
  83 {
  84 public:
  85     // ctor(s)
  86     MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
  87
  88     wxHelpController& GetHelpController() { return m_help; }
  89
  90 #if USE_HTML_HELP
  91     wxHelpControllerHtml& GetHtmlHelpController() { return m_htmlHelp; }
  92     wxHtmlHelpController& GetAdvancedHtmlHelpController() { return m_advancedHtmlHelp; }
  93 #endif
  94
  95     // event handlers (these functions should _not_ be virtual)
  96     void OnQuit(wxCommandEvent& event);
  97     void OnHelp(wxCommandEvent& event);
  98     void OnHtmlHelp(wxCommandEvent& event);
  99     void OnAdvancedHtmlHelp(wxCommandEvent& event);
 100
 101 private:
 102    wxHelpController         m_help;
 103
 104 #if USE_HTML_HELP
 105    wxHelpControllerHtml     m_htmlHelp;
 106    wxHtmlHelpController     m_advancedHtmlHelp;
 107 #endif
 108
 109     // any class wishing to process wxWindows events must use this macro
 110    DECLARE_EVENT_TABLE()
 111 };
 112
 113 // ----------------------------------------------------------------------------
 114 // constants
 115 // ----------------------------------------------------------------------------
 116
 117 // IDs for the controls and the menu commands
 118 enum
 119 {
 120     // menu items
 121     HelpDemo_Quit = 1,
 122     HelpDemo_Help_Index,
 123     HelpDemo_Help_Classes,
 124     HelpDemo_Help_Functions,
 125     HelpDemo_Help_Help,
 126     HelpDemo_Help_Search,
 127
 128     HelpDemo_Html_Help_Index,
 129     HelpDemo_Html_Help_Classes,
 130     HelpDemo_Html_Help_Functions,
 131     HelpDemo_Html_Help_Help,
 132     HelpDemo_Html_Help_Search,
 133
 134     HelpDemo_Advanced_Html_Help_Index,
 135     HelpDemo_Advanced_Html_Help_Classes,
 136     HelpDemo_Advanced_Html_Help_Functions,
 137     HelpDemo_Advanced_Html_Help_Help,
 138     HelpDemo_Advanced_Html_Help_Search,
 139
 140     HelpDemo_Help_KDE,
 141     HelpDemo_Help_GNOME,
 142     HelpDemo_Help_Netscape,
 143     // controls start here (the numbers are, of course, arbitrary)
 144     HelpDemo_Text = 1000,
 145 };
 146
 147 // ----------------------------------------------------------------------------
 148 // event tables and other macros for wxWindows
 149 // ----------------------------------------------------------------------------
 150
 151 // the event tables connect the wxWindows events with the functions (event
 152 // handlers) which process them. It can be also done at run-time, but for the
 153 // simple menu events like this the static method is much simpler.
 154 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
 155     EVT_MENU(HelpDemo_Quit,  MyFrame::OnQuit)
 156     EVT_MENU(HelpDemo_Help_Index, MyFrame::OnHelp)
 157     EVT_MENU(HelpDemo_Help_Classes, MyFrame::OnHelp)
 158     EVT_MENU(HelpDemo_Help_Functions, MyFrame::OnHelp)
 159     EVT_MENU(HelpDemo_Help_Help, MyFrame::OnHelp)
 160     EVT_MENU(HelpDemo_Help_Search, MyFrame::OnHelp)
 161
 162     EVT_MENU(HelpDemo_Html_Help_Index, MyFrame::OnHtmlHelp)
 163     EVT_MENU(HelpDemo_Html_Help_Classes, MyFrame::OnHtmlHelp)
 164     EVT_MENU(HelpDemo_Html_Help_Functions, MyFrame::OnHtmlHelp)
 165     EVT_MENU(HelpDemo_Html_Help_Help, MyFrame::OnHtmlHelp)
 166     EVT_MENU(HelpDemo_Html_Help_Search, MyFrame::OnHtmlHelp)
 167
 168     EVT_MENU(HelpDemo_Advanced_Html_Help_Index, MyFrame::OnAdvancedHtmlHelp)
 169     EVT_MENU(HelpDemo_Advanced_Html_Help_Classes, MyFrame::OnAdvancedHtmlHelp)
 170     EVT_MENU(HelpDemo_Advanced_Html_Help_Functions, MyFrame::OnAdvancedHtmlHelp)
 171     EVT_MENU(HelpDemo_Advanced_Html_Help_Help, MyFrame::OnAdvancedHtmlHelp)
 172     EVT_MENU(HelpDemo_Advanced_Html_Help_Search, MyFrame::OnAdvancedHtmlHelp)
 173
 174     EVT_MENU(HelpDemo_Help_KDE, MyFrame::OnHelp)
 175     EVT_MENU(HelpDemo_Help_GNOME, MyFrame::OnHelp)
 176     EVT_MENU(HelpDemo_Help_Netscape, MyFrame::OnHelp)
 177 END_EVENT_TABLE()
 178
 179 // Create a new application object: this macro will allow wxWindows to create
 180 // the application object during program execution (it's better than using a
 181 // static object for many reasons) and also declares the accessor function
 182 // wxGetApp() which will return the reference of the right type (i.e. MyApp and
 183 // not wxApp)
 184 IMPLEMENT_APP(MyApp)
 185
 186 // ============================================================================
 187 // implementation
 188 // ============================================================================
 189
 190 // ----------------------------------------------------------------------------
 191 // the application class
 192 // ----------------------------------------------------------------------------
 193
 194 // `Main program' equivalent: the program execution "starts" here
 195 bool MyApp::OnInit()
 196 {
 197 #if wxUSE_HTML
 198 #if wxUSE_GIF
 199     // Required for images in the online documentation
 200     wxImage::AddHandler(new wxGIFHandler);
 201
 202     // Required for advanced HTML help
 203 #if wxUSE_STREAMS && wxUSE_ZIPSTREAM && wxUSE_ZLIB
 204       wxFileSystem::AddHandler(new wxZipFSHandler);
 205 #endif
 206
 207 #endif
 208 #endif
 209
 210     // Create the main application window
 211     MyFrame *frame = new MyFrame("HelpDemo wxWindows App",
 212                                  wxPoint(50, 50), wxSize(450, 340));
 213
 214     frame->Show(TRUE);
 215     SetTopWindow(frame);
 216
 217     // initialise the help system: this means that we'll use doc.hlp file under
 218     // Windows and that the HTML docs are in the subdirectory doc for platforms
 219     // using HTML help
 220     if ( !frame->GetHelpController().Initialize("doc") )
 221     {
 222         wxLogError("Cannot initialize the help system, aborting.");
 223
 224         return FALSE;
 225     }
 226
 227 #if USE_HTML_HELP
 228     // initialise the standard HTML help system: this means that the HTML docs are in the
 229     // subdirectory doc for platforms using HTML help
 230     if ( !frame->GetHtmlHelpController().Initialize("doc") )
 231     {
 232         wxLogError("Cannot initialize the HTML help system, aborting.");
 233
 234         return FALSE;
 235     }
 236
 237     // initialise the advanced HTML help system: this means that the HTML docs are in .htb
 238     // (zipped) form
 239     if ( !frame->GetAdvancedHtmlHelpController().Initialize("doc") )
 240     {
 241         wxLogError("Cannot initialize the advanced HTML help system, aborting.");
 242
 243         return FALSE;
 244     }
 245 #endif
 246
 247     return TRUE;
 248 }
 249
 250 // ----------------------------------------------------------------------------
 251 // main frame
 252 // ----------------------------------------------------------------------------
 253
 254 // frame constructor
 255 MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
 256        : wxFrame((wxFrame *)NULL, -1, title, pos, size)
 257 {
 258     // set the frame icon
 259     SetIcon(wxICON(mondrian));
 260
 261     // create a menu bar
 262     wxMenu *menuFile = new wxMenu;
 263
 264     menuFile->Append(HelpDemo_Help_Index, "&Help Index...");
 265     menuFile->Append(HelpDemo_Help_Classes, "&Help on Classes...");
 266     menuFile->Append(HelpDemo_Help_Functions, "&Help on Functions...");
 267     menuFile->Append(HelpDemo_Help_Help, "&About Help Demo...");
 268     menuFile->Append(HelpDemo_Help_Search, "&Search help...");
 269 #if USE_HTML_HELP
 270     menuFile->AppendSeparator();
 271     menuFile->Append(HelpDemo_Html_Help_Index, "HTML &Help Index...");
 272     menuFile->Append(HelpDemo_Html_Help_Classes, "HTML &Help on Classes...");
 273     menuFile->Append(HelpDemo_Html_Help_Functions, "HTML &Help on Functions...");
 274     menuFile->Append(HelpDemo_Html_Help_Help, "HTML &About Help Demo...");
 275     menuFile->Append(HelpDemo_Html_Help_Search, "HTML &Search help...");
 276     menuFile->AppendSeparator();
 277     menuFile->Append(HelpDemo_Advanced_Html_Help_Index, "Advanced HTML &Help Index...");
 278     menuFile->Append(HelpDemo_Advanced_Html_Help_Classes, "Advanced HTML &Help on Classes...");
 279     menuFile->Append(HelpDemo_Advanced_Html_Help_Functions, "Advanced HTML &Help on Functions...");
 280     menuFile->Append(HelpDemo_Advanced_Html_Help_Help, "Advanced HTML &About Help Demo...");
 281     menuFile->Append(HelpDemo_Advanced_Html_Help_Search, "Advanced HTML &Search help...");
 282 #endif
 283
 284 #ifndef __WXMSW__
 285 #if !wxUSE_HTML
 286     menuFile->AppendSeparator();
 287     menuFile->Append(HelpDemo_Help_KDE, "Use &KDE");
 288     menuFile->Append(HelpDemo_Help_GNOME, "Use &GNOME");
 289     menuFile->Append(HelpDemo_Help_Netscape, "Use &Netscape");
 290 #endif
 291 #endif
 292     menuFile->AppendSeparator();
 293     menuFile->Append(HelpDemo_Quit, "E&xit");
 294
 295     // now append the freshly created menu to the menu bar...
 296     wxMenuBar *menuBar = new wxMenuBar;
 297     menuBar->Append(menuFile, "&File");
 298
 299     // ... and attach this menu bar to the frame
 300     SetMenuBar(menuBar);
 301
 302     // create a status bar just for fun (by default with 1 pane only)
 303     CreateStatusBar();
 304     SetStatusText("Welcome to wxWindows!");
 305
 306     // now create some controls
 307
 308     // a panel first - if there were several controls, it would allow us to
 309     // navigate between them from the keyboard
 310     wxPanel *panel = new wxPanel(this, -1, wxPoint(0, 0), wxSize(400, 200));
 311
 312     // and a static control whose parent is the panel
 313     (void)new wxStaticText(panel, -1, "Hello, world!", wxPoint(10, 10));
 314 }
 315
 316
 317 // event handlers
 318
 319 void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
 320 {
 321     // TRUE is to force the frame to close
 322     Close(TRUE);
 323 }
 324
 325 void MyFrame::OnHelp(wxCommandEvent& event)
 326 {
 327    switch(event.GetId())
 328    {
 329
 330    // Note: For WinHelp, these ids are specified in the map session, mapping
 331    // topic names to numbers.
 332    // For HTML and external help, a wxhelp.map file is used.
 333
 334    case HelpDemo_Help_Classes:
 335       m_help.DisplaySection(2);
 336       break;
 337    case HelpDemo_Help_Functions:
 338       m_help.DisplaySection(1);
 339       break;
 340    case HelpDemo_Help_Help:
 341       m_help.DisplaySection(3);
 342       break;
 343
 344    // These three calls are only used by wxExtHelpController
 345
 346    case HelpDemo_Help_KDE:
 347       m_help.SetViewer("kdehelp");
 348       break;
 349    case HelpDemo_Help_GNOME:
 350       m_help.SetViewer("gnome-help-browser");
 351       break;
 352    case HelpDemo_Help_Netscape:
 353       m_help.SetViewer("netscape", wxHELP_NETSCAPE);
 354       break;
 355
 356    case HelpDemo_Help_Search:
 357    {
 358       wxString key = wxGetTextFromUser("Search for?",
 359                                        "Search help for keyword",
 360                                        "",
 361                                        this);
 362       if(! key.IsEmpty())
 363          m_help.KeywordSearch(key);
 364    }
 365    break;
 366    case HelpDemo_Help_Index:
 367    default:
 368       m_help.DisplayContents();
 369       break;
 370    }
 371 }
 372
 373 void MyFrame::OnHtmlHelp(wxCommandEvent& event)
 374 {
 375 #if USE_HTML_HELP
 376    switch(event.GetId())
 377    {
 378
 379    case HelpDemo_Html_Help_Classes:
 380       m_htmlHelp.DisplaySection(2);
 381       break;
 382    case HelpDemo_Html_Help_Functions:
 383       m_htmlHelp.DisplaySection(1);
 384       break;
 385    case HelpDemo_Html_Help_Help:
 386       m_htmlHelp.DisplaySection(3);
 387       break;
 388
 389    case HelpDemo_Html_Help_Search:
 390    {
 391       wxString key = wxGetTextFromUser("Search for?",
 392                                        "Search help for keyword",
 393                                        "",
 394                                        this);
 395       if(! key.IsEmpty())
 396          m_htmlHelp.KeywordSearch(key);
 397    }
 398    break;
 399    case HelpDemo_Html_Help_Index:
 400    default:
 401       m_htmlHelp.DisplayContents();
 402       break;
 403    }
 404 #endif
 405 }
 406
 407 void MyFrame::OnAdvancedHtmlHelp(wxCommandEvent& event)
 408 {
 409 #if USE_HTML_HELP
 410    switch(event.GetId())
 411    {
 412
 413    case HelpDemo_Advanced_Html_Help_Classes:
 414       m_advancedHtmlHelp.DisplaySection(2);
 415 //      m_advancedHtmlHelp.Display("Classes"); // An alternative form
 416       break;
 417    case HelpDemo_Advanced_Html_Help_Functions:
 418       m_advancedHtmlHelp.DisplaySection(1);
 419 //      m_advancedHtmlHelp.Display("Functions"); // An alternative form
 420       break;
 421    case HelpDemo_Advanced_Html_Help_Help:
 422       m_advancedHtmlHelp.DisplaySection(3);
 423 //      m_advancedHtmlHelp.Display("About"); // An alternative form
 424       break;
 425
 426    case HelpDemo_Advanced_Html_Help_Search:
 427    {
 428       wxString key = wxGetTextFromUser("Search for?",
 429                                        "Search help for keyword",
 430                                        "",
 431                                        this);
 432       if(! key.IsEmpty())
 433          m_advancedHtmlHelp.KeywordSearch(key);
 434    }
 435    break;
 436    case HelpDemo_Advanced_Html_Help_Index:
 437    default:
 438       m_advancedHtmlHelp.DisplayContents();
 439       break;
 440    }
 441 #endif
 442 }
 443