X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/551266a969c28562e73c96941f2c7d83fa3eb282..b5fe7ca67bf3121959a0b5a59afd00c1708f2f03:/interface/wx/html/htmlwin.h diff --git a/interface/wx/html/htmlwin.h b/interface/wx/html/htmlwin.h index b15356dda6..dd08acaa0e 100644 --- a/interface/wx/html/htmlwin.h +++ b/interface/wx/html/htmlwin.h @@ -9,18 +9,20 @@ /** @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 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 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(text), + LoadPage(filename) or wxHtmlWindow::LoadFile. + + @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.) @beginStyleTable @style{wxHW_SCROLLBAR_NEVER} @@ -32,6 +34,16 @@ 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} @@ -40,30 +52,29 @@ class wxHtmlWindow : public wxScrolledWindow { 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 +88,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. + contain \ tag. */ wxString GetOpenedPageTitle() const; @@ -109,20 +119,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. + (each page displayed using LoadPage() is 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. HistoryBack() won't fail). */ bool HistoryCanForward(); @@ -146,12 +156,12 @@ public: bool LoadFile(const wxFileName& filename); /** - Unlike SetPage this function first loads HTML page from @a location + Unlike SetPage() this function first loads HTML page from @a location and then displays it. See example: @param location - The address of document. See wxFileSystem for details on address format and - behaviour of "opener". + The address of document. + See wxFileSystem for details on address format and behaviour of "opener". @return @false if an error occurred, @true otherwise @@ -160,87 +170,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 +249,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 current selection as plain text. + Returns 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 @@ -294,23 +282,28 @@ public: 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 ) + The same thing for fixed face ( \..\ ) @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. + ( \ to \ ). + Default sizes are used if sizes is @NULL. + + Default font sizes are defined by constants wxHTML_FONT_SIZE_1, + wxHTML_FONT_SIZE_2, ..., wxHTML_FONT_SIZE_7. + Note that they differ among platforms. Default face names are empty strings. */ - void SetFonts(const wxString& normal_face, - const wxString& fixed_face, - const int sizes = NULL); + void SetFonts(const wxString& normal_face, const wxString& fixed_face, + const int* sizes = NULL); /** Sets HTML page and display it. This won't @b load the page!! It will display the @e source. See 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. @@ -320,16 +313,16 @@ public: 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,55 +349,62 @@ 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); }; @@ -414,8 +414,13 @@ protected: 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 +428,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 +444,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 +463,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 +472,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 +483,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); };