]>
Commit | Line | Data |
---|---|---|
e9aad10a | 1 | /*-*- c++ -*-******************************************************** |
a75d9863 | 2 | * helpext.h - an external help controller for wxWidgets * |
e9aad10a | 3 | * * |
9d55bfef | 4 | * (C) 1998 by Karsten Ballueder (Ballueder@usa.net) * |
a75d9863 | 5 | * License: wxWindows licence * |
e9aad10a KB |
6 | * * |
7 | * $Id$ | |
8 | *******************************************************************/ | |
88ac883a VZ |
9 | |
10 | #ifndef __WX_HELPEXT_H_ | |
11 | #define __WX_HELPEXT_H_ | |
e9aad10a KB |
12 | |
13 | #if wxUSE_HELP | |
14 | ||
69108ccb JS |
15 | #include "wx/helpbase.h" |
16 | ||
e9aad10a KB |
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 | ||
12f190b0 | 36 | class WXDLLIMPEXP_ADV wxExtHelpController : public wxHelpControllerBase |
ca65c044 | 37 | { |
249b3fe3 | 38 | public: |
3db52265 | 39 | wxExtHelpController(wxWindow* parentWindow = NULL); |
d3c7fc99 | 40 | virtual ~wxExtHelpController(); |
e9aad10a KB |
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 | |
ca65c044 | 46 | window. |
e9aad10a | 47 | @param browsername The command to call a browser/html viewer. |
ca65c044 | 48 | @param isNetscape Set this to true if the browser is some variant of Netscape. |
e9aad10a | 49 | */ |
a85a25c7 VZ |
50 | void SetBrowser(const wxString& browsername = wxEmptyString, |
51 | bool isNetscape = false); | |
33b64e6f JS |
52 | |
53 | // Set viewer: new name for SetBrowser | |
a85a25c7 VZ |
54 | virtual void SetViewer(const wxString& viewer = wxEmptyString, |
55 | long flags = wxHELP_NETSCAPE); | |
33b64e6f | 56 | |
69108ccb JS |
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 | */ | |
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 | */ | |
ca65c044 | 87 | virtual bool LoadFile(const wxString& file = wxEmptyString); |
69108ccb JS |
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 | */ | |
cb07c544 VZ |
110 | virtual bool KeywordSearch(const wxString& k, |
111 | wxHelpSearchMode mode = wxHELP_SEARCH_ALL); | |
69108ccb JS |
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, | |
ca65c044 | 125 | bool WXUNUSED(newFrameEachTime) = false) |
69108ccb JS |
126 | { |
127 | // does nothing by default | |
128 | } | |
ca65c044 | 129 | /// Obtains the latest settings used by the help frame and the help |
69108ccb JS |
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 | ||
249b3fe3 | 138 | protected: |
69108ccb | 139 | /// Filename of currently active map file. |
2364556b | 140 | wxString m_helpDir; |
69108ccb JS |
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; | |
249b3fe3 VZ |
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 | ||
69108ccb JS |
152 | /// Deletes the list and all objects. |
153 | void DeleteList(void); | |
154 | ||
249b3fe3 | 155 | |
e9aad10a KB |
156 | /// How to call the html viewer. |
157 | wxString m_BrowserName; | |
158 | /// Is the viewer a variant of netscape? | |
159 | bool m_BrowserIsNetscape; | |
249b3fe3 VZ |
160 | |
161 | DECLARE_CLASS(wxExtHelpController) | |
e9aad10a KB |
162 | }; |
163 | ||
88ac883a VZ |
164 | #endif // wxUSE_HELP |
165 | ||
166 | #endif // __WX_HELPEXT_H_ |