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