X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/551266a969c28562e73c96941f2c7d83fa3eb282..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/html/htmlwin.h diff --git a/interface/wx/html/htmlwin.h b/interface/wx/html/htmlwin.h index b15356dda6..330ff938d7 100644 --- a/interface/wx/html/htmlwin.h +++ b/interface/wx/html/htmlwin.h @@ -2,25 +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). + 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 width - of the window is constant - given in the constructor - and virtual height + 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 - @ref wxHtmlWindow::setpage SetPage(text), - @ref wxHtmlWindow::loadpage 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 + 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} @@ -32,38 +139,47 @@ Don't allow the user to select text. @endStyleTable + + @beginEventEmissionTable{wxHtmlCellEvent, wxHtmlLinkEvent} + @event{EVT_HTML_CELL_CLICKED(id, func)} + A wxHtmlCell was clicked. + @event{EVT_HTML_CELL_HOVER(id, func)} + The mouse passed over a wxHtmlCell. + @event{EVT_HTML_LINK_CLICKED(id, func)} + A wxHtmlCell which contains an hyperlink was clicked. + @endEventTable + @library{wxhtml} @category{html} @see wxHtmlLinkEvent, wxHtmlCellEvent */ -class wxHtmlWindow : public wxScrolledWindow +class wxHtmlWindow : public wxScrolledWindow, public wxHtmlWindowInterface { public: - //@{ /** - Constructor. The parameters are the same as wxScrolled::wxScrolled() - constructor. - - @param style - Window style. See wxHtmlWindow. + Default ctor. */ wxHtmlWindow(); - wxHtmlWindow(wxWindow parent, wxWindowID id = -1, + + /** + Constructor. + The parameters are the same as wxScrolled::wxScrolled() constructor. + */ + wxHtmlWindow(wxWindow *parent, wxWindowID id = wxID_ANY, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxHW_DEFAULT_STYLE, const wxString& name = "htmlWindow"); - //@} /** - Adds @ref overview_filters "input filter" to the static list of available + Adds @ref overview_html_filters "input filter" to the static list of available filters. These filters are present by default: - @c text/html MIME type - @c image/* MIME types - Plain Text filter (this filter is used if no other filter matches) + - @c text/html MIME type + - @c image/* MIME types + - Plain Text filter (this filter is used if no other filter matches) */ - static void AddFilter(wxHtmlFilter filter); + static void AddFilter(wxHtmlFilter* filter); /** Appends HTML fragment to currently displayed text and refreshes the window. @@ -77,29 +193,28 @@ public: /** Returns pointer to the top-level container. - See also: @ref overview_cells "Cells Overview", - @ref overview_printing + + @see @ref overview_html_cells, @ref overview_printing */ wxHtmlContainerCell* GetInternalRepresentation() const; /** - Returns anchor within currently opened page - (see wxHtmlWindow::GetOpenedPage). - If no page is opened or if the displayed page wasn't - produced by call to LoadPage, empty string is returned. + Returns anchor within currently opened page (see wxHtmlWindow::GetOpenedPage). + If no page is opened or if the displayed page wasn't produced by call to + LoadPage(), empty string is returned. */ wxString GetOpenedAnchor() const; /** - Returns full location of the opened page. If no page is opened or if the - displayed page wasn't - produced by call to LoadPage, empty string is returned. + Returns full location of the opened page. + If no page is opened or if the displayed page wasn't produced by call to + LoadPage(), empty string is returned. */ wxString GetOpenedPage() const; /** - Returns title of the opened page or wxEmptyString if current page does not - contain @c TITLE tag. + Returns title of the opened page or wxEmptyString if the current page does not + contain \ tag. */ wxString GetOpenedPageTitle() const; @@ -109,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). + Returns @true if it is possible to go back in the history + 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). + Returns @true if it is possible to go forward in the history + i.e. HistoryForward() won't fail. */ bool HistoryCanForward(); @@ -132,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 @@ -146,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 @@ -160,87 +277,65 @@ public: virtual bool LoadPage(const wxString& location); /** - Called when user clicks on hypertext link. Default behaviour is to emit a - wxHtmlLinkEvent and, if the event was not processed - or skipped, call LoadPage() and do nothing else. + Called when user clicks on hypertext link. + Default behaviour is to emit a wxHtmlLinkEvent and, if the event was not + processed or skipped, call LoadPage() and do nothing else. + Overloading this method is deprecated; intercept the event instead. + Also see wxHtmlLinkInfo. */ virtual void OnLinkClicked(const wxHtmlLinkInfo& link); /** Called when an URL is being opened (either when the user clicks on a link or - an image is loaded). The URL will be opened only if OnOpeningURL returns - @c wxHTML_OPEN. This method is called by - wxHtmlParser::OpenURL. - You can override OnOpeningURL to selectively block some - URLs (e.g. for security reasons) or to redirect them elsewhere. Default - behaviour is to always return @c wxHTML_OPEN. + an image is loaded). The URL will be opened only if OnOpeningURL() returns + @c wxHTML_OPEN. This method is called by wxHtmlParser::OpenURL. + + You can override OnOpeningURL() to selectively block some URLs + (e.g. for security reasons) or to redirect them elsewhere. + Default behaviour is to always return @c wxHTML_OPEN. @param type Indicates type of the resource. Is one of - - - - - - - wxHTML_URL_PAGE - - - - - Opening a HTML page. - - - - - - wxHTML_URL_IMAGE - - - - - Opening an image. - - - - - - wxHTML_URL_OTHER - - - - - Opening a resource that doesn't fall into - any other category. + - wxHTML_URL_PAGE: Opening a HTML page. + - wxHTML_URL_IMAGE: Opening an image. + - wxHTML_URL_OTHER: Opening a resource that doesn't fall into + any other category. @param url URL being opened. @param redirect Pointer to wxString variable that must be filled with an - URL if OnOpeningURL returns wxHTML_REDIRECT. + URL if OnOpeningURL() returns @c wxHTML_REDIRECT. + + The return value is: + - wxHTML_OPEN: Open the URL. + - wxHTML_BLOCK: Deny access to the URL, wxHtmlParser::OpenURL will return @NULL. + - wxHTML_REDIRECT: Don't open url, redirect to another URL. + OnOpeningURL() must fill *redirect with the new URL. + OnOpeningURL() will be called again on returned URL. */ virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type, const wxString& url, wxString* redirect) const; /** - Called on parsing @c TITLE tag. + Called on parsing \ tag. */ virtual void OnSetTitle(const wxString& title); /** This reads custom settings from wxConfig. It uses the path 'path' if given, otherwise it saves info into currently selected path. - The values are stored in sub-path @c wxHtmlWindow - Read values: all things set by SetFonts, SetBorders. + The values are stored in sub-path @c wxHtmlWindow. + Read values: all things set by SetFonts(), SetBorders(). @param cfg wxConfig from which you want to read the configuration. @param path Optional path in config tree. If not given current path is used. */ - virtual void ReadCustomization(wxConfigBase cfg, + virtual void ReadCustomization(wxConfigBase* cfg, wxString path = wxEmptyString); /** @@ -261,24 +356,24 @@ public: void SelectLine(const wxPoint& pos); /** - Selects the word at position @e pos. Note that @e pos - is relative to the top of displayed page, not to window's origin, use - wxScrolled::CalcUnscrolledPosition() - to convert physical coordinate. + Selects the word at position @a pos. + Note that @a pos is relative to the top of displayed page, not to window's + origin, use wxScrolled::CalcUnscrolledPosition() to convert physical coordinate. @see SelectAll(), SelectLine() */ 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(); /** - This function sets the space between border of window and HTML contents. See - image: + This function sets the space between border of window and HTML contents. + See image: + @image html htmlwin_border.png @param b indentation from borders in pixels @@ -286,50 +381,49 @@ public: void SetBorders(int b); /** - This function sets font sizes and faces. + This function sets font sizes and faces. See wxHtmlDCRenderer::SetFonts + for detailed description. + + @see SetSize() + */ + void SetFonts(const wxString& normal_face, const wxString& fixed_face, + const int* sizes = NULL); - @param normal_face - This is face name for normal (i.e. non-fixed) font. - It can be either empty string (then the default face is chosen) or - platform-specific face name. Examples are "helvetica" under Unix or - "Times New Roman" under Windows. - @param fixed_face - The same thing for fixed face ( TT../TT ) - @param sizes - This is an array of 7 items of int type. - The values represent size of font with HTML size from -2 to +4 - ( FONT SIZE=-2 to FONT SIZE=+4 ). Default sizes are used if sizes - is @NULL. + /** + Sets default font sizes and/or default font size. + See wxHtmlDCRenderer::SetStandardFonts for detailed description. + @see SetFonts() */ - void SetFonts(const wxString& normal_face, - const wxString& fixed_face, - const int sizes = NULL); + void SetStandardFonts(int size = -1, + const wxString& normal_face = wxEmptyString, + 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 - If you want to load a document from some location use - LoadPage() instead. + 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. */ virtual bool SetPage(const wxString& source); /** - Sets the frame in which page title will be displayed. @a format is format of - frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s. This - %s is substituted with HTML page title. + Sets the frame in which page title will be displayed. + @a format is the format of the frame title, e.g. "HtmlHelp : %s". + It must contain exactly one %s. + This %s is substituted with HTML page title. */ void SetRelatedFrame(wxFrame* frame, const wxString& format); /** - @b After calling SetRelatedFrame(), - this sets statusbar slot where messages will be displayed. - (Default is -1 = no messages.) + @b After calling SetRelatedFrame(), this sets statusbar slot where messages + will be displayed. (Default is -1 = no messages.) @param index Statusbar slot number (0..n) @@ -356,66 +450,83 @@ public: wxString ToText(); /** - Saves custom settings into wxConfig. It uses the path 'path' - if given, otherwise it saves info into currently selected path. - Regardless of whether the path is given or not, the function creates sub-path - @c wxHtmlWindow. - Saved values: all things set by SetFonts, SetBorders. + Saves custom settings into wxConfig. + It uses the path 'path' if given, otherwise it saves info into currently + selected path. + Regardless of whether the path is given or not, the function creates + sub-path @c wxHtmlWindow. + + Saved values: all things set by SetFonts(), SetBorders(). @param cfg wxConfig to which you want to save the configuration. @param path Optional path in config tree. If not given, the current path is used. */ - virtual void WriteCustomization(wxConfigBase cfg, + virtual void WriteCustomization(wxConfigBase* cfg, wxString path = wxEmptyString); - + protected: /** This method is called when a mouse button is clicked inside wxHtmlWindow. - The default behaviour is to emit a wxHtmlCellEvent - and, if the event was not processed or skipped, call - OnLinkClicked() if the cell contains an + The default behaviour is to emit a wxHtmlCellEvent and, if the event was + not processed or skipped, call OnLinkClicked() if the cell contains an hypertext link. + Overloading this method is deprecated; intercept the event instead. @param cell The cell inside which the mouse was clicked, always a simple (i.e. non-container) cell - @param x, y - The logical coordinates of the click point + @param x + The logical x coordinate of the click point + @param y + The logical y coordinate of the click point @param event The mouse event containing other information about the click @return @true if a link was clicked, @false otherwise. */ - virtual bool OnCellClicked(wxHtmlCell cell, wxCoord x, wxCoord y, + virtual bool OnCellClicked(wxHtmlCell* cell, wxCoord x, wxCoord y, const wxMouseEvent& event); /** This method is called when a mouse moves over an HTML cell. Default behaviour is to emit a wxHtmlCellEvent. + Overloading this method is deprecated; intercept the event instead. @param cell The cell inside which the mouse is currently, always a simple (i.e. non-container) cell - @param x, y - The logical coordinates of the click point + @param x + The logical x coordinate of the click point + @param y + The logical y coordinate of the click point */ - virtual void OnCellMouseHover(wxHtmlCell cell, wxCoord x, wxCoord y); + virtual void OnCellMouseHover(wxHtmlCell* cell, wxCoord x, wxCoord y); }; +wxEventType wxEVT_HTML_CELL_CLICKED; +wxEventType wxEVT_HTML_CELL_HOVER; +wxEventType wxEVT_HTML_LINK_CLICKED; + + /** @class wxHtmlLinkEvent This event class is used for the events generated by wxHtmlWindow. + @beginEventTable{wxHtmlLinkEvent} + @event{EVT_HTML_LINK_CLICKED(id, func)} + User clicked on an hyperlink. + @endEventTable + @library{wxhtml} - @category{FIXME} + @category{html} */ class wxHtmlLinkEvent : public wxCommandEvent { @@ -423,13 +534,13 @@ public: /** The constructor is not normally used by the user code. */ - wxHyperlinkEvent(int id, const wxHtmlLinkInfo& linkinfo); + wxHtmlLinkEvent(int id, const wxHtmlLinkInfo& linkinfo); /** - Returns the wxHtmlLinkInfo which contains info about the cell clicked and the - hyperlink it contains. + Returns the wxHtmlLinkInfo which contains info about the cell clicked + and the hyperlink it contains. */ - const wxHtmlLinkInfo GetLinkInfo() const; + const wxHtmlLinkInfo& GetLinkInfo() const; }; @@ -439,8 +550,16 @@ public: This event class is used for the events generated by wxHtmlWindow. + @beginEventTable{wxHtmlCellEvent} + @event{EVT_HTML_CELL_HOVER(id, func)} + User moved the mouse over a wxHtmlCell. + @event{EVT_HTML_CELL_CLICKED(id, func)} + User clicked on a wxHtmlCell. When handling this event, remember to use + wxHtmlCell::SetLinkClicked(true) if the cell contains a link. + @endEventTable + @library{wxhtml} - @category{FIXME} + @category{html} */ class wxHtmlCellEvent : public wxCommandEvent { @@ -450,7 +569,8 @@ public: */ wxHtmlCellEvent(wxEventType commandType, int id, wxHtmlCell* cell, - const wxPoint& point); + const wxPoint& point, + const wxMouseEvent& ev); /** Returns the wxHtmlCellEvent associated with the event. @@ -458,8 +578,7 @@ public: wxHtmlCell* GetCell() const; /** - Returns @true if @ref setlinkclicked() SetLinkClicked(@true) has previously - been called; + Returns @true if SetLinkClicked(@true) has previously been called; @false otherwise. */ bool GetLinkClicked() const; @@ -470,12 +589,12 @@ public: wxPoint GetPoint() const; /** - Call this function with @c linkclicked set to @true if the cell which has - been clicked contained a link or - @false otherwise (which is the default). With this function the event handler - can return info to the - wxHtmlWindow which sent the event. + Call this function with @a linkclicked set to @true if the cell which has + been clicked contained a link or @false otherwise (which is the default). + + With this function the event handler can return info to the wxHtmlWindow + which sent the event. */ - bool SetLinkClicked(bool linkclicked); + void SetLinkClicked(bool linkclicked); };