Make the CreateTool factories be public so they can be used from application code

[wxWidgets.git] / interface / wx / html / htmlwin.h

diff --git a/interface/wx/html/htmlwin.h b/interface/wx/html/htmlwin.h
index 2aa8bb3c9ef6692d399bb3c24fe12d6efa72d63a..9ad78baac9e7f92b71df79ddaa7239870ba4ce09 100644 (file)
--- a/interface/wx/html/htmlwin.h
+++ b/interface/wx/html/htmlwin.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxHtmlWindow
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxHtmlWindow
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -12,17 +12,21 @@
     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 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.
     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
 
     @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}
 
     @beginStyleTable
     @style{wxHW_SCROLLBAR_NEVER}


@@ -35,7 +39,7 @@
     @endStyleTable
 
 
     @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)}
     @event{EVT_HTML_CELL_CLICKED(id, func)}
         A wxHtmlCell was clicked.
     @event{EVT_HTML_CELL_HOVER(id, func)}


@@ -61,12 +65,11 @@ public:
         Constructor.
         The parameters are the same as wxScrolled::wxScrolled() constructor.
     */
         Constructor.
         The parameters are the same as wxScrolled::wxScrolled() constructor.
     */

-    wxHtmlWindow(wxWindow parent, wxWindowID id = -1,
+    wxHtmlWindow(wxWindow *parent, wxWindowID id = wxID_ANY,

                  const wxPoint& pos = wxDefaultPosition,
                  const wxSize& size = wxDefaultSize,
                  long style = wxHW_DEFAULT_STYLE,
                  const wxString& name = "htmlWindow");
                  const wxPoint& pos = wxDefaultPosition,
                  const wxSize& size = wxDefaultSize,
                  long style = wxHW_DEFAULT_STYLE,
                  const wxString& name = "htmlWindow");

-    //@}

 
     /**
         Adds @ref overview_html_filters "input filter" to the static list of available
 
     /**
         Adds @ref overview_html_filters "input filter" to the static list of available


@@ -75,7 +78,7 @@ public:
         - @c image/* MIME types
         - Plain Text filter (this filter is used if no other filter matches)
     */
         - @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.
 
     /**
         Appends HTML fragment to currently displayed text and refreshes the window.


@@ -109,7 +112,7 @@ public:
     wxString GetOpenedPage() const;
 
     /**
     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;
         contain \<TITLE\> tag.
     */
     wxString GetOpenedPageTitle() const;


@@ -120,20 +123,20 @@ public:
     wxFrame* GetRelatedFrame() const;
 
     /**
     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
     */
     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
     */
     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();
 
     */
     bool HistoryCanForward();
 


@@ -143,12 +146,13 @@ public:
     void HistoryClear();
 
     /**
     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();
 
     /**
     */
     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
 
 
         @return @false if an error occurred, @true otherwise
 


@@ -157,12 +161,13 @@ public:
     bool LoadFile(const wxFileName& filename);
 
     /**
     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
 
         @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
 
 
         @return @false if an error occurred, @true otherwise
 


@@ -259,15 +264,15 @@ public:
     void SelectWord(const wxPoint& pos);
 
     /**
     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:
     */
     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
 
         @param b
             indentation from borders in pixels


@@ -275,31 +280,25 @@ public:
     void SetBorders(int b);
 
     /**
     void SetBorders(int b);
 
     /**

-        This function sets font sizes and faces.
-
-        @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.
+        This function sets font sizes and faces. See wxHtmlDCRenderer::SetFonts
+        for detailed description.

 
 

-        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);
 
     /**
     */
     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
         @code
         htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
         @endcode


@@ -307,7 +306,7 @@ public:
         If you want to load a document from some location use LoadPage() instead.
 
         @param source
         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.
     */
 
         @return @false if an error occurred, @true otherwise.
     */


@@ -429,7 +428,7 @@ public:
     /**
         The constructor is not normally used by the user code.
     */
     /**
         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
 
     /**
         Returns the wxHtmlLinkInfo which contains info about the cell clicked


@@ -464,7 +463,8 @@ public:
     */
     wxHtmlCellEvent(wxEventType commandType, int id,
                     wxHtmlCell* cell,
     */
     wxHtmlCellEvent(wxEventType commandType, int id,
                     wxHtmlCell* cell,

-                    const wxPoint& point);
+                    const wxPoint& point,
+                    const wxMouseEvent& ev);

 
     /**
         Returns the wxHtmlCellEvent associated with the event.
 
     /**
         Returns the wxHtmlCellEvent associated with the event.