X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e37870dd38374cce7ca0fe0fabf2070ebc8218b3..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/html/htmlwin.h diff --git a/interface/wx/html/htmlwin.h b/interface/wx/html/htmlwin.h index 0e88ed1eb3..330ff938d7 100644 --- a/interface/wx/html/htmlwin.h +++ b/interface/wx/html/htmlwin.h @@ -2,27 +2,132 @@ // Name: html/htmlwin.h // Purpose: interface of wxHtmlWindow // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// 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 wxHtmlWindow is probably the only class you will directly use unless you want to do something special (like adding new tag handlers or MIME filters). - The purpose of this class is to display HTML pages (either local file or - downloaded via HTTP protocol) in a window. + The purpose of this class is to display rich content pages (either local file or + downloaded via HTTP protocol) in a window based on a subset of the HTML standard. The width of the window is constant - given in the constructor - and virtual height is changed dynamically depending on page size. - Once the window is created you can set its content by calling SetPage(text), - LoadPage(filename) or wxHtmlWindow::LoadFile. + Once the window is created you can set its content by calling SetPage() with raw HTML, + LoadPage() with a wxFileSystem location or LoadFile() with a filename. @note - wxHtmlWindow uses the wxImage class for displaying images. - Don't forget to initialize all image formats you need before loading any page! - (See ::wxInitAllImageHandlers and wxImage::AddHandler.) + If you want complete HTML/CSS support as well as a Javascript engine, see instead + wxWebView. + + @note + wxHtmlWindow uses the wxImage class for displaying images, as such you need to + initialize the handlers for any image formats you use before loading a page. + See ::wxInitAllImageHandlers and wxImage::AddHandler. @beginStyleTable @style{wxHW_SCROLLBAR_NEVER} @@ -49,7 +154,7 @@ @see wxHtmlLinkEvent, wxHtmlCellEvent */ -class wxHtmlWindow : public wxScrolledWindow +class wxHtmlWindow : public wxScrolledWindow, public wxHtmlWindowInterface { public: /** @@ -108,7 +213,7 @@ public: wxString GetOpenedPage() const; /** - Returns title of the opened page or wxEmptyString if current page does not + Returns title of the opened page or wxEmptyString if the current page does not contain \ tag. */ wxString GetOpenedPageTitle() const; @@ -119,20 +224,20 @@ public: wxFrame* GetRelatedFrame() const; /** - Moves back to the previous page. - (each page displayed using LoadPage() is stored in history list.) + Moves back to the previous page. Only pages displayed using LoadPage() + are stored in history list. */ bool HistoryBack(); /** Returns @true if it is possible to go back in the history - (i.e. HistoryBack() won't fail). + i.e. HistoryBack() won't fail. */ bool HistoryCanBack(); /** Returns @true if it is possible to go forward in the history - (i.e. HistoryBack() won't fail). + i.e. HistoryForward() won't fail. */ bool HistoryCanForward(); @@ -142,12 +247,13 @@ public: void HistoryClear(); /** - Moves to next page in history. + Moves to next page in history. Only pages displayed using LoadPage() + are stored in history list. */ bool HistoryForward(); /** - Loads HTML page from file and displays it. + Loads an HTML page from a file and displays it. @return @false if an error occurred, @true otherwise @@ -156,12 +262,13 @@ public: bool LoadFile(const wxFileName& filename); /** - Unlike SetPage() this function first loads HTML page from @a location - and then displays it. See example: + Unlike SetPage() this function first loads the HTML page from @a location + and then displays it. @param location - The address of document. - See wxFileSystem for details on address format and behaviour of "opener". + The address of the document. + See the @ref overview_fs for details on the address format + and wxFileSystem for a description of how the file is opened. @return @false if an error occurred, @true otherwise @@ -258,8 +365,8 @@ public: void SelectWord(const wxPoint& pos); /** - Returns current selection as plain text. - Returns empty string if no text is currently selected. + Returns the current selection as plain text. + Returns an empty string if no text is currently selected. */ wxString SelectionToText(); @@ -292,8 +399,7 @@ public: const wxString& fixed_face = wxEmptyString); /** - Sets HTML page and display it. This won't @b load the page!! - It will display the @e source. See example: + Sets the source of a page and displays it, for example: @code htmlwin -> SetPage("Hello, world!"); @endcode @@ -301,7 +407,7 @@ public: If you want to load a document from some location use LoadPage() instead. @param source - The HTML document source to be displayed. + The HTML to be displayed. @return @false if an error occurred, @true otherwise. */ @@ -359,7 +465,7 @@ public: */ virtual void WriteCustomization(wxConfigBase* cfg, wxString path = wxEmptyString); - + protected: /** @@ -404,6 +510,11 @@ protected: +wxEventType wxEVT_HTML_CELL_CLICKED; +wxEventType wxEVT_HTML_CELL_HOVER; +wxEventType wxEVT_HTML_LINK_CLICKED; + + /** @class wxHtmlLinkEvent