Added WinHelp sample doc to samples/help, and made it possible to show

both native and wxHTML help


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@6522 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

samples/help/demo.cpp

@@ -30,13 +30,22 @@
 #   include "wx/wx.h"
 #endif
 
-// define this to 1 to use HTML help even under Windows (by default, Windows
-// version will HLP-based help)
-#define USE_HTML_HELP 1
-#if USE_HTML_HELP
-#   include "wx/helpbase.h"
-#else
+#   include "wx/image.h"
 #   include "wx/help.h"
+
+// define this to 1 to use HTML help even under Windows (by default, Windows
+// version will use WinHelp).
+// Please also see samples/html/helpview for a more complex help viewer.
+
+#define USE_HTML_HELP 1
+
+#if !wxUSE_HTML
+#undef USE_HTML_HELP
+#define USE_HTML_HELP 0
+#endif
+
+#if USE_HTML_HELP
+#   include "wx/generic/helpwxht.h"
 #endif
 
 // ----------------------------------------------------------------------------
@@ -73,12 +82,21 @@ public:
 
     wxHelpController& GetHelpController() { return m_help; }
 
+#if USE_HTML_HELP
+    wxHelpControllerHtml& GetHtmlHelpController() { return m_htmlHelp; }
+#endif
+
     // event handlers (these functions should _not_ be virtual)
     void OnQuit(wxCommandEvent& event);
     void OnHelp(wxCommandEvent& event);
+    void OnHtmlHelp(wxCommandEvent& event);
 
 private:
-   wxHelpController m_help;
+   wxHelpController         m_help;
+
+#if USE_HTML_HELP
+   wxHelpControllerHtml     m_htmlHelp;
+#endif
 
     // any class wishing to process wxWindows events must use this macro
    DECLARE_EVENT_TABLE()
@@ -97,10 +115,17 @@ enum
     HelpDemo_Help_Classes,
     HelpDemo_Help_Functions,
     HelpDemo_Help_Help,
+    HelpDemo_Help_Search,
+
+    HelpDemo_Html_Help_Index,
+    HelpDemo_Html_Help_Classes,
+    HelpDemo_Html_Help_Functions,
+    HelpDemo_Html_Help_Help,
+    HelpDemo_Html_Help_Search,
+
     HelpDemo_Help_KDE,
     HelpDemo_Help_GNOME,
     HelpDemo_Help_Netscape,
-    HelpDemo_Help_Search,
     // controls start here (the numbers are, of course, arbitrary)
     HelpDemo_Text = 1000,
 };
@@ -118,10 +143,17 @@ BEGIN_EVENT_TABLE(MyFrame, wxFrame)
     EVT_MENU(HelpDemo_Help_Classes, MyFrame::OnHelp)
     EVT_MENU(HelpDemo_Help_Functions, MyFrame::OnHelp)
     EVT_MENU(HelpDemo_Help_Help, MyFrame::OnHelp)
+    EVT_MENU(HelpDemo_Help_Search, MyFrame::OnHelp)
+
+    EVT_MENU(HelpDemo_Html_Help_Index, MyFrame::OnHtmlHelp)
+    EVT_MENU(HelpDemo_Html_Help_Classes, MyFrame::OnHtmlHelp)
+    EVT_MENU(HelpDemo_Html_Help_Functions, MyFrame::OnHtmlHelp)
+    EVT_MENU(HelpDemo_Html_Help_Help, MyFrame::OnHtmlHelp)
+    EVT_MENU(HelpDemo_Html_Help_Search, MyFrame::OnHtmlHelp)
+
     EVT_MENU(HelpDemo_Help_KDE, MyFrame::OnHelp)
     EVT_MENU(HelpDemo_Help_GNOME, MyFrame::OnHelp)
     EVT_MENU(HelpDemo_Help_Netscape, MyFrame::OnHelp)
-    EVT_MENU(HelpDemo_Help_Search, MyFrame::OnHelp)
 END_EVENT_TABLE()
 
 // Create a new application object: this macro will allow wxWindows to create
