include/wx/html/htmlhelp.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        htmlhelp.h
   3 // Purpose:     Help controller
   4 // Author:      Vaclav Slavik
   5 // Copyright:   (c) 1999 Vaclav Slavik
   6 // Licence:     wxWindows Licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 #ifndef __HTMLHELP_H__
  11 #define __HTMLHELP_H__
  12
  13 #ifdef __GNUG__
  14 #pragma interface
  15 #endif
  16
  17 #include "wx/defs.h"
  18 #if wxUSE_HTML
  19
  20 #include <wx/window.h>
  21 #include <wx/config.h>
  22 #include <wx/splitter.h>
  23 #include <wx/notebook.h>
  24 #include <wx/listctrl.h>
  25 #include <wx/html/htmlwin.h>
  26
  27
  28
  29 //--------------------------------------------------------------------------------
  30 // helper classes & structs - please ignore 'em
  31 //--------------------------------------------------------------------------------
  32
  33
  34
  35 class WXDLLEXPORT HtmlBookRecord : public wxObject
  36 {
  37     public:
  38         wxString m_BasePath;
  39         wxString m_Title;
  40         wxString m_Start;
  41
  42         HtmlBookRecord(const wxString& basepath, const wxString& title, const wxString& start) {m_BasePath = basepath; m_Title = title; m_Start = start;}
  43         wxString GetTitle() const {return m_Title;}
  44         wxString GetStart() const {return m_Start;}
  45         wxString GetBasePath() const {return m_BasePath;}
  46 };
  47
  48
  49 #undef WXDLLEXPORTLOCAL
  50 #define WXDLLEXPORTLOCAL WXDLLEXPORT
  51      // ?? Don't know why - but Allen Van Sickel reported it to fix problems with DLL
  52 WX_DECLARE_OBJARRAY(HtmlBookRecord, HtmlBookRecArray);
  53
  54 #undef WXDLLEXPORTLOCAL
  55 #define WXDLLEXPORTLOCAL
  56
  57
  58 typedef struct
  59     {
  60         short int m_Level;
  61         int m_ID;
  62         char* m_Name;
  63         char* m_Page;
  64         HtmlBookRecord *m_Book;
  65     } HtmlContentsItem;
  66
  67
  68
  69
  70 //--------------------------------------------------------------------------------
  71 // wxHtmlHelpController
  72 //                  This class ensures dislaying help.
  73 //                  See documentation for details on its philosophy.
  74 //
  75 //                  WARNING!!
  76 //                  This class is not derived from wxHelpController and is not
  77 //                  compatible with it!
  78 //--------------------------------------------------------------------------------
  79
  80
  81 class WXDLLEXPORT wxHtmlHelpController : public wxEvtHandler
  82 {
  83     DECLARE_DYNAMIC_CLASS(wxHtmlHelpController)
  84
  85     protected:
  86         wxConfigBase *m_Config;
  87         wxString m_ConfigRoot;
  88                 // configuration file/registry used to store custom settings
  89         wxString m_TitleFormat;
  90                 // title of the help frame
  91         wxString m_TempPath;
  92
  93         wxFrame *m_Frame;
  94         wxHtmlWindow *m_HtmlWin;
  95         wxSplitterWindow *m_Splitter;
  96         wxNotebook *m_NavigPan;
  97         wxTreeCtrl *m_ContentsBox;
  98         wxImageList *m_ContentsImageList;
  99         wxListBox *m_IndexBox;
 100         wxTextCtrl *m_SearchText;
 101         wxButton *m_SearchButton;
 102         wxListBox *m_SearchList;
 103                 // ...pointers to parts of help window
 104
 105         struct {
 106             long x, y, w, h;
 107             long sashpos;
 108             bool navig_on;
 109         } m_Cfg;
 110                 // settings (window size, position, sash pos etc..)
 111
 112         HtmlBookRecArray m_BookRecords;
 113                 // each book has one record in this array
 114         HtmlContentsItem* m_Contents;
 115         int m_ContentsCnt;
 116                 // list of all available books and pages.
 117         HtmlContentsItem* m_Index;
 118         int m_IndexCnt;
 119                 // list of index items
 120
 121     public:
 122         wxHtmlHelpController();
 123         ~wxHtmlHelpController();
 124
 125         void SetTitleFormat(const wxString& format) {m_TitleFormat = format;}
 126                 // Sets format of title of the frame. Must contain exactly one "%s"
 127                 // (for title of displayed HTML page)
 128
 129         void SetTempDir(const wxString& path);
 130                 // Sets directory where temporary files are stored.
 131                 // These temp files are index & contents file in binary (much faster to read)
 132                 // form. These files are NOT deleted on program's exit.
 133
 134         bool AddBook(const wxString& book, bool show_wait_msg = FALSE);
 135                 // Adds new book. 'book' is location of .htb file (stands for "html book").
 136                 // See documentation for details on its format.
 137                 // Returns success.
 138                 // If show_wait_msg == true then message window with "loading book..." is displayed
 139
 140         void Display(const wxString& x);
 141                 // Displays page x. If not found it will offect the user a choice of searching
 142                 // books.
 143                 // Looking for the page runs in these steps:
 144                 // 1. try to locate file named x (if x is for example "doc/howto.htm")
 145                 // 2. try to open starting page of book x
 146                 // 3. try to find x in contents (if x is for example "How To ...")
 147                 // 4. try to find x in index (if x is for example "How To ...")
 148                 // 5. offer searching and if the user agree, run KeywordSearch
 149         void Display(const int id);
 150                 // Alternative version that works with numeric ID.
 151                 // (uses extension to MS format, <param name="ID" value=id>, see docs)
 152
 153         void DisplayContents();
 154                 // Displays help window and focuses contents.
 155
 156         void DisplayIndex();
 157                 // Displays help window and focuses index.
 158
 159         bool KeywordSearch(const wxString& keyword);
 160                 // Searches for keyword. Returns TRUE and display page if found, return
 161                 // FALSE otherwise
 162                 // Syntax of keyword is Altavista-like:
 163                 // * words are separated by spaces
 164                 //   (but "\"hello world\"" is only one world "hello world")
 165                 // * word may be pretended by + or -
 166                 //   (+ : page must contain the word ; - : page can't contain the word)
 167                 // * if there is no + or - before the word, + is default
 168
 169         void UseConfig(wxConfigBase *config, const wxString& rootpath = wxEmptyString) {m_Config = config; m_ConfigRoot = rootpath;}
 170                 // Assigns config object to the controller. This config is then
 171                 // used in subsequent calls to Read/WriteCustomization of both help
 172                 // controller and it's wxHtmlWindow
 173
 174         void ReadCustomization(wxConfigBase *cfg, wxString path = wxEmptyString);
 175                 // saves custom settings into cfg config. it will use the path 'path'
 176                 // if given, otherwise it will save info into currently selected path.
 177                 // saved values : things set by SetFonts, SetBorders.
 178         void WriteCustomization(wxConfigBase *cfg, wxString path = wxEmptyString);
 179                 // ...
 180
 181     protected:
 182         virtual void CreateHelpWindow();
 183                 // Creates frame & html window and sets m_Frame and other variables;
 184                 // Do nothing if the window already exists
 185         void RefreshLists();
 186                 // Refreshes Contents and Index tabs
 187         void CreateContents();
 188                 // Adds items to m_Contents tree control
 189         void CreateIndex();
 190                 // Adds items to m_IndexList
 191
 192         void LoadMSProject(HtmlBookRecord *book, wxFileSystem& fsys, const wxString& indexfile, const wxString& contentsfile, bool show_wait_msg);
 193                 // Imports .hhp files (MS HTML Help Workshop)
 194         void LoadCachedBook(HtmlBookRecord *book, wxInputStream *f);
 195                 // Reads binary book
 196         void SaveCachedBook(HtmlBookRecord *book, wxOutputStream *f);
 197                 // Writes binary book
 198
 199         void OnToolbar(wxCommandEvent& event);
 200         void OnContentsSel(wxTreeEvent& event);
 201         void OnIndexSel(wxCommandEvent& event);
 202         void OnSearchSel(wxCommandEvent& event);
 203         void OnSearch(wxCommandEvent& event);
 204         void OnCloseWindow(wxCloseEvent& event);
 205
 206     DECLARE_EVENT_TABLE()
 207 };
 208
 209
 210
 211 #endif // __HTMLHELP_H__
 212
 213 #endif
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223