Fixes and tweaks and additions to the wxHtml docs for Phoenix

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@72858 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/help.h

@@ -108,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) = 0;;
+    virtual bool DisplaySection(int sectionNo) = 0;
 
     /**
         Displays the text in a popup window, if possible.

interface/wx/html/helpctrl.h

@@ -6,6 +6,24 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+#define wxID_HTML_HELPFRAME   (wxID_HIGHEST + 1)
+
+/// This style indicates that the window is
+/// embedded in the application and must not be
+/// destroyed by the help controller.
+#define wxHF_EMBEDDED                0x00008000
+
+/// Create a dialog for the help window.
+#define wxHF_DIALOG                  0x00010000
+
+/// Create a frame for the help window.
+#define wxHF_FRAME                   0x00020000
+
+/// Make the dialog modal when displaying help.
+#define wxHF_MODAL                   0x00040000
+
+
+
 /**
     @class wxHtmlHelpController
 
@@ -228,6 +246,31 @@ public:
     virtual void WriteCustomization(wxConfigBase* cfg,
                                     const wxString& path = wxEmptyString);
 
+    /**
+       Get the current help window
+    */
+    wxHtmlHelpWindow* GetHelpWindow();
+
+    /**
+       Set the help window to be managed by this controller.  This makes it
+    possible to have a help window that might not be in a wxHtmlHelpFrame or
+    dialog but is embedded in some other window in the application.  Be sure
+    to use the wxHF_EMBEDDED style in this case.
+    */
+    void SetHelpWindow(wxHtmlHelpWindow* helpWindow);
+
+    /**
+       Returns the current help frame.  (May be NULL.)
+    */
+    wxHtmlHelpFrame* GetFrame();
+
+    /**
+       Returns the current help dialog. (May be NULL.)
+    */
+    wxHtmlHelpDialog* GetDialog();
+
+
+    
 protected:
 
     /**

interface/wx/html/helpdata.h

@@ -6,6 +6,69 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    @class wxHtmlBookRecord
+
+    Helper class for wxHtmlHelpData
+*/
+class wxHtmlBookRecord
+{
+public:
+    wxHtmlBookRecord(const wxString& bookfile, const wxString& basepath,
+                     const wxString& title, const wxString& start);
+
+    wxString GetBookFile() const;
+    wxString GetTitle() const;
+    wxString GetStart() const;
+    wxString GetBasePath() const;
+    
+    /* SetContentsRange: store in the bookrecord where in the index/contents lists the
+     * book's records are stored. This to facilitate searching in a specific book.
+     * This code will have to be revised when loading/removing books becomes dynamic.
+     * (as opposed to appending only)
+     * Note that storing index range is pointless, because the index is alphab. sorted. */
+    void SetContentsRange(int start, int end);
+    int GetContentsStart() const;
+    int GetContentsEnd() const;
+
+    void SetTitle(const wxString& title);
+    void SetBasePath(const wxString& path);
+    void SetStart(const wxString& start);
+
+    // returns full filename of page (which is part of the book),
+    // i.e. with book's basePath prepended. If page is already absolute
+    // path, basePath is _not_ prepended.
+    wxString GetFullPath(const wxString &page) const;
+};
+
+
+
+/**
+    @class wxHtmlHelpDataItem
+
+    Helper class for wxHtmlHelpData
+*/
+struct wxHtmlHelpDataItem
+{
+    wxHtmlHelpDataItem();
+
+    int level;
+    wxHtmlHelpDataItem *parent;
+    int id;
+    wxString name;
+    wxString page;
+    wxHtmlBookRecord *book;
+
+    // returns full filename of m_Page, i.e. with book's basePath prepended
+    wxString GetFullPath() const;
+
+    // returns item indented with spaces if it has level>1:
+    wxString GetIndentedName() const;
+};
+
+
+
+
 /**
     @class wxHtmlHelpData
 

interface/wx/html/helpdlg.h

@@ -16,7 +16,7 @@
     @library{wxhtml}
     @category{help,html}
 */
