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

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

@ -1,124 +1,62 @@
/*-*- 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();
/** 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);
/** 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 WXUNUSED(server))
{ return Initialize(dir); }
/** 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.
@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.
@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 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,
@ -126,21 +64,22 @@ public:
{
// 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
return (wxFrame*) NULL; // does nothing by default
}
protected:
/// Filename of currently active map file.
// Filename of currently active map file.
wxString m_helpDir;
/// How many entries do we have in the map file?
// How many entries do we have in the map file?
int m_NumOfEntries;
/// A list containing all id,url,documentation triples.
// A list containing all id,url,documentation triples.
wxList *m_MapList;
private:
@ -149,13 +88,14 @@ private:
// return true if the line was valid or false otherwise
bool ParseMapFileLine(const wxString& line);
/// Deletes the list and all objects.
// Deletes the list and all objects.
void DeleteList(void);
/// How to call the html viewer.
// How to call the html viewer.
wxString m_BrowserName;
/// Is the viewer a variant of netscape?
// 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);
};

29
src/generic/helpext.cpp
View File

@ -52,26 +52,22 @@
// constants
// ----------------------------------------------------------------------------
/// Name for map file.
// Name for map file.
#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 CONTENTS_ID 0
// The ID of the Contents section
#define WXEXTHELP_CONTENTS_ID 0
IMPLEMENT_CLASS(wxExtHelpController, wxHelpControllerBase)
/// Name of environment variable to set help browser.
// Name of environment variable to set help browser.
#define WXEXTHELP_ENVVAR_BROWSER wxT("WX_HELPBROWSER")
/// Is browser a netscape browser?
// 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.
*/
IMPLEMENT_CLASS(wxExtHelpController, wxHelpControllerBase)
wxExtHelpController::wxExtHelpController(wxWindow* parentWindow)
: wxHelpControllerBase(parentWindow)
@ -100,10 +96,10 @@ void wxExtHelpController::SetBrowser(const wxString& browsername, bool isNetscap
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)
@ -139,6 +135,7 @@ public:
int id;
wxString url;
wxString doc;
wxExtHelpMapEntry(int iid, wxString const &iurl, wxString const &idoc)
{ id = iid; url = iurl; doc = idoc; }
};
@ -327,7 +324,7 @@ bool wxExtHelpController::DisplayContents()
while (node)
{
entry = (wxExtHelpMapEntry *)node->GetData();
if (entry->id == CONTENTS_ID)
if (entry->id == WXEXTHELP_CONTENTS_ID)
{
contents = entry->url;
break;
@ -342,7 +339,7 @@ bool wxExtHelpController::DisplayContents()
if (file.Contains(wxT('#')))
file = file.BeforeLast(wxT('#'));
if (contents.length() && wxFileExists(file))
rc = DisplaySection(CONTENTS_ID);
rc = DisplaySection(WXEXTHELP_CONTENTS_ID);
// if not found, open homemade toc:
return rc ? true : KeywordSearch(wxEmptyString);