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 // Helper constants
  71 //-----------------------------------------------------------------------------
  72
  73
  74 // Command IDs :
  75
  76 enum {
  77     wxID_HTML_PANEL = wxID_HIGHEST + 1,
  78     wxID_HTML_BACK,
  79     wxID_HTML_FORWARD,
  80     wxID_HTML_TREECTRL,
  81     wxID_HTML_INDEXPAGE,
  82     wxID_HTML_INDEXLIST,
  83     wxID_HTML_NOTEBOOK,
  84     wxID_HTML_SEARCHPAGE,
  85     wxID_HTML_SEARCHTEXT,
  86     wxID_HTML_SEARCHLIST,
  87     wxID_HTML_SEARCHBUTTON
  88 };
  89
  90
  91 //--------------------------------------------------------------------------------
  92 // HtmlHelpTreeItemData
  93 //                  Stores the location of a contents item in a tree item
  94 //--------------------------------------------------------------------------------
  95
  96 class wxHtmlHelpTreeItemData : public wxTreeItemData
  97 {
  98     private:
  99         wxString m_Page;
 100
 101     public:
 102         wxHtmlHelpTreeItemData(HtmlContentsItem *it) : wxTreeItemData() {m_Page = it -> m_Book -> GetBasePath() + it -> m_Page;}
 103         const wxString& GetPage() {return m_Page;}
 104 };
 105
 106
 107 //--------------------------------------------------------------------------------
 108 // wxHtmlHelpController
 109 //                  This class ensures dislaying help.
 110 //                  See documentation for details on its philosophy.
 111 //
 112 //                  WARNING!!
 113 //                  This class is not derived from wxHelpController and is not
 114 //                  compatible with it!
 115 //--------------------------------------------------------------------------------
 116
 117
 118 class WXDLLEXPORT wxHtmlHelpController : public wxEvtHandler
 119 {
 120     DECLARE_DYNAMIC_CLASS(wxHtmlHelpController)
 121
 122     protected:
 123         wxConfigBase *m_Config;
 124         wxString m_ConfigRoot;
 125                 // configuration file/registry used to store custom settings
 126         wxString m_TitleFormat;
 127                 // title of the help frame
 128         wxString m_TempPath;
 129
 130         wxFrame *m_Frame;
 131         wxHtmlWindow *m_HtmlWin;
 132         wxSplitterWindow *m_Splitter;
 133         wxNotebook *m_NavigPan;
 134         wxTreeCtrl *m_ContentsBox;
 135         wxImageList *m_ContentsImageList;
 136         wxListBox *m_IndexBox;
 137         wxTextCtrl *m_SearchText;
 138         wxButton *m_SearchButton;
 139         wxListBox *m_SearchList;
 140                 // ...pointers to parts of help window
 141
 142         struct {
 143             long x, y, w, h;
 144             long sashpos;
 145             bool navig_on;
 146         } m_Cfg;
 147                 // settings (window size, position, sash pos etc..)
 148
 149         HtmlBookRecArray m_BookRecords;
 150                 // each book has one record in this array
 151         HtmlContentsItem* m_Contents;
 152         int m_ContentsCnt;
 153                 // list of all available books and pages.
 154         HtmlContentsItem* m_Index;
 155         int m_IndexCnt;
 156                 // list of index items
 157
 158     public:
 159         wxHtmlHelpController();
 160         ~wxHtmlHelpController();
 161
 162         // Images:
 163         enum {
 164             IMG_Book = 0,
 165             IMG_Folder,
 166             IMG_Page
 167         };
 168
 169         void SetTitleFormat(const wxString& format) {m_TitleFormat = format;}
 170                 // Sets format of title of the frame. Must contain exactly one "%s"
 171                 // (for title of displayed HTML page)
 172
 173         void SetTempDir(const wxString& path);
 174                 // Sets directory where temporary files are stored.
 175                 // These temp files are index & contents file in binary (much faster to read)
 176                 // form. These files are NOT deleted on program's exit.
 177
 178         bool AddBook(const wxString& book, bool show_wait_msg = FALSE);
 179                 // Adds new book. 'book' is location of .htb file (stands for "html book").
 180                 // See documentation for details on its format.
 181                 // Returns success.
 182                 // If show_wait_msg == true then message window with "loading book..." is displayed
 183
 184         void Display(const wxString& x);
 185                 // Displays page x. If not found it will offect the user a choice of searching
 186                 // books.
 187                 // Looking for the page runs in these steps:
 188                 // 1. try to locate file named x (if x is for example "doc/howto.htm")
 189                 // 2. try to open starting page of book x
 190                 // 3. try to find x in contents (if x is for example "How To ...")
 191                 // 4. try to find x in index (if x is for example "How To ...")
 192                 // 5. offer searching and if the user agree, run KeywordSearch
 193         void Display(const int id);
 194                 // Alternative version that works with numeric ID.
 195                 // (uses extension to MS format, <param name="ID" value=id>, see docs)
 196
 197         void DisplayContents();
 198                 // Displays help window and focuses contents.
 199
 200         void DisplayIndex();
 201                 // Displays help window and focuses index.
 202
 203         bool KeywordSearch(const wxString& keyword);
 204                 // Searches for keyword. Returns TRUE and display page if found, return
 205                 // FALSE otherwise
 206                 // Syntax of keyword is Altavista-like:
 207                 // * words are separated by spaces
 208                 //   (but "\"hello world\"" is only one world "hello world")
 209                 // * word may be pretended by + or -
 210                 //   (+ : page must contain the word ; - : page can't contain the word)
 211                 // * if there is no + or - before the word, + is default
 212
 213         void UseConfig(wxConfigBase *config, const wxString& rootpath = wxEmptyString) {m_Config = config; m_ConfigRoot = rootpath;}
 214                 // Assigns config object to the controller. This config is then
 215                 // used in subsequent calls to Read/WriteCustomization of both help
 216                 // controller and it's wxHtmlWindow
 217
 218         void ReadCustomization(wxConfigBase *cfg, wxString path = wxEmptyString);
 219                 // saves custom settings into cfg config. it will use the path 'path'
 220                 // if given, otherwise it will save info into currently selected path.
 221                 // saved values : things set by SetFonts, SetBorders.
 222         void WriteCustomization(wxConfigBase *cfg, wxString path = wxEmptyString);
 223                 // ...
 224
 225     protected:
 226         virtual void CreateHelpWindow();
 227                 // Creates frame & html window and sets m_Frame and other variables;
 228                 // Do nothing if the window already exists
 229         void RefreshLists();
 230                 // Refreshes Contents and Index tabs
 231         void CreateContents();
 232                 // Adds items to m_Contents tree control
 233         void CreateIndex();
 234                 // Adds items to m_IndexList
 235
 236         void LoadMSProject(HtmlBookRecord *book, wxFileSystem& fsys, const wxString& indexfile, const wxString& contentsfile, bool show_wait_msg);
 237                 // Imports .hhp files (MS HTML Help Workshop)
 238         void LoadCachedBook(HtmlBookRecord *book, wxInputStream *f);
 239                 // Reads binary book
 240         void SaveCachedBook(HtmlBookRecord *book, wxOutputStream *f);
 241                 // Writes binary book
 242
 243         void OnToolbar(wxCommandEvent& event);
 244         void OnContentsSel(wxTreeEvent& event);
 245         void OnIndexSel(wxCommandEvent& event);
 246         void OnSearchSel(wxCommandEvent& event);
 247         void OnSearch(wxCommandEvent& event);
 248         void OnCloseWindow(wxCloseEvent& event);
 249
 250     DECLARE_EVENT_TABLE()
 251 };
 252
 253
 254
 255 #endif // __HTMLHELP_H__
 256
 257 #endif
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267