X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ccf39540bb96a0e5d067451ad79c82397579aceb..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/html/htmlwin.h diff --git a/interface/wx/html/htmlwin.h b/interface/wx/html/htmlwin.h index 34c231c82c..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 + 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. - Don't forget to initialize all image formats you need before loading any page! - (See ::wxInitAllImageHandlers and wxImage::AddHandler.) + 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} @@ -35,7 +140,7 @@ @endStyleTable - @beginEventTable{wxHtmlCellEvent, wxHtmlLinkEvent} + @beginEventEmissionTable{wxHtmlCellEvent, wxHtmlLinkEvent} @event{EVT_HTML_CELL_CLICKED(id, func)} A wxHtmlCell was clicked. @event{EVT_HTML_CELL_HOVER(id, func)} @@ -49,7 +154,7 @@ @see wxHtmlLinkEvent, wxHtmlCellEvent */ -class wxHtmlWindow : public wxScrolledWindow +class wxHtmlWindow : public wxScrolledWindow, public wxHtmlWindowInterface { public: /** @@ -74,7 +179,7 @@ public: - @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. @@ -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,15 +365,15 @@ 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(); /** This function sets the space between border of window and HTML contents. See image: - @image html border.png + @image html htmlwin_border.png @param b indentation from borders in pixels @@ -274,31 +381,25 @@ 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. - @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 ( \..\ ) - @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 - ( \ 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. + @see SetSize() */ 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: + Sets default font sizes and/or default font size. + See wxHtmlDCRenderer::SetStandardFonts for detailed description. + @see SetFonts() + */ + void SetStandardFonts(int size = -1, + const wxString& normal_face = wxEmptyString, + const wxString& fixed_face = wxEmptyString); + + /** + Sets the source of a page and displays it, for example: @code htmlwin -> SetPage("Hello, world!"); @endcode @@ -306,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. */ @@ -364,7 +465,7 @@ public: */ virtual void WriteCustomization(wxConfigBase* cfg, wxString path = wxEmptyString); - + protected: /** @@ -409,6 +510,11 @@ protected: +wxEventType wxEVT_HTML_CELL_CLICKED; +wxEventType wxEVT_HTML_CELL_HOVER; +wxEventType wxEVT_HTML_LINK_CLICKED; + + /** @class wxHtmlLinkEvent