cheng/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
Show Stats 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 *
* *
* (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)
};

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
// ----------------------------------------------------------------------------
/// 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,