]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/html/htmlwin.h
Add test for absence of events from wxSpinCtrlDouble ctor.
[wxWidgets.git] / interface / wx / html / htmlwin.h
index 92409c9af2109e954a5dbadf8883d59345cf1568..330ff938d7a6bc7897b4384535ace4e5f31960f9 100644 (file)
 // 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}
     @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)}
 
     @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 \<TITLE\> 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 ( \<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.
-
-        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("<html><body>Hello, world!</body></html>");
         @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