Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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()

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52689 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-03-22 12:06:30 +00:00
parent 89267fe552
commit 5c7b506103
3 changed files with 323 additions and 218 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
include/wx/generic/helpext.h
View File

@@ -1,162 +1,102 @@
/*-*- c++ -*-******************************************************** /////////////////////////////////////////////////////////////////////////////
* helpext.h - an external help controller for wxWidgets * // Name: wx/generic/helpext.h
* * // Purpose: an external help controller for wxWidgets
* (C) 1998 by Karsten Ballueder (Ballueder@usa.net) * // Author: Karsten Ballueder (Ballueder@usa.net)
* License: wxWindows licence * // Modified by:
* * // Copyright: (c) Karsten Ballueder 1998
* $Id$ // RCS-ID: $Id$
*******************************************************************/ // Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
#ifndef __WX_HELPEXT_H_ #ifndef __WX_HELPEXT_H_
#define __WX_HELPEXT_H_ #define __WX_HELPEXT_H_
#if wxUSE_HELP #if wxUSE_HELP
// ----------------------------------------------------------------------------
// headers
// ----------------------------------------------------------------------------
#include "wx/helpbase.h" #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] // wxExtHelpController
// ----------------------------------------------------------------------------
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.
*/
// This class implements help via an external browser.
class WXDLLIMPEXP_ADV wxExtHelpController : public wxHelpControllerBase class WXDLLIMPEXP_ADV wxExtHelpController : public wxHelpControllerBase
{ {
public: public:
wxExtHelpController(wxWindow* parentWindow = NULL); wxExtHelpController(wxWindow* parentWindow = NULL);
virtual ~wxExtHelpController(); virtual ~wxExtHelpController();
/** Tell it which browser to use. #if WXWIN_COMPATIBILITY_2_8
The Netscape support will check whether Netscape is already wxDEPRECATED(void SetBrowser(const wxString& browsername = wxEmptyString, bool isNetscape = false) );
running (by looking at the .netscape/lock file in the user's #endif
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);
// Set viewer: new name for SetBrowser // Set viewer: new name for SetBrowser
virtual void SetViewer(const wxString& viewer = wxEmptyString, virtual void SetViewer(const wxString& viewer = wxEmptyString,
long flags = wxHELP_NETSCAPE); long flags = wxHELP_NETSCAPE);
/** This must be called to tell the controller where to find the virtual bool Initialize(const wxString& dir, int WXUNUSED(server))
documentation. { return Initialize(dir); }
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. virtual bool Initialize(const wxString& dir);
@return true on success virtual bool LoadFile(const wxString& file = wxEmptyString);
*/ virtual bool DisplayContents(void);
virtual bool Initialize(const wxString& dir, int WXUNUSED(server)) virtual bool DisplaySection(int sectionNo);
{ return Initialize(dir); } 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 virtual bool Quit(void);
documentation. virtual void OnQuit(void);
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. virtual bool DisplayHelp(const wxString &) ;
@file Name of help directory.
@return true on success
*/
virtual bool LoadFile(const wxString& file = wxEmptyString);
/** Display list of all help entries. virtual void SetFrameParameters(const wxString& WXUNUSED(title),
@return true on success const wxSize& WXUNUSED(size),
*/ const wxPoint& WXUNUSED(pos) = wxDefaultPosition,
virtual bool DisplayContents(void); bool WXUNUSED(newFrameEachTime) = false)
/** Display help for id sectionNo. {
@return true on success // does nothing by default
*/ }
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);
/// does nothing virtual wxFrame *GetFrameParameters(wxSize *WXUNUSED(size) = NULL,
virtual bool Quit(void); wxPoint *WXUNUSED(pos) = NULL,
/// does nothing bool *WXUNUSED(newFrameEachTime) = NULL)
virtual void OnQuit(void); {
return (wxFrame*) NULL; // does nothing by default
/// 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
}
protected: protected:
/// Filename of currently active map file. // Filename of currently active map file.
wxString m_helpDir; wxString m_helpDir;
/// How many entries do we have in the map file?
int m_NumOfEntries; // How many entries do we have in the map file?
/// A list containing all id,url,documentation triples. int m_NumOfEntries;
wxList *m_MapList;
// A list containing all id,url,documentation triples.
wxList *m_MapList;
private: private:
// parse a single line of the map file (called by LoadFile()) // parse a single line of the map file (called by LoadFile())
// //
// return true if the line was valid or false otherwise // return true if the line was valid or false otherwise
bool ParseMapFileLine(const wxString& line); bool ParseMapFileLine(const wxString& line);
/// Deletes the list and all objects. // Deletes the list and all objects.
void DeleteList(void); void DeleteList(void);
/// How to call the html viewer. // How to call the html viewer.
wxString m_BrowserName; wxString m_BrowserName;
/// Is the viewer a variant of netscape?
bool m_BrowserIsNetscape; // Is the viewer a variant of netscape?
bool m_BrowserIsNetscape;
DECLARE_CLASS(wxExtHelpController) DECLARE_CLASS(wxExtHelpController)
}; };