-class wxHtmlHelpDialog : public wxFrame
+class wxHtmlHelpDialog : public wxDialog
 {
 public:
     wxHtmlHelpDialog(wxHtmlHelpData* data = NULL);
@@ -26,7 +26,7 @@ public:
 
         For the possible values of @a style, please see wxHtmlHelpController.
     */
-    wxHtmlHelpDialog(wxWindow* parent, int wxWindowID,
+    wxHtmlHelpDialog(wxWindow* parent, wxWindowID id,
                      const wxString& title = wxEmptyString,
                      int style = wxHF_DEFAULT_STYLE,
                      wxHtmlHelpData* data = NULL);

interface/wx/html/helpfrm.h

@@ -6,6 +6,24 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+/// style flags for the Help Frame
+#define wxHF_TOOLBAR                0x0001
+#define wxHF_CONTENTS               0x0002
+#define wxHF_INDEX                  0x0004
+#define wxHF_SEARCH                 0x0008
+#define wxHF_BOOKMARKS              0x0010
+#define wxHF_OPEN_FILES             0x0020
+#define wxHF_PRINT                  0x0040
+#define wxHF_FLAT_TOOLBAR           0x0080
+#define wxHF_MERGE_BOOKS            0x0100
+#define wxHF_ICONS_BOOK             0x0200
+#define wxHF_ICONS_BOOK_CHAPTER     0x0400
+#define wxHF_ICONS_FOLDER           0x0000 // this is 0 since it is default
+#define wxHF_DEFAULT_STYLE          (wxHF_TOOLBAR | wxHF_CONTENTS | \
+                                     wxHF_INDEX | wxHF_SEARCH | \
+                                     wxHF_BOOKMARKS | wxHF_PRINT)
+
+
 /**
     @class wxHtmlHelpFrame
 
@@ -26,7 +44,7 @@ public:
 
         For the possible values of @a style, please see wxHtmlHelpController.
     */
-    wxHtmlHelpFrame(wxWindow* parent, int wxWindowID,
+    wxHtmlHelpFrame(wxWindow* parent, wxWindowID id,
                     const wxString& title = wxEmptyString,
                     int style = wxHF_DEFAULT_STYLE,
                     wxHtmlHelpData* data = NULL,

interface/wx/html/helpwnd.h

@@ -6,6 +6,40 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+/*!
+ * Command IDs
+ */
+enum
+{
+    //wxID_HTML_HELPFRAME = wxID_HIGHEST + 1,
+    wxID_HTML_PANEL = wxID_HIGHEST + 10,
+    wxID_HTML_BACK,
+    wxID_HTML_FORWARD,
+    wxID_HTML_UPNODE,
+    wxID_HTML_UP,
+    wxID_HTML_DOWN,
+    wxID_HTML_PRINT,
+    wxID_HTML_OPENFILE,
+    wxID_HTML_OPTIONS,
+    wxID_HTML_BOOKMARKSLIST,
+    wxID_HTML_BOOKMARKSADD,
+    wxID_HTML_BOOKMARKSREMOVE,
+    wxID_HTML_TREECTRL,
+    wxID_HTML_INDEXPAGE,
+    wxID_HTML_INDEXLIST,
+    wxID_HTML_INDEXTEXT,
+    wxID_HTML_INDEXBUTTON,
+    wxID_HTML_INDEXBUTTONALL,
+    wxID_HTML_NOTEBOOK,
+    wxID_HTML_SEARCHPAGE,
+    wxID_HTML_SEARCHTEXT,
+    wxID_HTML_SEARCHLIST,
+    wxID_HTML_SEARCHBUTTON,
+    wxID_HTML_SEARCHCHOICE,
+    wxID_HTML_COUNTINFO
+};
+
+
 /**
     @class wxHtmlHelpWindow
 
@@ -46,7 +80,7 @@ public:
     */
     wxHtmlHelpWindow(wxWindow* parent, int wxWindowID,
                      const wxPoint& pos = wxDefaultPosition,
-                     const wxSize& pos = wxDefaultSize,
+                     const wxSize& size = wxDefaultSize,
                      int style = wxTAB_TRAVERSAL|wxBORDER_NONE,
                      int helpStyle = wxHF_DEFAULT_STYLE,
                      wxHtmlHelpData* data = NULL);
@@ -130,6 +164,10 @@ public:
     */
     void RefreshLists();
 
+
+    wxHtmlHelpController* GetController() const;
+    void SetController(wxHtmlHelpController* controller);
+
 protected:
 
     /**

interface/wx/html/htmlcell.h

@@ -7,6 +7,81 @@
 /////////////////////////////////////////////////////////////////////////////
 
 
+/**
+   @class wxHtmlRenderingStyle
+ 
+   wxHtmlSelection is data holder with information about text selection.
+   Selection is defined by two positions (beginning and end of the selection)
+   and two leaf(!) cells at these positions.
+
+   @library{wxhtml}
+   @category{html}
+*/
+class wxHtmlSelection
+{
+public:
+    wxHtmlSelection();
+
+    // this version is used for the user selection defined with the mouse
+    void Set(const wxPoint& fromPos, const wxHtmlCell *fromCell,
+             const wxPoint& toPos, const wxHtmlCell *toCell);
+    void Set(const wxHtmlCell *fromCell, const wxHtmlCell *toCell);
+
+    const wxHtmlCell *GetFromCell() const;
+    const wxHtmlCell *GetToCell() const;
+
+    // these values are in absolute coordinates:
+    const wxPoint& GetFromPos() const;
+    const wxPoint& GetToPos() const;
+
+    // these are From/ToCell's private data
+    void ClearFromToCharacterPos();
+    bool AreFromToCharacterPosSet() const;
+
+    void SetFromCharacterPos (wxCoord pos);
+    void SetToCharacterPos (wxCoord pos);
+    wxCoord GetFromCharacterPos () const;
+    wxCoord GetToCharacterPos () const;
+
+    bool IsEmpty() const;
+};
+
+
+
+enum wxHtmlSelectionState
+{
+    wxHTML_SEL_OUT,     // currently rendered cell is outside the selection
+    wxHTML_SEL_IN,      // ... is inside selection
+    wxHTML_SEL_CHANGING // ... is the cell on which selection state changes
+};
+
+
+/**
+   @class wxHtmlRenderingState
+
+   Selection state is passed to wxHtmlCell::Draw so that it can render itself
+   differently e.g. when inside text selection or outside it.
+
+   @library{wxhtml}
+   @category{html}
+*/
+class wxHtmlRenderingState
+{
+public:
+    wxHtmlRenderingState();
+
+    void SetSelectionState(wxHtmlSelectionState s);
+    wxHtmlSelectionState GetSelectionState() const;
+
+    void SetFgColour(const wxColour& c);
+    const wxColour& GetFgColour() const;
+    void SetBgColour(const wxColour& c);
+    const wxColour& GetBgColour() const;
+    void SetBgMode(int m);
+    int GetBgMode() const;
+};
+
+
 
 /**
     @class wxHtmlRenderingStyle
@@ -69,6 +144,25 @@ public:
 };
 
 
+
+// Flags for wxHtmlCell::FindCellByPos
+enum
+{
+    wxHTML_FIND_EXACT             = 1,
+    wxHTML_FIND_NEAREST_BEFORE    = 2,
+    wxHTML_FIND_NEAREST_AFTER     = 4
+};
+
+
+// Superscript/subscript/normal script mode of a cell
+enum wxHtmlScriptMode
+{
+    wxHTML_SCRIPT_NORMAL,
+    wxHTML_SCRIPT_SUB,
+    wxHTML_SCRIPT_SUP
+};
+
+
 /**
     @class wxHtmlCell
 

interface/wx/html/htmldefs.h

@@ -0,0 +1,79 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        html/htmldefs.h
+// Purpose:     constants for wxhtml library
+// Author:      wxWidgets team
+// RCS-ID:      $Id$
+// Licence:     wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+
+//--------------------------------------------------------------------------------
+// ALIGNMENTS
+//                  Describes alignment of text etc. in containers
+//--------------------------------------------------------------------------------
+
+#define wxHTML_ALIGN_LEFT            0x0000
+#define wxHTML_ALIGN_RIGHT           0x0002
+#define wxHTML_ALIGN_JUSTIFY         0x0010
+
+#define wxHTML_ALIGN_TOP             0x0004
+#define wxHTML_ALIGN_BOTTOM          0x0008
+
+#define wxHTML_ALIGN_CENTER          0x0001
+
+
+
+//--------------------------------------------------------------------------------
+// COLOR MODES
+//                  Used by wxHtmlColourCell to determine clr of what is changing
+//--------------------------------------------------------------------------------
+
+#define wxHTML_CLR_FOREGROUND                0x0001
+#define wxHTML_CLR_BACKGROUND                0x0002
+#define wxHTML_CLR_TRANSPARENT_BACKGROUND    0x0004
+
+
+
+//--------------------------------------------------------------------------------
+// UNITS
+//                  Used to specify units
+//--------------------------------------------------------------------------------
+
+#define wxHTML_UNITS_PIXELS          0x0001
+#define wxHTML_UNITS_PERCENT         0x0002
+
+
+
+//--------------------------------------------------------------------------------
+// INDENTS
+//                  Used to specify indetation relatives
+//--------------------------------------------------------------------------------
+
+#define wxHTML_INDENT_LEFT           0x0010
+#define wxHTML_INDENT_RIGHT          0x0020
+#define wxHTML_INDENT_TOP            0x0040
+#define wxHTML_INDENT_BOTTOM         0x0080
+
+#define wxHTML_INDENT_HORIZONTAL     (wxHTML_INDENT_LEFT | wxHTML_INDENT_RIGHT)
+#define wxHTML_INDENT_VERTICAL       (wxHTML_INDENT_TOP | wxHTML_INDENT_BOTTOM)
+#define wxHTML_INDENT_ALL            (wxHTML_INDENT_VERTICAL | wxHTML_INDENT_HORIZONTAL)
+
+
+
+
+//--------------------------------------------------------------------------------
+// FIND CONDITIONS
+//                  Identifiers of wxHtmlCell's Find() conditions
+//--------------------------------------------------------------------------------
+
+#define wxHTML_COND_ISANCHOR              1
+        // Finds the anchor of 'param' name (pointer to wxString).
+
+#define wxHTML_COND_ISIMAGEMAP            2
+        // Finds imagemap of 'param' name (pointer to wxString).
+    // (used exclusively by m_image.cpp)
+
+#define wxHTML_COND_USER              10000
+        // User-defined conditions should start from this number
+
+

interface/wx/html/htmlpars.h

@@ -6,6 +6,15 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+enum wxHtmlURLType
+{
+    wxHTML_URL_PAGE,
+    wxHTML_URL_IMAGE,
+    wxHTML_URL_OTHER
+};
+
+
+
 /**
     @class wxHtmlTagHandler
 
@@ -75,6 +84,14 @@ protected:
     */
     void ParseInner(const wxHtmlTag& tag);
 
+    /**
+       Parses given source as if it was tag's inner code (see
+       wxHtmlParser::GetInnerSource).  Unlike ParseInner(), this method lets
+       you specify the source code to parse. This is useful when you need to
+       modify the inner text before parsing.
+    */
+    void ParseInnerSource(const wxString& source);
+
     /**
         This attribute is used to access parent parser. It is protected so that
         it can't be accessed by user but can be accessed from derived classes.

interface/wx/html/htmlwin.h

@@ -6,6 +6,108 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+// wxHtmlWindow flags:
+#define wxHW_SCROLLBAR_NEVER    0x0002
+#define wxHW_SCROLLBAR_AUTO     0x0004
+#define wxHW_NO_SELECTION       0x0008
+
+#define wxHW_DEFAULT_STYLE      wxHW_SCROLLBAR_AUTO
+
+
+/// Enum for wxHtmlWindow::OnOpeningURL and wxHtmlWindowInterface::OnOpeningURL
+enum wxHtmlOpeningStatus
+{
+    /// Open the requested URL
+    wxHTML_OPEN,
+    /// Do not open the URL
+    wxHTML_BLOCK,
+    /// Redirect to another URL (returned from OnOpeningURL)
+    wxHTML_REDIRECT
+};
+
+
+/**
+   @class wxHtmlWindowInterface
+   
+   Abstract interface to a HTML rendering window (such as wxHtmlWindow or
+   wxHtmlListBox) that is passed to wxHtmlWinParser. It encapsulates all
+   communication from the parser to the window.
+ */
+class wxHtmlWindowInterface
+{
+public:
+    /// Ctor
+    wxHtmlWindowInterface();
+    virtual ~wxHtmlWindowInterface();
+
+    /**
+        Called by the parser to set window's title to given text.
+     */
+    virtual void SetHTMLWindowTitle(const wxString& title) = 0;
+
+    /**
+        Called when a link is clicked.
+
+        @param link information about the clicked link
+     */
+    virtual void OnHTMLLinkClicked(const wxHtmlLinkInfo& link) = 0;
+
+    /**
+        Called when the parser needs to open another URL (e.g. an image).
+
+        @param type     Type of the URL request (e.g. image)
+        @param url      URL the parser wants to open
+        @param redirect If the return value is wxHTML_REDIRECT, then the
+                        URL to redirect to will be stored in this variable
+                        (the pointer must never be NULL)
+
+        @return indicator of how to treat the request
+     */
+    virtual wxHtmlOpeningStatus OnHTMLOpeningURL(wxHtmlURLType type,
+                                                 const wxString& url,
+                                                 wxString *redirect) const = 0;
+
+    /**
+        Converts coordinates @a pos relative to given @a cell to
+        physical coordinates in the window.
+     */
+    virtual wxPoint HTMLCoordsToWindow(wxHtmlCell *cell,
+                                       const wxPoint& pos) const = 0;
+
+    /// Returns the window used for rendering (may be NULL).
+    virtual wxWindow* GetHTMLWindow() = 0;
+
+    /// Returns background colour to use by default.
+    virtual wxColour GetHTMLBackgroundColour() const = 0;
+
+    /// Sets window's background to colour @a clr.
+    virtual void SetHTMLBackgroundColour(const wxColour& clr) = 0;
+
+    /// Sets window's background to given bitmap.
+    virtual void SetHTMLBackgroundImage(const wxBitmap& bmpBg) = 0;
+
+    /// Sets status bar text.
+    virtual void SetHTMLStatusText(const wxString& text) = 0;
+
+    /// Type of mouse cursor
+    enum HTMLCursor
+    {
+        /// Standard mouse cursor (typically an arrow)
+        HTMLCursor_Default,
+        /// Cursor shown over links
+        HTMLCursor_Link,
+        /// Cursor shown over selectable text
+        HTMLCursor_Text
+    };
+
+    /**
+        Returns mouse cursor of given @a type.
+     */
+    virtual wxCursor GetHTMLCursor(wxHtmlWindowInterface::HTMLCursor type) const = 0;
+};
+
+
+
 /**
     @class wxHtmlWindow
 
@@ -53,7 +155,7 @@
 
     @see wxHtmlLinkEvent, wxHtmlCellEvent
 */
-class wxHtmlWindow : public wxScrolledWindow
+class wxHtmlWindow : public wxScrolledWindow, public wxHtmlWindowInterface
 {
 public:
     /**
@@ -364,7 +466,7 @@ public:
     */
     virtual void WriteCustomization(wxConfigBase* cfg,
                                     wxString path = wxEmptyString);
-
+    
 protected:
 
     /**
@@ -409,6 +511,11 @@ protected:
 
 
 
+wxEventType wxEVT_COMMAND_HTML_CELL_CLICKED;
+wxEventType wxEVT_COMMAND_HTML_CELL_HOVER;
+wxEventType wxEVT_COMMAND_HTML_LINK_CLICKED;
+
+
 /**
     @class wxHtmlLinkEvent
 

interface/wx/html/htmprint.h

@@ -348,6 +348,12 @@ private:
 };
 
 
+enum {
+    wxPAGE_ODD,
+    wxPAGE_EVEN,
+    wxPAGE_ALL
+};
+
 
 /**
     @class wxHtmlPrintout

interface/wx/html/winpars.h

@@ -214,9 +214,8 @@ public:
         (You should always test if it is non-@NULL.
         For example @c TITLE handler sets window title only if some window is
         associated, otherwise it does nothing.
-        @deprecated use GetWindowInterface()->GetHTMLWindow() instead
+   */
-    */
+    wxHtmlWindowInterface* GetWindowInterface();
-    wxHtmlWindow* GetWindow();
 
     /**
         Opens new container and returns pointer to it (see @ref overview_html_cells).