1 /*-*- c++ -*-******************************************************** 2 * helpext.h - an external help controller for wxWidgets * 3 * * 4 * (C) 1998 by Karsten Ballueder (Ballueder@usa.net) * 5 * License: wxWindows licence * 6 * * 7 * $Id: helpext.h 50711 2007-12-15 02:57:58Z VZ $ 8 *******************************************************************/ 9 10 #ifndef __WX_HELPEXT_H_ 11 #define __WX_HELPEXT_H_ 12 13 #if wxUSE_HELP 14 15 #include "wx/helpbase.h" 16 17 /** 18 This class implements help via an external browser. 19 It requires the name of a directory containing the documentation 20 and a file mapping numerical Section numbers to relative URLS. 21 22 The map file contains two or three fields per line: 23 numeric_id relative_URL [; comment/documentation] 24 25 The numeric_id is the id used to look up the entry in 26 DisplaySection()/DisplayBlock(). The relative_URL is a filename of 27 an html file, relative to the help directory. The optional 28 comment/documentation field (after a ';') is used for keyword 29 searches, so some meaningful text here does not hurt. 30 If the documentation itself contains a ';', only the part before 31 that will be displayed in the listbox, but all of it used for search. 32 33 Lines starting with ';' will be ignored. 34 */ 35 36 class WXDLLIMPEXP_ADV wxExtHelpController : public wxHelpControllerBase 37 { 38 public: 39 wxExtHelpController(wxWindow* parentWindow = NULL); 40 virtual ~wxExtHelpController(); 41 42 /** Tell it which browser to use. 43 The Netscape support will check whether Netscape is already 44 running (by looking at the .netscape/lock file in the user's 45 home directory) and tell it to load the page into the existing 46 window. 47 @param browsername The command to call a browser/html viewer. 48 @param isNetscape Set this to true if the browser is some variant of Netscape. 49 */ 50 void SetBrowser(const wxString& browsername = wxEmptyString, 51 bool isNetscape = false); 52 53 // Set viewer: new name for SetBrowser 54 virtual void SetViewer(const wxString& viewer = wxEmptyString, 55 long flags = wxHELP_NETSCAPE); 56 57 /** This must be called to tell the controller where to find the 58 documentation. 59 If a locale is set, look in file/localename, i.e. 60 If passed "/usr/local/myapp/help" and the current wxLocale is 61 set to be "de", then look in "/usr/local/myapp/help/de/" 62 first and fall back to "/usr/local/myapp/help" if that 63 doesn't exist. 64 65 @param file - NOT a filename, but a directory name. 66 @return true on success 67 */ Initialize(const wxString & dir,int WXUNUSED (server))68 virtual bool Initialize(const wxString& dir, int WXUNUSED(server)) 69 { return Initialize(dir); } 70 71 /** This must be called to tell the controller where to find the 72 documentation. 73 If a locale is set, look in file/localename, i.e. 74 If passed "/usr/local/myapp/help" and the current wxLocale is 75 set to be "de", then look in "/usr/local/myapp/help/de/" 76 first and fall back to "/usr/local/myapp/help" if that 77 doesn't exist. 78 @param dir - directory name where to fine the help files 79 @return true on success 80 */ 81 virtual bool Initialize(const wxString& dir); 82 83 /** If file is "", reloads file given in Initialize. 84 @file Name of help directory. 85 @return true on success 86 */ 87 virtual bool LoadFile(const wxString& file = wxEmptyString); 88 89 /** Display list of all help entries. 90 @return true on success 91 */ 92 virtual bool DisplayContents(void); 93 /** Display help for id sectionNo. 94 @return true on success 95 */ 96 virtual bool DisplaySection(int sectionNo); 97 /** Display help for id sectionNo -- identical with DisplaySection(). 98 @return true on success 99 */ 100 virtual bool DisplaySection(const wxString& section); 101 /** Display help for URL (using DisplayHelp) or keyword (using KeywordSearch) 102 @return true on success 103 */ 104 virtual bool DisplayBlock(long blockNo); 105 /** Search comment/documentation fields in map file and present a 106 list to chose from. 107 @key k string to search for, empty string will list all entries 108 @return true on success 109 */ 110 virtual bool KeywordSearch(const wxString& k, 111 wxHelpSearchMode mode = wxHELP_SEARCH_ALL); 112 113 /// does nothing 114 virtual bool Quit(void); 115 /// does nothing 116 virtual void OnQuit(void); 117 118 /// Call the browser using a relative URL. 119 virtual bool DisplayHelp(const wxString &) ; 120 121 /// Allows one to override the default settings for the help frame. 122 virtual void SetFrameParameters(const wxString& WXUNUSED(title), 123 const wxSize& WXUNUSED(size), 124 const wxPoint& WXUNUSED(pos) = wxDefaultPosition, 125 bool WXUNUSED(newFrameEachTime) = false) 126 { 127 // does nothing by default 128 } 129 /// Obtains the latest settings used by the help frame and the help 130 /// frame. 131 virtual wxFrame *GetFrameParameters(wxSize *WXUNUSED(size) = NULL, 132 wxPoint *WXUNUSED(pos) = NULL, 133 bool *WXUNUSED(newFrameEachTime) = NULL) 134 { 135 return (wxFrame*) NULL;// does nothing by default 136 } 137 138 protected: 139 /// Filename of currently active map file. 140 wxString m_helpDir; 141 /// How many entries do we have in the map file? 142 int m_NumOfEntries; 143 /// A list containing all id,url,documentation triples. 144 wxList *m_MapList; 145 146 private: 147 // parse a single line of the map file (called by LoadFile()) 148 // 149 // return true if the line was valid or false otherwise 150 bool ParseMapFileLine(const wxString& line); 151 152 /// Deletes the list and all objects. 153 void DeleteList(void); 154 155 156 /// How to call the html viewer. 157 wxString m_BrowserName; 158 /// Is the viewer a variant of netscape? 159 bool m_BrowserIsNetscape; 160 161 DECLARE_CLASS(wxExtHelpController) 162 }; 163 164 #endif // wxUSE_HELP 165 166 #endif // __WX_HELPEXT_H_ 167