168
interface/generic/helpext.h Normal file
View File

@@ -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);
};

171
src/generic/helpext.cpp
View File

@@ -52,58 +52,54 @@
// constants // constants
// ---------------------------------------------------------------------------- // ----------------------------------------------------------------------------
/// Name for map file. // Name for map file.
#define WXEXTHELP_MAPFILE _T("wxhelp.map") #define WXEXTHELP_MAPFILE _T("wxhelp.map")
/// Character introducing comments/documentation field in map file. // Character introducing comments/documentation field in map file.
#define WXEXTHELP_COMMENTCHAR ';' #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) 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) wxExtHelpController::wxExtHelpController(wxWindow* parentWindow)
: wxHelpControllerBase(parentWindow) : wxHelpControllerBase(parentWindow)
{ {
m_MapList = NULL; m_MapList = NULL;
m_NumOfEntries = 0; m_NumOfEntries = 0;
m_BrowserIsNetscape = false; m_BrowserIsNetscape = false;
wxChar *browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSER); wxChar *browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSER);
if (browser) if (browser)
{ {
m_BrowserName = browser; m_BrowserName = browser;
browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSERISNETSCAPE); browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSERISNETSCAPE);
m_BrowserIsNetscape = browser && (wxAtoi(browser) != 0); m_BrowserIsNetscape = browser && (wxAtoi(browser) != 0);
} }
} }
wxExtHelpController::~wxExtHelpController() wxExtHelpController::~wxExtHelpController()
{ {
DeleteList(); DeleteList();
} }
void wxExtHelpController::SetBrowser(const wxString& browsername, bool isNetscape) void wxExtHelpController::SetBrowser(const wxString& browsername, bool isNetscape)
{ {
m_BrowserName = browsername; m_BrowserName = browsername;
m_BrowserIsNetscape = isNetscape; m_BrowserIsNetscape = isNetscape;
} }
// Set viewer: new, generic name for SetBrowser
void wxExtHelpController::SetViewer(const wxString& viewer, long flags) 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) bool wxExtHelpController::DisplayHelp(const wxString &relativeURL)
@@ -136,28 +132,29 @@ bool wxExtHelpController::DisplayHelp(const wxString &relativeURL)
class wxExtHelpMapEntry : public wxObject class wxExtHelpMapEntry : public wxObject
{ {
public: public:
int id; int id;
wxString url; wxString url;
wxString doc; wxString doc;
wxExtHelpMapEntry(int iid, wxString const &iurl, wxString const &idoc)
{ id = iid; url = iurl; doc = idoc; } wxExtHelpMapEntry(int iid, wxString const &iurl, wxString const &idoc)
{ id = iid; url = iurl; doc = idoc; }
}; };
void wxExtHelpController::DeleteList() void wxExtHelpController::DeleteList()
{ {
if (m_MapList) if (m_MapList)
{ {
wxList::compatibility_iterator node = m_MapList->GetFirst(); wxList::compatibility_iterator node = m_MapList->GetFirst();
while (node) while (node)
{ {
delete (wxExtHelpMapEntry *)node->GetData(); delete (wxExtHelpMapEntry *)node->GetData();
m_MapList->Erase(node); m_MapList->Erase(node);
node = m_MapList->GetFirst(); node = m_MapList->GetFirst();
} }
delete m_MapList; delete m_MapList;
m_MapList = (wxList*) NULL; m_MapList = (wxList*) NULL;
} }
} }
// This must be called to tell the controller where to find the documentation. // This must be called to tell the controller where to find the documentation.
@@ -165,7 +162,7 @@ void wxExtHelpController::DeleteList()
// @return true on success // @return true on success
bool wxExtHelpController::Initialize(const wxString& file) bool wxExtHelpController::Initialize(const wxString& file)
{ {
return LoadFile(file); return LoadFile(file);
} }
bool wxExtHelpController::ParseMapFileLine(const wxString& line) bool wxExtHelpController::ParseMapFileLine(const wxString& line)
@@ -318,53 +315,53 @@ bool wxExtHelpController::LoadFile(const wxString& file)
bool wxExtHelpController::DisplayContents() bool wxExtHelpController::DisplayContents()
{ {
if (! m_NumOfEntries) if (! m_NumOfEntries)
return false; return false;
wxString contents; wxString contents;
wxList::compatibility_iterator node = m_MapList->GetFirst(); wxList::compatibility_iterator node = m_MapList->GetFirst();
wxExtHelpMapEntry *entry; wxExtHelpMapEntry *entry;
while (node) while (node)
{ {
entry = (wxExtHelpMapEntry *)node->GetData(); entry = (wxExtHelpMapEntry *)node->GetData();
if (entry->id == CONTENTS_ID) if (entry->id == WXEXTHELP_CONTENTS_ID)
{ {
contents = entry->url; contents = entry->url;
break; break;
} }
node = node->GetNext(); node = node->GetNext();
} }
bool rc = false; bool rc = false;
wxString file; wxString file;
file << m_helpDir << wxFILE_SEP_PATH << contents; file << m_helpDir << wxFILE_SEP_PATH << contents;
if (file.Contains(wxT('#'))) if (file.Contains(wxT('#')))
file = file.BeforeLast(wxT('#')); file = file.BeforeLast(wxT('#'));
if (contents.length() && wxFileExists(file)) if (contents.length() && wxFileExists(file))
rc = DisplaySection(CONTENTS_ID); rc = DisplaySection(WXEXTHELP_CONTENTS_ID);
// if not found, open homemade toc: // if not found, open homemade toc:
return rc ? true : KeywordSearch(wxEmptyString); return rc ? true : KeywordSearch(wxEmptyString);
} }
bool wxExtHelpController::DisplaySection(int sectionNo) bool wxExtHelpController::DisplaySection(int sectionNo)
{ {
if (! m_NumOfEntries) if (! m_NumOfEntries)
return false; return false;
wxBusyCursor b; // display a busy cursor wxBusyCursor b; // display a busy cursor
wxList::compatibility_iterator node = m_MapList->GetFirst(); wxList::compatibility_iterator node = m_MapList->GetFirst();
wxExtHelpMapEntry *entry; wxExtHelpMapEntry *entry;
while (node) while (node)
{ {
entry = (wxExtHelpMapEntry *)node->GetData(); entry = (wxExtHelpMapEntry *)node->GetData();
if (entry->id == sectionNo) if (entry->id == sectionNo)
return DisplayHelp(entry->url); return DisplayHelp(entry->url);
node = node->GetNext(); node = node->GetNext();
} }
return false; return false;
} }
bool wxExtHelpController::DisplaySection(const wxString& section) bool wxExtHelpController::DisplaySection(const wxString& section)
@@ -379,7 +376,7 @@ bool wxExtHelpController::DisplaySection(const wxString& section)
bool wxExtHelpController::DisplayBlock(long blockNo) bool wxExtHelpController::DisplayBlock(long blockNo)
{ {
return DisplaySection((int)blockNo); return DisplaySection((int)blockNo);
} }
bool wxExtHelpController::KeywordSearch(const wxString& k, bool wxExtHelpController::KeywordSearch(const wxString& k,