utils/wxPython/modules/html/htmlhelp.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        htmlhelp.i
   3 // Purpose:     SWIG definitions of html classes
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     25-nov-1998
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 1998 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13
  14 %module htmlhelp
  15
  16 %{
  17 #include "helpers.h"
  18 #include <wx/html/htmlwin.h>
  19 #include <wx/image.h>
  20 #include <wx/fs_zip.h>
  21 #include <wx/fs_inet.h>
  22 #include <wx/wfstream.h>
  23 #include "helpsys.h"
  24 %}
  25
  26 //---------------------------------------------------------------------------
  27
  28 %include typemaps.i
  29 %include my_typemaps.i
  30
  31 %extern wx.i
  32 %extern windows.i
  33 %extern _defs.i
  34 %extern events.i
  35 %extern controls.i
  36 %extern controls2.i
  37
  38 %extern utils.i
  39
  40 %extern html.i
  41
  42 //---------------------------------------------------------------------------
  43
  44 enum {
  45     wxID_HTML_PANEL,
  46     wxID_HTML_BACK,
  47     wxID_HTML_FORWARD,
  48     wxID_HTML_TREECTRL,
  49     wxID_HTML_INDEXPAGE,
  50     wxID_HTML_INDEXLIST,
  51     wxID_HTML_NOTEBOOK,
  52     wxID_HTML_SEARCHPAGE,
  53     wxID_HTML_SEARCHTEXT,
  54     wxID_HTML_SEARCHLIST,
  55     wxID_HTML_SEARCHBUTTON
  56 };
  57
  58 class wxHtmlHelpController : public wxEvtHandler {
  59 public:
  60     wxHtmlHelpController();
  61     ~wxHtmlHelpController();
  62
  63     // Images:
  64     enum {
  65         IMG_Book = 0,
  66         IMG_Folder,
  67         IMG_Page
  68     };
  69
  70     void SetTitleFormat(const wxString& format) {m_TitleFormat = format;}
  71                 // Sets format of title of the frame. Must contain exactly one "%s"
  72                 // (for title of displayed HTML page)
  73
  74     void SetTempDir(const wxString& path);
  75                 // Sets directory where temporary files are stored.
  76                 // These temp files are index & contents file in binary (much faster to read)
  77                 // form. These files are NOT deleted on program's exit.
  78
  79     bool AddBook(const wxString& book, bool show_wait_msg = FALSE);
  80                 // Adds new book. 'book' is location of .htb file (stands for "html book").
  81                 // See documentation for details on its format.
  82                 // Returns success.
  83                 // If show_wait_msg == true then message window with "loading book..." is displayed
  84
  85     void Display(const wxString& x);
  86                 // Displays page x. If not found it will offect the user a choice of searching
  87                 // books.
  88                 // Looking for the page runs in these steps:
  89                 // 1. try to locate file named x (if x is for example "doc/howto.htm")
  90                 // 2. try to open starting page of book x
  91                 // 3. try to find x in contents (if x is for example "How To ...")
  92                 // 4. try to find x in index (if x is for example "How To ...")
  93                 // 5. offer searching and if the user agree, run KeywordSearch
  94     %name(DisplayID) void Display(const int id);
  95                 // Alternative version that works with numeric ID.
  96                 // (uses extension to MS format, <param name="ID" value=id>, see docs)
  97
  98     void DisplayContents();
  99                 // Displays help window and focuses contents.
 100
 101     void DisplayIndex();
 102                 // Displays help window and focuses index.
 103
 104     bool KeywordSearch(const wxString& keyword);
 105                 // Searches for keyword. Returns TRUE and display page if found, return
 106                 // FALSE otherwise
 107                 // Syntax of keyword is Altavista-like:
 108                 // * words are separated by spaces
 109                 //   (but "\"hello world\"" is only one world "hello world")
 110                 // * word may be pretended by + or -
 111                 //   (+ : page must contain the word ; - : page can't contain the word)
 112                 // * if there is no + or - before the word, + is default
 113
 114     void UseConfig(wxConfigBase *config, const wxString& rootpath = wxEmptyString);
 115                 // Assigns config object to the controller. This config is then
 116                 // used in subsequent calls to Read/WriteCustomization of both help
 117                 // controller and it's wxHtmlWindow
 118
 119     void ReadCustomization(wxConfigBase *cfg, wxString path = wxEmptyString);
 120                 // saves custom settings into cfg config. it will use the path 'path'
 121                 // if given, otherwise it will save info into currently selected path.
 122                 // saved values : things set by SetFonts, SetBorders.
 123     void WriteCustomization(wxConfigBase *cfg, wxString path = wxEmptyString);
 124                 // ...
 125 };
 126
 127 class wxHtmlHelpSystem : public wxHtmlHelpController {
 128 public:
 129     wxHtmlHelpSystem() {};
 130     ~wxHtmlHelpSystem() {};
 131
 132     bool AddBookParam(const wxString& title, const wxString& contfile,
 133                       const wxString& indexfile=wxEmptyString, const wxString& deftopic=wxEmptyString,
 134                       const wxString& path=wxEmptyString, bool show_wait_msg=FALSE);
 135     // Alternative to AddBook(wxString& hhpfile)
 136     wxToolBar* CreateToolBar(wxFrame* frame);
 137     // creates a dockable toolbar for the frame, containing hide/show, back and forward buttons
 138     wxTreeCtrl* CreateContentsTree(wxWindow* parent);
 139     // creates a treecontrol with imagelist for books, folders etc and id wxID_HTML_TREECTRL
 140     wxListBox* CreateIndexList(wxWindow* parent);
 141     // creates a listbox with the right id
 142     virtual void CreateHelpWindow();
 143     // Slightly different version than in wxHtmlHelpController; uses helpers above
 144     // Do nothing if the window already exists
 145     void SetControls(wxFrame* frame, wxHtmlWindow* htmlwin,
 146                      wxTreeCtrl* contents=NULL, wxListBox* index=NULL,
 147                      wxListBox* searchlist=NULL);
 148     // alternative for CreateHelpWindow(), sets frame, htmlwindow, contents tree, index
 149     // listbox and searchlist listbox. If null, their functionality won't be used
 150
 151     // Some extra accessor functions
 152     wxFrame* GetFrame() { return m_Frame; }
 153     wxHtmlWindow* GetHtmlWindow() { return m_HtmlWin; }
 154     wxTreeCtrl* GetContentsTree() { return m_ContentsBox; }
 155     wxListBox* GetIndexList() { return m_IndexBox; }
 156     wxListBox* GetSearchList() { return m_SearchList; }
 157     wxImageList* GetContentsImageList() { return m_ContentsImageList; }
 158     // public interface for wxHtmlHelpControllers handlers, so wxPython can call them
 159     void OnToolbar(wxCommandEvent& event);
 160     void OnContentsSel(wxTreeEvent& event) {wxHtmlHelpController::OnContentsSel(event);}
 161     void OnIndexSel(wxCommandEvent& event) {wxHtmlHelpController::OnIndexSel(event);}
 162     void OnSearchSel(wxCommandEvent& event) {wxHtmlHelpController::OnSearchSel(event);}
 163     void OnSearch(wxCommandEvent& event) {wxHtmlHelpController::OnSearch(event);}
 164     void OnCloseWindow(wxCloseEvent& event);
 165
 166     // some more protected functions that should be accessible from wxPython
 167     void RefreshLists();
 168     void CreateContents() { if (!m_IndexBox) return; wxHtmlHelpController::CreateContents(); }
 169     // Adds items to m_Contents tree control
 170     void CreateIndex() { if (! m_ContentsBox) return; wxHtmlHelpController::CreateIndex(); }
 171     // Adds items to m_IndexList
 172 };
 173
 174 // just for fun, an Altavista-like search engine (the gems that Vaclav has hidden in wxHtml...)
 175 // but not for wxMSW because it's not DLL exported
 176 //#ifndef __WXMSW__
 177 #ifdef THIS_IS_NOT_DEFINED_OKAY
 178 class wxSearchEngine
 179 {
 180     public:
 181         wxSearchEngine() : wxObject() {m_Keyword = NULL;}
 182         ~wxSearchEngine() {if (m_Keyword) free(m_Keyword);}
 183
 184         void LookFor(const wxString& keyword);
 185             // Sets the keyword we will be searching for
 186
 187         bool Scan(wxInputStream *stream);
 188             // Scans the stream for the keyword.
 189             // Returns TRUE if the stream contains keyword, fALSE otherwise
 190         %addmethods {
 191                 bool ScanFile(const wxString& filename) {
 192                         if (filename.IsEmpty())
 193                                 return false;
 194                         wxFileInputStream istr(filename);
 195                         return self->Scan(&istr);
 196                 }
 197         }
 198 };
 199 #endif
 200
 201 //---------------------------------------------------------------------------