X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/336aecf1c2f69fa10e3271ea94dac7c545bf6300..633e19307ce18ce24837db616feb9dda848056dd:/interface/wx/help.h diff --git a/interface/wx/help.h b/interface/wx/help.h index e32617b320..b3199690f8 100644 --- a/interface/wx/help.h +++ b/interface/wx/help.h @@ -3,14 +3,27 @@ // Purpose: interface of wxHelpController // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + +#define wxHELP_NETSCAPE 1 + + /** - @class wxHelpController + Help search modes for wxHelpController::KeywordSearch(). + */ +enum wxHelpSearchMode +{ + wxHELP_SEARCH_INDEX, ///< Search the index only. + wxHELP_SEARCH_ALL ///< Search all entries. +}; + +/** + @class wxHelpControllerBase - This is a family of classes by which applications may invoke a help viewer - to provide on-line help. + This is the abstract base class a family of classes by which applications + may invoke a help viewer to provide on-line help. A help controller allows an application to display help, at the contents or at a particular topic, and shut the help program down on termination. @@ -22,48 +35,12 @@ The help viewer will only get run, however, just before the first call to display something. - Most help controller classes actually derive from wxHelpControllerBase and have - names of the form wxXXXHelpController or wxHelpControllerXXX. - An appropriate class is aliased to the name wxHelpController for each platform, as - follows: - - On desktop Windows, wxCHMHelpController is used (MS HTML Help). - - On Windows CE, wxWinceHelpController is used. - - On all other platforms, wxHtmlHelpController is used if wxHTML is compiled - into wxWidgets; otherwise wxExtHelpController is used (for invoking an - external browser). - - The remaining help controller classes need to be named explicitly by an - application that wishes to make use of them. - - The following help controller classes are defined: - - wxWinHelpController, for controlling Windows Help. - - wxCHMHelpController, for controlling MS HTML Help. To use this, you need to - set wxUSE_MS_HTML_HELP to 1 in setup.h and have the htmlhelp.h header from - Microsoft's HTML Help kit. (You don't need the VC++-specific htmlhelp.lib - because wxWidgets loads necessary DLL at runtime and so it works with all - compilers.) - - wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime - is not available, wxHtmlHelpController. You need to provide @b both CHM and - HTB versions of the help file. For wxMSW only. - - wxExtHelpController, for controlling external browsers under Unix. - The default browser is Netscape Navigator. The 'help' sample shows its use. - - wxWinceHelpController, for controlling a simple @c .htm help controller for - Windows CE applications. - - wxHtmlHelpController, a sophisticated help controller using wxHTML, in a - similar style to the Microsoft HTML Help viewer and using some of the same - files. Although it has an API compatible with other help controllers, it has - more advanced features, so it is recommended that you use the specific API - for this class instead. Note that if you use .zip or .htb formats for your - books, you must add this line to your application initialization: - @code wxFileSystem::AddHandler(new wxArchiveFSHandler); @endcode - or nothing will be shown in your help window. - - @library{wxbase} + @library{wxcore} @category{help} - @see wxHtmlHelpController, @ref overview_html + @see wxHelpController, wxHtmlHelpController, @ref overview_html */ -class wxHelpController : public wxHelpControllerBase +class wxHelpControllerBase : public wxObject { public: /** @@ -75,12 +52,12 @@ public: You can also change the parent window later with SetParentWindow(). */ - wxHelpController(wxWindow* parentWindow = NULL); + wxHelpControllerBase(wxWindow* parentWindow = NULL); /** Destroys the help instance, closing down the viewer if it is running. */ - ~wxHelpController(); + ~wxHelpControllerBase(); /** If the help viewer is not running, runs it and displays the file at the given @@ -96,12 +73,12 @@ public: This function is for backward compatibility only, and applications should use DisplaySection() instead. */ - virtual bool DisplayBlock(long blockNo); + virtual bool DisplayBlock(long blockNo) = 0; /** If the help viewer is not running, runs it and displays the contents. */ - virtual bool DisplayContents(); + virtual bool DisplayContents() = 0; /** Displays the section as a popup window using a context id. @@ -131,7 +108,7 @@ public: See also the help sample for notes on how to specify section numbers for various help file formats. */ - virtual bool DisplaySection(int sectionNo); + virtual bool DisplaySection(int sectionNo) = 0; /** Displays the text in a popup window, if possible. @@ -153,8 +130,8 @@ public: @param newFrameEachTime @true if a new frame is drawn with each invocation. */ - virtual wxFrame* GetFrameParameters(const wxSize* size = NULL, - const wxPoint* pos = NULL, + virtual wxFrame* GetFrameParameters(wxSize* size = NULL, + wxPoint* pos = NULL, bool* newFrameEachTime = NULL); /** @@ -182,8 +159,8 @@ public: /** If the help viewer is not running, runs it, and searches for sections matching the given keyword. If one match is found, the file is displayed at this section. - The optional parameter allows the search the index (wxHELP_SEARCH_INDEX) - but this currently only supported by the wxHtmlHelpController. + The optional parameter allows to search the index (wxHELP_SEARCH_INDEX) + but this currently is only supported by the wxHtmlHelpController. - @e WinHelp, MS HTML Help: If more than one match is found, the first topic is displayed. @@ -192,7 +169,7 @@ public: - @e wxHtmlHelpController: see wxHtmlHelpController::KeywordSearch. */ virtual bool KeywordSearch(const wxString& keyWord, - wxHelpSearchMode mode = wxHELP_SEARCH_ALL); + wxHelpSearchMode mode = wxHELP_SEARCH_ALL) = 0; /** If the help viewer is not running, runs it and loads the given file. @@ -205,28 +182,32 @@ public: wxHtmlHelpController ignores this call. */ - virtual bool LoadFile(const wxString& file = wxEmptyString); + virtual bool LoadFile(const wxString& file = wxEmptyString) = 0; /** - Overrideable member called when this application's viewer is quit by the user. + Overridable member called when this application's viewer is quit by the user. This does not work for all help controllers. */ - virtual bool OnQuit(); + virtual void OnQuit(); /** If the viewer is running, quits it by disconnecting. For Windows Help, the viewer will only close if no other application is using it. */ - virtual bool Quit(); + virtual bool Quit() = 0; /** - For wxHtmlHelpController, the title is set (with %s indicating the - page title) and also the size and position of the frame if the frame is - already open. @a newFrameEachTime is ignored. + Set the parameters of the frame window. + + For wxHtmlHelpController, @a titleFormat specifies the title string + format (with @c %s being replaced by the actual page title) and @a size + and @a position specify the geometry of the frame. For all other help controllers this function has no effect. + + Finally, @a newFrameEachTime is always ignored currently. */ - virtual void SetFrameParameters(const wxString& title, + virtual void SetFrameParameters(const wxString& titleFormat, const wxSize& size, const wxPoint& pos = wxDefaultPosition, bool newFrameEachTime = false); @@ -256,6 +237,84 @@ public: @todo modernize this function with ::wxLaunchDefaultBrowser */ - virtual void SetViewer(const wxString& viewer, long flags); + virtual void SetViewer(const wxString& viewer, long flags=wxHELP_NETSCAPE); }; + + + + + +/** + @class wxHelpController + + This is an alias for one of a family of help controller classes which is + most appropriate for the current platform. + + A help controller allows an application to display help, at the contents + or at a particular topic, and shut the help program down on termination. + This avoids proliferation of many instances of the help viewer whenever the + user requests a different topic via the application's menus or buttons. + + Typically, an application will create a help controller instance when it starts, + and immediately call wxHelpController::Initialize to associate a filename with it. + The help viewer will only get run, however, just before the first call to + display something. + + Most help controller classes actually derive from wxHelpControllerBase and have + names of the form wxXXXHelpController or wxHelpControllerXXX. + An appropriate class is aliased to the name wxHelpController for each platform, as + follows: + - On desktop Windows, wxCHMHelpController is used (MS HTML Help). + - On Windows CE, wxWinceHelpController is used. + - On all other platforms, wxHtmlHelpController is used if wxHTML is compiled + into wxWidgets; otherwise wxExtHelpController is used (for invoking an + external browser). + + The remaining help controller classes need to be named explicitly by an + application that wishes to make use of them. + + The following help controller classes are defined: + - wxWinHelpController, for controlling Windows Help. + - wxCHMHelpController, for controlling MS HTML Help. To use this, you need to + set wxUSE_MS_HTML_HELP to 1 in setup.h and have the htmlhelp.h header from + Microsoft's HTML Help kit. (You don't need the VC++-specific htmlhelp.lib + because wxWidgets loads necessary DLL at runtime and so it works with all + compilers.) + - wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime + is not available, wxHtmlHelpController. You need to provide @b both CHM and + HTB versions of the help file. For wxMSW only. + - wxExtHelpController, for controlling external browsers under Unix. + The default browser is Netscape Navigator. The 'help' sample shows its use. + - wxWinceHelpController, for controlling a simple @c .htm help controller for + Windows CE applications. + - wxHtmlHelpController, a sophisticated help controller using wxHTML, in a + similar style to the Microsoft HTML Help viewer and using some of the same + files. Although it has an API compatible with other help controllers, it has + more advanced features, so it is recommended that you use the specific API + for this class instead. Note that if you use .zip or .htb formats for your + books, you must add this line to your application initialization: + @code wxFileSystem::AddHandler(new wxArchiveFSHandler); @endcode + or nothing will be shown in your help window. + + @library{wxcore} + @category{help} + + @see wxHtmlHelpController, @ref overview_html +*/ +class wxHelpController : public wxHelpControllerBase +{ +public: + /** + Constructs a help instance object, but does not invoke the help viewer. + + If you provide a window, it will be used by some help controller classes, such as + wxCHMHelpController, wxWinHelpController and wxHtmlHelpController, as the + parent for the help window instead of the value of wxApp::GetTopWindow. + + You can also change the parent window later with SetParentWindow(). + */ + wxHelpController(wxWindow* parentWindow = NULL); +}; + +