wxWidgets/include/wx/html/helpfrm.h

/////////////////////////////////////////////////////////////////////////////
// Name:        helpfrm.h
// Purpose:     wxHtmlHelpFrame
// Notes:       Based on htmlhelp.cpp, implementing a monolithic 
//              HTML Help controller class,  by Vaclav Slavik
// Author:      Harm van der Heijden and Vaclav Slavik
// Created:
// RCS-ID:
// Copyright:   (c) Harm van der Heijden and Vaclav Slavik
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

#ifndef _WX_HELPFRM_H_
#define _WX_HELPFRM_H_

#ifdef __GNUG__
#pragma interface "helpfrm.h"
#endif

#include "wx/defs.h"

#if wxUSE_HTML

#include "helpdata.h"
#include "wx/window.h"
#include "wx/frame.h"
#include "wx/config.h"
#include "wx/splitter.h"
#include "wx/notebook.h"
#include "wx/listbox.h"
#include "wx/choice.h"
#include "wx/html/htmlwin.h"

// style flags for the Help Frame
const int wxHF_TOOLBAR = 1;
const int wxHF_CONTENTS = 2;
const int wxHF_INDEX = 4;
const int wxHF_SEARCH = 8;
const int wxHF_DEFAULTSTYLE = -1;

// Command IDs :
enum {
    wxID_HTML_PANEL = wxID_HIGHEST + 1,
    wxID_HTML_BACK,
    wxID_HTML_FORWARD,
    wxID_HTML_TREECTRL,
    wxID_HTML_INDEXPAGE,
    wxID_HTML_INDEXLIST,
    wxID_HTML_NOTEBOOK,
    wxID_HTML_SEARCHPAGE,
    wxID_HTML_SEARCHTEXT,
    wxID_HTML_SEARCHLIST,
    wxID_HTML_SEARCHBUTTON,
    wxID_HTML_SEARCHCHOICE,
    wxID_HTML_HELPFRAME // the id of wxHtmlHelpController's helpframe
};

class WXDLLEXPORT wxHtmlHelpFrame : public wxFrame
{
    DECLARE_DYNAMIC_CLASS(wxHtmlHelpFrame)

public:
    wxHtmlHelpFrame(wxHtmlHelpData* data = NULL) { Init(data); }
    wxHtmlHelpFrame(wxWindow* parent, int wxWindowID, 
		    const wxString& title = wxEmptyString,
		    int style = wxHF_DEFAULTSTYLE, wxHtmlHelpData* data = NULL);
    bool Create(wxWindow* parent, wxWindowID id, const wxString& title = wxEmptyString,
		int style = wxHF_DEFAULTSTYLE);
    ~wxHtmlHelpFrame();
    
    wxHtmlHelpData* GetData() { return m_Data; }
    
    void SetTitleFormat(const wxString& format) {
	if (m_HtmlWin) 
	    m_HtmlWin->SetRelatedFrame(this, format);
	m_TitleFormat = format;
    }
    // Sets format of title of the frame. Must contain exactly one "%s"
    // (for title of displayed HTML page)
    
    bool Display(const wxString& x);
    // Displays page x. If not found it will offect the user a choice of 
    // searching books.
    // Looking for the page runs in these steps:
    // 1. try to locate file named x (if x is for example "doc/howto.htm")
    // 2. try to open starting page of book x
    // 3. try to find x in contents (if x is for example "How To ...")
    // 4. try to find x in index (if x is for example "How To ...")
    bool Display(const int id);
    // Alternative version that works with numeric ID.
    // (uses extension to MS format, <param name="ID" value=id>, see docs)
    
    bool DisplayContents();
    // Displays help window and focuses contents.
    
    bool DisplayIndex();
    // Displays help window and focuses index.
    
    bool KeywordSearch(const wxString& keyword);
    // Searches for keyword. Returns TRUE and display page if found, return
    // FALSE otherwise
    // Syntax of keyword is Altavista-like:
    // * words are separated by spaces
    //   (but "\"hello world\"" is only one world "hello world")
    // * word may be pretended by + or -
    //   (+ : page must contain the word ; - : page can't contain the word)
    // * if there is no + or - before the word, + is default
    void RefreshLists(bool show_progress = FALSE);
    // Refreshes Contents and Index tabs
    void CreateContents(bool show_progress = FALSE);
    // Adds items to m_Contents tree control
    void CreateIndex(bool show_progress = FALSE);
    // Adds items to m_IndexList
    void CreateSearch();
    // Add books to search choice panel
    void UseConfig(wxConfigBase *config, const wxString& rootpath = wxEmptyString) {
	m_Config = config; m_ConfigRoot = rootpath;
	ReadCustomization(config, rootpath);
    }
    void ReadCustomization(wxConfigBase *cfg, const wxString& path = wxEmptyString);
    // saves custom settings into cfg config. it will use the path 'path'
    // if given, otherwise it will save info into currently selected path.
    // saved values : things set by SetFonts, SetBorders.
    void WriteCustomization(wxConfigBase *cfg, const wxString& path = wxEmptyString);
    // ...
    void OnToolbar(wxCommandEvent& event);
    void OnContentsSel(wxTreeEvent& event);
    void OnIndexSel(wxCommandEvent& event);
    void OnSearchSel(wxCommandEvent& event);
    void OnSearch(wxCommandEvent& event);
    void OnCloseWindow(wxCloseEvent& event);

    // Images:
    enum {
	IMG_Book = 0,
	IMG_Folder,
	IMG_Page
    };
    
protected:
    wxHtmlHelpData* m_Data;
    bool m_DataCreated; // m_Data created by frame, or supplied?
    wxString m_TitleFormat; // title of the help frame
    // below are various pointers to GUI components
    wxHtmlWindow *m_HtmlWin;
    wxSplitterWindow *m_Splitter;
    wxNotebook *m_NavigPan;
    wxTreeCtrl *m_ContentsBox;
    wxImageList *m_ContentsImageList;
    wxListBox *m_IndexBox;
    wxTextCtrl *m_SearchText;
    wxButton *m_SearchButton;
    wxListBox *m_SearchList; 
    wxChoice *m_SearchChoice;

    struct {
	long x, y, w, h;
	long sashpos;
	bool navig_on;
	int style; // flags given to wxHtmlHelpFrame ctor
	wxString titleformat;
    } m_Cfg;
    // settings (window size, position, sash pos etc..)     
    wxConfigBase *m_Config;
    wxString m_ConfigRoot;

    // pagenumbers of controls in notebook (usually 0,1,2)
    int m_ContentsPage;
    int m_IndexPage;
    int m_SearchPage;
    
protected:
    void Init(wxHtmlHelpData* data = NULL);

    DECLARE_EVENT_TABLE()
};

#endif

#endif