@@ -142,6 +174,13 @@ IMPLEMENT_APP(MyApp)
 // `Main program' equivalent: the program execution "starts" here
 bool MyApp::OnInit()
 {
+#if wxUSE_HTML
+#if wxUSE_GIF
+    // Required for images in the online documentation
+    wxImage::AddHandler(new wxGIFHandler);
+#endif
+#endif
+
     // Create the main application window
     MyFrame *frame = new MyFrame("HelpDemo wxWindows App",
                                  wxPoint(50, 50), wxSize(450, 340));
@@ -149,7 +188,6 @@ bool MyApp::OnInit()
     frame->Show(TRUE);
     SetTopWindow(frame);
 
-
     // initialise the help system: this means that we'll use doc.hlp file under
     // Windows and that the HTML docs are in the subdirectory doc for platforms
     // using HTML help
@@ -160,6 +198,17 @@ bool MyApp::OnInit()
         return FALSE;
     }
 
+#if USE_HTML_HELP
+    // initialise the help system: this means that the HTML docs are in the
+    // subdirectory doc for platforms using HTML help
+    if ( !frame->GetHtmlHelpController().Initialize("doc") )
+    {
+        wxLogError("Cannot initialize the HTML help system, aborting.");
+
+        return FALSE;
+    }
+#endif
+
     return TRUE;
 }
 
@@ -183,6 +232,16 @@ MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
     menuFile->Append(HelpDemo_Help_Help, "&About Help Demo...");
     menuFile->AppendSeparator();
     menuFile->Append(HelpDemo_Help_Search, "&Search help...");
+#if USE_HTML_HELP
+    menuFile->AppendSeparator();
+    menuFile->Append(HelpDemo_Html_Help_Index, "HTML &Help Index...");
+    menuFile->Append(HelpDemo_Html_Help_Classes, "HTML &Help on Classes...");
+    menuFile->Append(HelpDemo_Html_Help_Functions, "HTML &Help on Functions...");
+    menuFile->Append(HelpDemo_Html_Help_Help, "HTML &About Help Demo...");
+    menuFile->AppendSeparator();
+    menuFile->Append(HelpDemo_Html_Help_Search, "HTML &Search help...");
+#endif
+
 #ifndef __WXMSW__
 #if !wxUSE_HTML
     menuFile->AppendSeparator();
@@ -229,14 +288,15 @@ void MyFrame::OnHelp(wxCommandEvent& event)
    switch(event.GetId())
    {
 
-   // Note: these DisplaySection calls use ids that are specific to wxExtHelpController
-   // (on Unix). For WinHelp, we'd need to use different context ids.
+   // Note: For WinHelp, these ids are specified in the map session, mapping
+   // topic names to numbers.
+   // For HTML and external help, a wxhelp.map file is used.
 
    case HelpDemo_Help_Classes:
-      m_help.DisplaySection(1);
+      m_help.DisplaySection(2);
       break;
    case HelpDemo_Help_Functions:
-      m_help.DisplaySection(2);
+      m_help.DisplaySection(1);
       break;
    case HelpDemo_Help_Help:
       m_help.DisplaySection(3);
@@ -271,3 +331,37 @@ void MyFrame::OnHelp(wxCommandEvent& event)
    }
 }
 
+void MyFrame::OnHtmlHelp(wxCommandEvent& event)
+{
+#if USE_HTML_HELP
+   switch(event.GetId())
+   {
+
+   case HelpDemo_Html_Help_Classes:
+      m_htmlHelp.DisplaySection(2);
+      break;
+   case HelpDemo_Html_Help_Functions:
+      m_htmlHelp.DisplaySection(1);
+      break;
+   case HelpDemo_Html_Help_Help:
+      m_htmlHelp.DisplaySection(3);
+      break;
+
+   case HelpDemo_Html_Help_Search:
+   {
+      wxString key = wxGetTextFromUser("Search for?",
+                                       "Search help for keyword",
+                                       "",
+                                       this);
+      if(! key.IsEmpty())
+         m_htmlHelp.KeywordSearch(key);
+   }
+   break;
+   case HelpDemo_Html_Help_Index:
+   default:
+      m_htmlHelp.DisplayContents();
+      break;
+   }
+#endif
+}
+

