[wxWidgets.git] / interface / wx / generic / helpext.h

/////////////////////////////////////////////////////////////////////////////
// Name:        helpext.h
// Purpose:     interface of wxExtHelpController
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////


/**
    @class wxExtHelpController

    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 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
        
        @param mode    
            optional parameter allows the search the index (wxHELP_SEARCH_INDEX) 
            but this currently only supported by the wxHtmlHelpController.

        @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);
};
Commit	Line	Data
5c7b5061 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: helpext.h
	3	// Purpose: interface of wxExtHelpController
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9
	10	/**
	11	@class wxExtHelpController
5c7b5061 FM	12
	13	This class implements help via an external browser.
	14	It requires the name of a directory containing the documentation
	15	and a file mapping numerical Section numbers to relative URLS.
	16
	17	The map file contains two or three fields per line:
	18	numeric_id relative_URL [; comment/documentation]
	19
	20	The numeric_id is the id used to look up the entry in
	21	DisplaySection()/DisplayBlock(). The relative_URL is a filename of
	22	an html file, relative to the help directory. The optional
	23	comment/documentation field (after a ';') is used for keyword
	24	searches, so some meaningful text here does not hurt.
	25	If the documentation itself contains a ';', only the part before
	26	that will be displayed in the listbox, but all of it used for search.
	27
	28	Lines starting with ';' will be ignored.
	29
	30	@library{wxadv}
	31	@category{help}
	32
	33	@see wxHelpController
	34	*/
	35	class wxExtHelpController : public wxHelpController
	36	{
	37	public:
	38	wxExtHelpController(wxWindow* parentWindow = NULL);
	39	virtual ~wxExtHelpController();
	40
	41	/**
	42	Tell it which browser to use.
	43	The Netscape support will check whether Netscape is already
	44	running (by looking at the .netscape/lock file in the user's
	45	home directory) and tell it to load the page into the existing window.
	46
	47	@param viewer
	48	The command to call a browser/html viewer.
	49	@param flags
	50	Set this to wxHELP_NETSCAPE if the browser is some variant of Netscape.
	51	*/
	52	virtual void SetViewer(const wxString& viewer = wxEmptyString,
	53	long flags = wxHELP_NETSCAPE);
	54
5c7b5061 FM	55	/**
	56	This must be called to tell the controller where to find the
	57	documentation.
	58	If a locale is set, look in file/localename, i.e.
	59	If passed "/usr/local/myapp/help" and the current wxLocale is
	60	set to be "de", then look in "/usr/local/myapp/help/de/"
	61	first and fall back to "/usr/local/myapp/help" if that
	62	doesn't exist.
	63
	64	@param dir
	65	directory name where to fine the help files
	66
	67	@return @true on success
	68	*/
	69	virtual bool Initialize(const wxString& dir);
	70
	71	/**
	72	If file is "", reloads file given in Initialize.
	73
	74	@param file
	75	Name of help directory.
	76
	77	@return @true on success
	78	*/
	79	virtual bool LoadFile(const wxString& file = wxEmptyString);
	80
	81	/**
	82	Display list of all help entries.
	83
	84	@return @true on success
	85	*/
	86	virtual bool DisplayContents(void);
	87
	88	/**
	89	Display help for id sectionNo.
	90
	91	@return @true on success
	92	*/
	93	virtual bool DisplaySection(int sectionNo);
	94
	95	/**
	96	Display help for id sectionNo -- identical with DisplaySection().
	97
	98	@return @true on success
	99	*/
	100	virtual bool DisplaySection(const wxString& section);
	101
	102	/**
	103	Display help for URL (using DisplayHelp) or keyword (using KeywordSearch)
	104
	105	@return @true on success
	106	*/
	107	virtual bool DisplayBlock(long blockNo);
	108
	109	/**
	110	Search comment/documentation fields in map file and present a
	111	list to chose from.
	112
	113	@param k
	114	string to search for, empty string will list all entries
45a591fa VZ	115
	116	@param mode
	117	optional parameter allows the search the index (wxHELP_SEARCH_INDEX)
	118	but this currently only supported by the wxHtmlHelpController.
5c7b5061 FM	119
	120	@return @true on success
	121	*/
	122	virtual bool KeywordSearch(const wxString& k,
	123	wxHelpSearchMode mode = wxHELP_SEARCH_ALL);
	124
	125	/**
	126	Does nothing.
	127	*/
	128	virtual bool Quit();
	129
	130	/**
	131	Does nothing.
	132	*/
	133	virtual void OnQuit();
	134
	135	/**
	136	Call the browser using a relative URL.
	137	*/
	138	virtual bool DisplayHelp(const wxString &) ;
	139
	140	/**
	141	Allows one to override the default settings for the help frame.
	142	*/
	143	virtual void SetFrameParameters(const wxString& title,
	144	const wxSize& size,
	145	const wxPoint& pos = wxDefaultPosition,
	146	bool newFrameEachTime = false);
	147
	148	/**
	149	Obtains the latest settings used by the help frame and the help frame.
	150	*/
	151	virtual wxFrame GetFrameParameters(wxSize size = NULL,
	152	wxPoint *pos = NULL,
	153	bool *newFrameEachTime = NULL);
	154	};
	155