From 5c7b506103cfc078a821860766e31c47d595e07f Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sat, 22 Mar 2008 12:06:30 +0000 Subject: [PATCH] use wx-style header and commets; fix indentation to be 4 spaces; move Doxygen comments in a new interface header; deprecate SetBrowser() in favour of SetViewer() git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52689 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- include/wx/generic/helpext.h | 202 ++++++++++++----------------------- interface/generic/helpext.h | 168 +++++++++++++++++++++++++++++ src/generic/helpext.cpp | 171 +++++++++++++++-------------- 3 files changed, 323 insertions(+), 218 deletions(-) create mode 100644 interface/generic/helpext.h diff --git a/include/wx/generic/helpext.h b/include/wx/generic/helpext.h index cf7fac0a21..080ba94620 100644 --- a/include/wx/generic/helpext.h +++ b/include/wx/generic/helpext.h @@ -1,162 +1,102 @@ -/*-*- c++ -*-******************************************************** - * helpext.h - an external help controller for wxWidgets * - * * - * (C) 1998 by Karsten Ballueder (Ballueder@usa.net) * - * License: wxWindows licence * - * * - * $Id$ - *******************************************************************/ +///////////////////////////////////////////////////////////////////////////// +// Name: wx/generic/helpext.h +// Purpose: an external help controller for wxWidgets +// Author: Karsten Ballueder (Ballueder@usa.net) +// Modified by: +// Copyright: (c) Karsten Ballueder 1998 +// RCS-ID: $Id$ +// Licence: wxWindows licence +///////////////////////////////////////////////////////////////////////////// #ifndef __WX_HELPEXT_H_ #define __WX_HELPEXT_H_ #if wxUSE_HELP + +// ---------------------------------------------------------------------------- +// headers +// ---------------------------------------------------------------------------- + #include "wx/helpbase.h" -/** - This class implements help via an external browser. - It requires the name of a directory containing the documentation - and a file mapping numerical Section numbers to relative URLS. - The map file contains two or three fields per line: - numeric_id relative_URL [; comment/documentation] - - The numeric_id is the id used to look up the entry in - DisplaySection()/DisplayBlock(). The relative_URL is a filename of - an html file, relative to the help directory. The optional - comment/documentation field (after a ';') is used for keyword - searches, so some meaningful text here does not hurt. - If the documentation itself contains a ';', only the part before - that will be displayed in the listbox, but all of it used for search. - - Lines starting with ';' will be ignored. -*/ +// ---------------------------------------------------------------------------- +// wxExtHelpController +// ---------------------------------------------------------------------------- +// This class implements help via an external browser. class WXDLLIMPEXP_ADV wxExtHelpController : public wxHelpControllerBase { public: - wxExtHelpController(wxWindow* parentWindow = NULL); - virtual ~wxExtHelpController(); + wxExtHelpController(wxWindow* parentWindow = NULL); + virtual ~wxExtHelpController(); - /** Tell it which browser to use. - The Netscape support will check whether Netscape is already - running (by looking at the .netscape/lock file in the user's - home directory) and tell it to load the page into the existing - window. - @param browsername The command to call a browser/html viewer. - @param isNetscape Set this to true if the browser is some variant of Netscape. - */ - void SetBrowser(const wxString& browsername = wxEmptyString, - bool isNetscape = false); +#if WXWIN_COMPATIBILITY_2_8 + wxDEPRECATED(void SetBrowser(const wxString& browsername = wxEmptyString, bool isNetscape = false) ); +#endif - // Set viewer: new name for SetBrowser - virtual void SetViewer(const wxString& viewer = wxEmptyString, - long flags = wxHELP_NETSCAPE); + // Set viewer: new name for SetBrowser + virtual void SetViewer(const wxString& viewer = wxEmptyString, + long flags = wxHELP_NETSCAPE); - /** This must be called to tell the controller where to find the - documentation. - If a locale is set, look in file/localename, i.e. - If passed "/usr/local/myapp/help" and the current wxLocale is - set to be "de", then look in "/usr/local/myapp/help/de/" - first and fall back to "/usr/local/myapp/help" if that - doesn't exist. + virtual bool Initialize(const wxString& dir, int WXUNUSED(server)) + { return Initialize(dir); } - @param file - NOT a filename, but a directory name. - @return true on success - */ - virtual bool Initialize(const wxString& dir, int WXUNUSED(server)) - { return Initialize(dir); } + virtual bool Initialize(const wxString& dir); + virtual bool LoadFile(const wxString& file = wxEmptyString); + virtual bool DisplayContents(void); + virtual bool DisplaySection(int sectionNo); + virtual bool DisplaySection(const wxString& section); + virtual bool DisplayBlock(long blockNo); + virtual bool KeywordSearch(const wxString& k, + wxHelpSearchMode mode = wxHELP_SEARCH_ALL); - /** This must be called to tell the controller where to find the - documentation. - If a locale is set, look in file/localename, i.e. - If passed "/usr/local/myapp/help" and the current wxLocale is - set to be "de", then look in "/usr/local/myapp/help/de/" - first and fall back to "/usr/local/myapp/help" if that - doesn't exist. - @param dir - directory name where to fine the help files - @return true on success - */ - virtual bool Initialize(const wxString& dir); + virtual bool Quit(void); + virtual void OnQuit(void); - /** If file is "", reloads file given in Initialize. - @file Name of help directory. - @return true on success - */ - virtual bool LoadFile(const wxString& file = wxEmptyString); + virtual bool DisplayHelp(const wxString &) ; - /** Display list of all help entries. - @return true on success - */ - virtual bool DisplayContents(void); - /** Display help for id sectionNo. - @return true on success - */ - virtual bool DisplaySection(int sectionNo); - /** Display help for id sectionNo -- identical with DisplaySection(). - @return true on success - */ - virtual bool DisplaySection(const wxString& section); - /** Display help for URL (using DisplayHelp) or keyword (using KeywordSearch) - @return true on success - */ - virtual bool DisplayBlock(long blockNo); - /** Search comment/documentation fields in map file and present a - list to chose from. - @key k string to search for, empty string will list all entries - @return true on success - */ - virtual bool KeywordSearch(const wxString& k, - wxHelpSearchMode mode = wxHELP_SEARCH_ALL); + virtual void SetFrameParameters(const wxString& WXUNUSED(title), + const wxSize& WXUNUSED(size), + const wxPoint& WXUNUSED(pos) = wxDefaultPosition, + bool WXUNUSED(newFrameEachTime) = false) + { + // does nothing by default + } - /// does nothing - virtual bool Quit(void); - /// does nothing - virtual void OnQuit(void); - - /// Call the browser using a relative URL. - virtual bool DisplayHelp(const wxString &) ; - - /// Allows one to override the default settings for the help frame. - virtual void SetFrameParameters(const wxString& WXUNUSED(title), - const wxSize& WXUNUSED(size), - const wxPoint& WXUNUSED(pos) = wxDefaultPosition, - bool WXUNUSED(newFrameEachTime) = false) - { - // does nothing by default - } - /// Obtains the latest settings used by the help frame and the help - /// frame. - virtual wxFrame *GetFrameParameters(wxSize *WXUNUSED(size) = NULL, - wxPoint *WXUNUSED(pos) = NULL, - bool *WXUNUSED(newFrameEachTime) = NULL) - { - return (wxFrame*) NULL;// does nothing by default - } + virtual wxFrame *GetFrameParameters(wxSize *WXUNUSED(size) = NULL, + wxPoint *WXUNUSED(pos) = NULL, + bool *WXUNUSED(newFrameEachTime) = NULL) + { + return (wxFrame*) NULL; // does nothing by default + } protected: - /// Filename of currently active map file. - wxString m_helpDir; - /// How many entries do we have in the map file? - int m_NumOfEntries; - /// A list containing all id,url,documentation triples. - wxList *m_MapList; + // Filename of currently active map file. + wxString m_helpDir; + + // How many entries do we have in the map file? + int m_NumOfEntries; + + // A list containing all id,url,documentation triples. + wxList *m_MapList; private: - // parse a single line of the map file (called by LoadFile()) - // - // return true if the line was valid or false otherwise - bool ParseMapFileLine(const wxString& line); + // parse a single line of the map file (called by LoadFile()) + // + // return true if the line was valid or false otherwise + bool ParseMapFileLine(const wxString& line); - /// Deletes the list and all objects. - void DeleteList(void); + // Deletes the list and all objects. + void DeleteList(void); - /// How to call the html viewer. - wxString m_BrowserName; - /// Is the viewer a variant of netscape? - bool m_BrowserIsNetscape; + // How to call the html viewer. + wxString m_BrowserName; + + // Is the viewer a variant of netscape? + bool m_BrowserIsNetscape; DECLARE_CLASS(wxExtHelpController) }; diff --git a/interface/generic/helpext.h b/interface/generic/helpext.h new file mode 100644 index 0000000000..57c84afce9 --- /dev/null +++ b/interface/generic/helpext.h @@ -0,0 +1,168 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: helpext.h +// Purpose: interface of wxExtHelpController +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + @class wxExtHelpController + @wxheader{help.h} + + This class implements help via an external browser. + It requires the name of a directory containing the documentation + and a file mapping numerical Section numbers to relative URLS. + + The map file contains two or three fields per line: + numeric_id relative_URL [; comment/documentation] + + The numeric_id is the id used to look up the entry in + DisplaySection()/DisplayBlock(). The relative_URL is a filename of + an html file, relative to the help directory. The optional + comment/documentation field (after a ';') is used for keyword + searches, so some meaningful text here does not hurt. + If the documentation itself contains a ';', only the part before + that will be displayed in the listbox, but all of it used for search. + + Lines starting with ';' will be ignored. + + @library{wxadv} + @category{help} + + @see wxHelpController +*/ +class wxExtHelpController : public wxHelpController +{ +public: + wxExtHelpController(wxWindow* parentWindow = NULL); + virtual ~wxExtHelpController(); + + /** + Tell it which browser to use. + The Netscape support will check whether Netscape is already + running (by looking at the .netscape/lock file in the user's + home directory) and tell it to load the page into the existing window. + + @param viewer + The command to call a browser/html viewer. + @param flags + Set this to wxHELP_NETSCAPE if the browser is some variant of Netscape. + */ + virtual void SetViewer(const wxString& viewer = wxEmptyString, + long flags = wxHELP_NETSCAPE); + + /** + This must be called to tell the controller where to find the + documentation. + If a locale is set, look in file/localename, i.e. + If passed "/usr/local/myapp/help" and the current wxLocale is + set to be "de", then look in "/usr/local/myapp/help/de/" + first and fall back to "/usr/local/myapp/help" if that + doesn't exist. + + @param file + NOT a filename, but a directory name. + + @return @true on success + */ + virtual bool Initialize(const wxString& dir, int server); + + /** + This must be called to tell the controller where to find the + documentation. + If a locale is set, look in file/localename, i.e. + If passed "/usr/local/myapp/help" and the current wxLocale is + set to be "de", then look in "/usr/local/myapp/help/de/" + first and fall back to "/usr/local/myapp/help" if that + doesn't exist. + + @param dir + directory name where to fine the help files + + @return @true on success + */ + virtual bool Initialize(const wxString& dir); + + /** + If file is "", reloads file given in Initialize. + + @param file + Name of help directory. + + @return @true on success + */ + virtual bool LoadFile(const wxString& file = wxEmptyString); + + /** + Display list of all help entries. + + @return @true on success + */ + virtual bool DisplayContents(void); + + /** + Display help for id sectionNo. + + @return @true on success + */ + virtual bool DisplaySection(int sectionNo); + + /** + Display help for id sectionNo -- identical with DisplaySection(). + + @return @true on success + */ + virtual bool DisplaySection(const wxString& section); + + /** + Display help for URL (using DisplayHelp) or keyword (using KeywordSearch) + + @return @true on success + */ + virtual bool DisplayBlock(long blockNo); + + /** + Search comment/documentation fields in map file and present a + list to chose from. + + @param k + string to search for, empty string will list all entries + + @return @true on success + */ + virtual bool KeywordSearch(const wxString& k, + wxHelpSearchMode mode = wxHELP_SEARCH_ALL); + + /** + Does nothing. + */ + virtual bool Quit(); + + /** + Does nothing. + */ + virtual void OnQuit(); + + /** + Call the browser using a relative URL. + */ + virtual bool DisplayHelp(const wxString &) ; + + /** + Allows one to override the default settings for the help frame. + */ + virtual void SetFrameParameters(const wxString& title, + const wxSize& size, + const wxPoint& pos = wxDefaultPosition, + bool newFrameEachTime = false); + + /** + Obtains the latest settings used by the help frame and the help frame. + */ + virtual wxFrame *GetFrameParameters(wxSize *size = NULL, + wxPoint *pos = NULL, + bool *newFrameEachTime = NULL); +}; + diff --git a/src/generic/helpext.cpp b/src/generic/helpext.cpp index fcf5f1f82a..64e1695638 100644 --- a/src/generic/helpext.cpp +++ b/src/generic/helpext.cpp @@ -52,58 +52,54 @@ // constants // ---------------------------------------------------------------------------- -/// Name for map file. -#define WXEXTHELP_MAPFILE _T("wxhelp.map") +// Name for map file. +#define WXEXTHELP_MAPFILE _T("wxhelp.map") -/// Character introducing comments/documentation field in map file. -#define WXEXTHELP_COMMENTCHAR ';' +// Character introducing comments/documentation field in map file. +#define WXEXTHELP_COMMENTCHAR ';' -#define CONTENTS_ID 0 +// The ID of the Contents section +#define WXEXTHELP_CONTENTS_ID 0 + +// Name of environment variable to set help browser. +#define WXEXTHELP_ENVVAR_BROWSER wxT("WX_HELPBROWSER") + +// Is browser a netscape browser? +#define WXEXTHELP_ENVVAR_BROWSERISNETSCAPE wxT("WX_HELPBROWSER_NS") IMPLEMENT_CLASS(wxExtHelpController, wxHelpControllerBase) -/// Name of environment variable to set help browser. -#define WXEXTHELP_ENVVAR_BROWSER wxT("WX_HELPBROWSER") -/// Is browser a netscape browser? -#define WXEXTHELP_ENVVAR_BROWSERISNETSCAPE wxT("WX_HELPBROWSER_NS") - -/** - This class implements help via an external browser. - It requires the name of a directory containing the documentation - and a file mapping numerical Section numbers to relative URLS. -*/ - wxExtHelpController::wxExtHelpController(wxWindow* parentWindow) : wxHelpControllerBase(parentWindow) { - m_MapList = NULL; - m_NumOfEntries = 0; - m_BrowserIsNetscape = false; + m_MapList = NULL; + m_NumOfEntries = 0; + m_BrowserIsNetscape = false; - wxChar *browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSER); - if (browser) - { - m_BrowserName = browser; - browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSERISNETSCAPE); - m_BrowserIsNetscape = browser && (wxAtoi(browser) != 0); - } + wxChar *browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSER); + if (browser) + { + m_BrowserName = browser; + browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSERISNETSCAPE); + m_BrowserIsNetscape = browser && (wxAtoi(browser) != 0); + } } wxExtHelpController::~wxExtHelpController() { - DeleteList(); + DeleteList(); } void wxExtHelpController::SetBrowser(const wxString& browsername, bool isNetscape) { - m_BrowserName = browsername; - m_BrowserIsNetscape = isNetscape; + m_BrowserName = browsername; + m_BrowserIsNetscape = isNetscape; } -// Set viewer: new, generic name for SetBrowser void wxExtHelpController::SetViewer(const wxString& viewer, long flags) { - SetBrowser(viewer, (flags & wxHELP_NETSCAPE) != 0); + m_BrowserName = viewer; + m_BrowserIsNetscape = (flags & wxHELP_NETSCAPE) != 0; } bool wxExtHelpController::DisplayHelp(const wxString &relativeURL) @@ -136,28 +132,29 @@ bool wxExtHelpController::DisplayHelp(const wxString &relativeURL) class wxExtHelpMapEntry : public wxObject { public: - int id; - wxString url; - wxString doc; - wxExtHelpMapEntry(int iid, wxString const &iurl, wxString const &idoc) - { id = iid; url = iurl; doc = idoc; } + int id; + wxString url; + wxString doc; + + wxExtHelpMapEntry(int iid, wxString const &iurl, wxString const &idoc) + { id = iid; url = iurl; doc = idoc; } }; void wxExtHelpController::DeleteList() { - if (m_MapList) - { - wxList::compatibility_iterator node = m_MapList->GetFirst(); - while (node) - { - delete (wxExtHelpMapEntry *)node->GetData(); - m_MapList->Erase(node); - node = m_MapList->GetFirst(); - } + if (m_MapList) + { + wxList::compatibility_iterator node = m_MapList->GetFirst(); + while (node) + { + delete (wxExtHelpMapEntry *)node->GetData(); + m_MapList->Erase(node); + node = m_MapList->GetFirst(); + } - delete m_MapList; - m_MapList = (wxList*) NULL; - } + delete m_MapList; + m_MapList = (wxList*) NULL; + } } // This must be called to tell the controller where to find the documentation. @@ -165,7 +162,7 @@ void wxExtHelpController::DeleteList() // @return true on success bool wxExtHelpController::Initialize(const wxString& file) { - return LoadFile(file); + return LoadFile(file); } bool wxExtHelpController::ParseMapFileLine(const wxString& line) @@ -318,53 +315,53 @@ bool wxExtHelpController::LoadFile(const wxString& file) bool wxExtHelpController::DisplayContents() { - if (! m_NumOfEntries) - return false; + if (! m_NumOfEntries) + return false; - wxString contents; - wxList::compatibility_iterator node = m_MapList->GetFirst(); - wxExtHelpMapEntry *entry; - while (node) - { - entry = (wxExtHelpMapEntry *)node->GetData(); - if (entry->id == CONTENTS_ID) - { - contents = entry->url; - break; - } + wxString contents; + wxList::compatibility_iterator node = m_MapList->GetFirst(); + wxExtHelpMapEntry *entry; + while (node) + { + entry = (wxExtHelpMapEntry *)node->GetData(); + if (entry->id == WXEXTHELP_CONTENTS_ID) + { + contents = entry->url; + break; + } - node = node->GetNext(); - } + node = node->GetNext(); + } - bool rc = false; - wxString file; - file << m_helpDir << wxFILE_SEP_PATH << contents; - if (file.Contains(wxT('#'))) - file = file.BeforeLast(wxT('#')); - if (contents.length() && wxFileExists(file)) - rc = DisplaySection(CONTENTS_ID); + bool rc = false; + wxString file; + file << m_helpDir << wxFILE_SEP_PATH << contents; + if (file.Contains(wxT('#'))) + file = file.BeforeLast(wxT('#')); + if (contents.length() && wxFileExists(file)) + rc = DisplaySection(WXEXTHELP_CONTENTS_ID); - // if not found, open homemade toc: - return rc ? true : KeywordSearch(wxEmptyString); + // if not found, open homemade toc: + return rc ? true : KeywordSearch(wxEmptyString); } bool wxExtHelpController::DisplaySection(int sectionNo) { - if (! m_NumOfEntries) - return false; + if (! m_NumOfEntries) + return false; - wxBusyCursor b; // display a busy cursor - wxList::compatibility_iterator node = m_MapList->GetFirst(); - wxExtHelpMapEntry *entry; - while (node) - { - entry = (wxExtHelpMapEntry *)node->GetData(); - if (entry->id == sectionNo) - return DisplayHelp(entry->url); - node = node->GetNext(); - } + wxBusyCursor b; // display a busy cursor + wxList::compatibility_iterator node = m_MapList->GetFirst(); + wxExtHelpMapEntry *entry; + while (node) + { + entry = (wxExtHelpMapEntry *)node->GetData(); + if (entry->id == sectionNo) + return DisplayHelp(entry->url); + node = node->GetNext(); + } - return false; + return false; } bool wxExtHelpController::DisplaySection(const wxString& section) @@ -379,7 +376,7 @@ bool wxExtHelpController::DisplaySection(const wxString& section) bool wxExtHelpController::DisplayBlock(long blockNo) { - return DisplaySection((int)blockNo); + return DisplaySection((int)blockNo); } bool wxExtHelpController::KeywordSearch(const wxString& k,