samples/help/doc.cnt

@@ -0,0 +1,8 @@
+:Base doc.hlp
+1 Introduction
+2 Introduction=intro
+2 Classes=classes
+2 Functions=functions
+2 About=about
+1 Chapter 2
+2 Chapter 2=chapter2

samples/help/doc.hpj

@@ -0,0 +1,21 @@
+[OPTIONS]
+BMROOT=D:\wx2\wxWind~1\samples\help
+TITLE=Help Demo Document
+CONTENTS=Contents
+COMPRESS=HIGH
+
+[FILES]
+doc.rtf
+
+[CONFIG]
+CreateButton("Up", "&Up", "JumpId(`doc.hlp', `Contents')")
+BrowseButtons()
+
+[MAP]
+#define intro       100
+#define functions   1
+#define classes     2
+#define about       3
+
+[BITMAPS]
+

samples/help/doc.tex

@@ -0,0 +1,59 @@
+\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}%
+\parskip=10pt%
+\parindent=0pt%
+\title{Help Demo}%
+\author{by Julian Smart}%
+\makeindex%
+\begin{document}%
+\maketitle%
+\pagestyle{fancyplain}%
+\bibliographystyle{plain}%
+\pagenumbering{roman}%
+\setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+\tableofcontents%
+
+\chapter{Introduction}\label{intro}
+\pagenumbering{arabic}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+This is a demo document for the wxWindows 'help' sample.
+
+You should process this file with Tex2RTF, for example:
+
+{\tt tex2rtf -winhelp -twice doc.tex doc.hlp}
+
+and then run:
+
+{\tt hc doc}
+
+where hc is the help compiler.
+
+Note that you can also generate HTML and Word RTF with Tex2RTF.
+
+\section{Classes}\label{classes}
+
+This would say something about classes, but doesn't yet.
+
+\section{Functions}\label{functions}
+
+This would say something about functions, but doesn't yet.
+
+\section{About}\label{about}
+
+About this HelpDemo: this file is really not much of a demo, but it's a start.
+
+\chapter{Chapter 2}\label{chapter2}
+\pagenumbering{arabic}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+Another chapter in this enticing little manual.
+
+\addcontentsline{toc}{chapter}{Index}
+\setheader{{\it INDEX}}{}{}{}{}{{\it INDEX}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+\printindex%
+
+\end{document}

samples/help/doc/wxhelp.map

@@ -5,6 +5,6 @@
 ; First, some wxWindows documentation files:
 ;
 0 wx.htm             ; wxWindows: Help index; additional keywords like overview
-1 wx204.htm          ; wxWindows Class References
-2 wx34.htm           ; wxWindows Function References; methods
-3 aindex.html
+1 wx204.htm          ; wxWindows Function Reference
+2 wx34.htm           ; wxWindows Class Reference
+3 aindex.html        ; 

samples/help/tex2rtf.ini

@@ -0,0 +1,21 @@
+; Tex2RTF initialisation file
+runTwice = yes
+titleFontSize = 12
+authorFontSize = 10
+chapterFontSize = 12
+sectionFontSize = 12
+subsectionFontSize = 12
+headerRule = yes
+footerRule = yes
+useHeadingStyles = yes
+contentsDepth = 2
+listItemIndent=40
+winHelpContents = yes
+winHelpVersion = 3 ; 3 for Windows 3.x, 4 for Windows 95
+generateHPJ = no
+htmlBrowseButtons = bitmap
+winHelpTitle = "Help Demo Document"
+truncateFilenames = yes
+combineSubSections = yes
+htmlIndex = yes
+htmlFrameContents = no