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
36class WXDLLIMPEXP_ADV wxExtHelpController : public wxHelpControllerBase
37{
38public:
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   */
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
138protected:
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
146private:
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