From 90f011dc6c50fe58172d90833d94e3b375ad0a08 Mon Sep 17 00:00:00 2001 From: Robin Dunn Date: Thu, 1 Nov 2012 22:56:13 +0000 Subject: [PATCH] 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 | 2 +- interface/wx/html/helpctrl.h | 43 ++++++++++++++ interface/wx/html/helpdata.h | 63 ++++++++++++++++++++ interface/wx/html/helpdlg.h | 4 +- interface/wx/html/helpfrm.h | 20 ++++++- interface/wx/html/helpwnd.h | 40 ++++++++++++- interface/wx/html/htmlcell.h | 94 +++++++++++++++++++++++++++++ interface/wx/html/htmldefs.h | 79 +++++++++++++++++++++++++ interface/wx/html/htmlpars.h | 17 ++++++ interface/wx/html/htmlwin.h | 111 ++++++++++++++++++++++++++++++++++- interface/wx/html/htmprint.h | 6 ++ interface/wx/html/winpars.h | 5 +- 12 files changed, 474 insertions(+), 10 deletions(-) create mode 100644 interface/wx/html/htmldefs.h diff --git a/interface/wx/help.h b/interface/wx/help.h index abaf35a33c..b3199690f8 100644 --- a/interface/wx/help.h +++ b/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. diff --git a/interface/wx/html/helpctrl.h b/interface/wx/html/helpctrl.h index 0d5bece059..a784927cdf 100644 --- a/interface/wx/html/helpctrl.h +++ b/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: /** diff --git a/interface/wx/html/helpdata.h b/interface/wx/html/helpdata.h index 4360c98e8c..ffcb3c528f 100644 --- a/interface/wx/html/helpdata.h +++ b/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 diff --git a/interface/wx/html/helpdlg.h b/interface/wx/html/helpdlg.h index a6f32a938b..f121301e41 100644 --- a/interface/wx/html/helpdlg.h +++ b/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); diff --git a/interface/wx/html/helpfrm.h b/interface/wx/html/helpfrm.h index 73f735380c..e61e80aafb 100644 --- a/interface/wx/html/helpfrm.h +++ b/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, diff --git a/interface/wx/html/helpwnd.h b/interface/wx/html/helpwnd.h index b58b21d084..50049069c6 100644 --- a/interface/wx/html/helpwnd.h +++ b/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: /** diff --git a/interface/wx/html/htmlcell.h b/interface/wx/html/htmlcell.h index 86351e6055..4f23a89c14 100644 --- a/interface/wx/html/htmlcell.h +++ b/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 diff --git a/interface/wx/html/htmldefs.h b/interface/wx/html/htmldefs.h new file mode 100644 index 0000000000..712056d147 --- /dev/null +++ b/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 + + diff --git a/interface/wx/html/htmlpars.h b/interface/wx/html/htmlpars.h index 28e7bc690f..1fad764ba9 100644 --- a/interface/wx/html/htmlpars.h +++ b/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. diff --git a/interface/wx/html/htmlwin.h b/interface/wx/html/htmlwin.h index 9ad78baac9..4b6d970e64 100644 --- a/interface/wx/html/htmlwin.h +++ b/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 diff --git a/interface/wx/html/htmprint.h b/interface/wx/html/htmprint.h index 00b1a44ff2..6b6de4a0f6 100644 --- a/interface/wx/html/htmprint.h +++ b/interface/wx/html/htmprint.h @@ -348,6 +348,12 @@ private: }; +enum { + wxPAGE_ODD, + wxPAGE_EVEN, + wxPAGE_ALL +}; + /** @class wxHtmlPrintout diff --git a/interface/wx/html/winpars.h b/interface/wx/html/winpars.h index 11b51bd834..36cc0cf97b 100644 --- a/interface/wx/html/winpars.h +++ b/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 - */ - wxHtmlWindow* GetWindow(); + */ + wxHtmlWindowInterface* GetWindowInterface(); /** Opens new container and returns pointer to it (see @ref overview_html_cells). -- 2.45.2