Added control over whether size and position units can be changed, and also size...

[wxWidgets.git] / docs / doxygen / overviews / html.h

diff --git a/docs/doxygen/overviews/html.h b/docs/doxygen/overviews/html.h
index 1d9803674e9e613db327177d4fe18a1db1b550ab..9c3d8bcbb0124307accd7bf4975096f13a894f43 100644 (file)
--- a/docs/doxygen/overviews/html.h
+++ b/docs/doxygen/overviews/html.h
@@ -3,13 +3,15 @@
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 
 @page overview_html wxHTML Overview
 
 /////////////////////////////////////////////////////////////////////////////
 
 /**
 
 @page overview_html wxHTML Overview
 

+@tableofcontents
+

 The wxHTML library provides classes for parsing and displaying HTML.
 It is not intended to be a high-end HTML browser. If you are looking for
 something like that try <http://www.mozilla.org/>.
 The wxHTML library provides classes for parsing and displaying HTML.
 It is not intended to be a high-end HTML browser. If you are looking for
 something like that try <http://www.mozilla.org/>.


@@ -27,42 +29,29 @@ See @c src/html/m_*.cpp files for details.
 
 There is a generic wxHtmlParser class, independent of wxHtmlWindow.
 
 
 There is a generic wxHtmlParser class, independent of wxHtmlWindow.
 

-@li @ref overview_html_quickstart
-@li @ref overview_html_printing
-@li @ref overview_html_helpformats
-@li @ref overview_html_filters
-@li @ref overview_html_cells
-@li @ref overview_html_handlers
-@li @ref overview_html_supptags
-
-
-<hr>

 
 
 
 

-@section overview_html_quickstart wxHTML quick start
+@section overview_html_quickstart wxHTML Quick Start

 
 @subsection overview_html_quickstart_disphtml Displaying HTML
 
 First of all, you must include @c wx/wxhtml.h.
 
 
 @subsection overview_html_quickstart_disphtml Displaying HTML
 
 First of all, you must include @c wx/wxhtml.h.
 

-Class wxHtmlWindow (derived from ::wxScrolledWindow) is used to display HTML documents.
+Class wxHtmlWindow (derived from ::wxScrolledWindow) is used to display HTML
+documents.

 
 It has two important methods: wxHtmlWindow::LoadPage and wxHtmlWindow::SetPage.
 LoadPage loads and displays HTML file while SetPage displays directly the
 passed @b string. See the example:
 
 @code
 
 It has two important methods: wxHtmlWindow::LoadPage and wxHtmlWindow::SetPage.
 LoadPage loads and displays HTML file while SetPage displays directly the
 passed @b string. See the example:
 
 @code

-    mywin -> LoadPage("test.htm");
-    mywin -> SetPage("htmlbody"
-                    "h1Error/h1"
-                    "Some error occurred :-H)"
-                    "/body/hmtl");
+mywin->LoadPage("test.htm");
+mywin->SetPage("htmlbody"
+               "h1Error/h1"
+               "Some error occurred :-H)"
+               "/body/hmtl");

 @endcode
 
 @endcode
 

-@subsection overview_html_quickstart_disphelp Displaying Help
-
-See wxHtmlHelpController.
-

 @subsection overview_html_quickstart_settingup Setting up wxHtmlWindow
 
 Because wxHtmlWindow is derived from ::wxScrolledWindow and not from
 @subsection overview_html_quickstart_settingup Setting up wxHtmlWindow
 
 Because wxHtmlWindow is derived from ::wxScrolledWindow and not from


@@ -75,9 +64,9 @@ wxHtmlWindow::SetRelatedFrame and wxHtmlWindow::SetRelatedStatusBar.
 See the example:
 
 @code
 See the example:
 
 @code

-    html = new wxHtmlWindow(this);
-    html -> SetRelatedFrame(this, "HTML : %%s");
-    html -> SetRelatedStatusBar(0);
+html = new wxHtmlWindow(this);
+html->SetRelatedFrame(this, "HTML : %%s");
+html->SetRelatedStatusBar(0);

 @endcode
 
 The first command associates the HTML object with its parent frame
 @endcode
 
 The first command associates the HTML object with its parent frame


@@ -105,34 +94,33 @@ The last two functions are used to store user customization info wxConfig stuff
 
 @section overview_html_printing HTML Printing
 
 
 @section overview_html_printing HTML Printing
 

-The wxHTML library provides printing facilities with several levels of complexity.
-The easiest way to print an HTML document is to use the wxHtmlEasyPrinting class.
+The wxHTML library provides printing facilities with several levels of
+complexity. The easiest way to print an HTML document is to use the
+wxHtmlEasyPrinting class.

 
 

-It lets you print HTML documents with only one command and you don't have to worry
-about deriving from the wxPrintout class at all. It is only a simple wrapper around the
-wxHtmlPrintout, normal wxWidgets printout class.
+It lets you print HTML documents with only one command and you don't have to
+worry about deriving from the wxPrintout class at all. It is only a simple
+wrapper around the wxHtmlPrintout, normal wxWidgets printout class.

 
 And finally there is the low level class wxHtmlDCRenderer which you can use to
 
 And finally there is the low level class wxHtmlDCRenderer which you can use to

-render HTML into a rectangular area on any DC.
+render HTML into a rectangular area on any DC. It supports rendering into
+multiple rectangles with the same width. The most common use of this is placing
+one rectangle on each page or printing into two columns.

 
 

-It supports rendering into multiple rectangles with the same
-width. (The most common use of this is placing one rectangle on each page or
-printing into two columns.)

 
 
 @section overview_html_helpformats Help Files Format
 
 
 
 @section overview_html_helpformats Help Files Format
 

-wxHTML library uses a reduced version of MS HTML Workshop format.
-Tex2RTF can produce these files when generating HTML, if you set
-@b htmlWorkshopFiles to @true in your tex2rtf.ini file.
-(See wxHtmlHelpController for help controller description.)
+wxHTML library can be used to show an help manual to the user; in fact, it
+supports natively (through wxHtmlHelpController) a reduced version of MS HTML
+Workshop format.

 
 A @b book consists of three files: the header file, the contents file
 and the index file.
 
 
 A @b book consists of three files: the header file, the contents file
 and the index file.
 

-You can make a regular zip archive of these files, plus the HTML and any
-image files, for wxHTML (or helpview) to read; and the @c .zip file can
-optionally be renamed to @c .htb.
+You can make a regular zip archive of these files, plus the HTML and any image
+files, for wxHTML (or helpview) to read; and the @c ".zip" file can optionally
+be renamed to @c ".htb".

 
 @subsection overview_html_helpformats_hhp Header file (.hhp)
 
 
 @subsection overview_html_helpformats_hhp Header file (.hhp)
 


@@ -147,9 +135,9 @@ Default topic=default page to be displayed.htm
 @endcode
 
 All filenames (including the Default topic) are relative to the
 @endcode
 
 All filenames (including the Default topic) are relative to the

-location of the @c .hhp file.
+location of the @c ".hhp" file.

 
 

-@note For localization, in addition the @c .hhp file may contain the line
+@note For localization, in addition the @c ".hhp" file may contain the line

     @code
         Charset=rfc_charset
     @endcode
     @code
         Charset=rfc_charset
     @endcode


@@ -165,56 +153,54 @@ It contains exactly one list (@c &lt;ul&gt;....@c &lt;/ul&gt; statement):
 
 @code
 <ul>
 
 @code
 <ul>

-
-<li><object type="text/sitemap">
+    <li><object type="text/sitemap">

             <param name="Name" value="@topic name@">
             <param name="ID" value=@numeric_id@>
             <param name="Local" value="@filename.htm@">
         </object>
             <param name="Name" value="@topic name@">
             <param name="ID" value=@numeric_id@>
             <param name="Local" value="@filename.htm@">
         </object>

-<li><object type="text/sitemap">
+    <li><object type="text/sitemap">

             <param name="Name" value="@topic name@">
             <param name="ID" value=@numeric_id@>
             <param name="Local" value="@filename.htm@">
         </object>
             <param name="Name" value="@topic name@">
             <param name="ID" value=@numeric_id@>
             <param name="Local" value="@filename.htm@">
         </object>

-...
+    ...

 </ul>
 @endcode
 
 </ul>
 @endcode
 

-You can modify value attributes of param tags.
-The <em>topic name</em> is name of chapter/topic as is displayed in
-contents, <em>filename.htm</em> is the HTML page name (relative to the @c .hhp file)
-and <em>numeric_id</em> is optional - it is used only when you use wxHtmlHelpController::Display(int).
+You can modify value attributes of param tags. The <em>topic name</em> is name
+of chapter/topic as is displayed in contents, <em>filename.htm</em> is the HTML
+page name (relative to the @c ".hhp" file) and <em>numeric_id</em> is optional,
+it is used only when you use wxHtmlHelpController::Display(int).

 
 

-Items in the list may be nested - one @c &lt;li&gt; statement may contain a @c &lt;ul&gt; sub-statement:
+Items in the list may be nested - one @c &lt;li&gt; statement may contain a
+@c &lt;ul&gt; sub-statement:

 
 @code
 <ul>
 
 @code
 <ul>

-
-<li><object type="text/sitemap">
-        <param name="Name" value="Top node">
-        <param name="Local" value="top.htm">
-    </object>
+    <li><object type="text/sitemap">
+            <param name="Name" value="Top node">
+            <param name="Local" value="top.htm">
+        </object>

     <ul>
         <li><object type="text/sitemap">
             <param name="Name" value="subnode in topnode">
             <param name="Local" value="subnode1.htm">
             </object>
     <ul>
         <li><object type="text/sitemap">
             <param name="Name" value="subnode in topnode">
             <param name="Local" value="subnode1.htm">
             </object>

-    ...
+        ...

     </ul>
     </ul>

-
-<li><object type="text/sitemap">
-        <param name="Name" value="Another Top">
-        <param name="Local" value="top2.htm">
-    </object>
-...
-
+    <li><object type="text/sitemap">
+            <param name="Name" value="Another Top">
+            <param name="Local" value="top2.htm">
+        </object>
+    ...

 </ul>
 @endcode
 
 </ul>
 @endcode
 

-@subsection overview_html_helpformats_hhk Index file (.hhk)
+@subsection overview_html_helpformats_hhk Index Files (.hhk)
+
+Index files have same format as contents files except that ID params are
+ignored and sublists are @b not allowed.

 
 

-Index files have same format as contents file except that ID params are ignored
-and sublists are @b not allowed.

 
 
 @section overview_html_filters Input Filters
 
 
 @section overview_html_filters Input Filters


@@ -227,6 +213,7 @@ To make a file type known to wxHtmlWindow you must create a wxHtmlFilter filter
 register it using wxHtmlWindow::AddFilter.
 
 
 register it using wxHtmlWindow::AddFilter.
 
 

+

 @section overview_html_cells Cells and Containers
 
 This article describes mechanism used by wxHtmlWinParser and
 @section overview_html_cells Cells and Containers
 
 This article describes mechanism used by wxHtmlWinParser and


@@ -268,20 +255,18 @@ to the parent container. See explanation:
 There clearly must be same number of calls to OpenContainer as to
 CloseContainer.
 
 There clearly must be same number of calls to OpenContainer as to
 CloseContainer.
 

-@subsubsection overview_html_cells_conttaghandler_example Example
-
-This code creates a new paragraph (container at same depth level)
-with "Hello, world!":
+This code creates a new paragraph (container at same depth level) with
+"Hello, world!":

 
 @code
 
 @code

-m_WParser -> CloseContainer();
-c = m_WParser -> OpenContainer();
+m_WParser->CloseContainer();
+c = m_WParser->OpenContainer();

 
 

-m_WParser -> AddText("Hello, ");
-m_WParser -> AddText("world!");
+m_WParser->AddText("Hello, ");
+m_WParser->AddText("world!");

 
 

-m_WParser -> CloseContainer();
-m_WParser -> OpenContainer();
+m_WParser->CloseContainer();
+m_WParser->OpenContainer();

 @endcode
 
 and here is image of the situation:
 @endcode
 
 and here is image of the situation:


@@ -292,14 +277,14 @@ You can see that there was an opened container before the code was executed.
 We closed it, created our own container, then closed our container and opened
 new container.
 
 We closed it, created our own container, then closed our container and opened
 new container.
 

-The result was that we had @e same depth level after executing.
-This is general rule that should be followed by tag handlers:
-leave depth level of containers unmodified (in other words, number of
-OpenContainer and CloseContainer calls should be same within
-wxHtmlTagHandler::HandleTag's body).
+The result was that we had @e same depth level after executing. This is general
+rule that should be followed by tag handlers: leave depth level of containers
+unmodified (in other words, number of OpenContainer and CloseContainer calls
+should be same within wxHtmlTagHandler::HandleTag's body).
+
+Notice that it would be usually better to use wxHtmlContainerCell::InsertCell
+instead of adding text to the parser directly.

 
 

-Notice that it would be usually better to use wxHtmlContainerCell::InsertCell instead
-of adding text to the parser directly.

 
 
 @section overview_html_handlers Tag Handlers
 
 
 @section overview_html_handlers Tag Handlers


@@ -433,19 +418,22 @@ See macros reference:
     @endcode
 
 
     @endcode
 
 

-@section overview_html_supptags Tags supported by wxHTML
+
+@section overview_html_supptags Supported HTML Tags

 
 wxHTML is not full implementation of HTML standard. Instead, it supports most
 common tags so that it is possible to display @e simple HTML documents with it.
 
 wxHTML is not full implementation of HTML standard. Instead, it supports most
 common tags so that it is possible to display @e simple HTML documents with it.

-(For example it works fine with pages created in Netscape Composer or generated by tex2rtf).
+(For example it works fine with pages created in Netscape Composer or generated
+by tex2rtf).

 
 

-Following tables list all tags known to wxHTML, together with supported parameters.
+Following tables list all tags known to wxHTML, together with supported
+parameters.

 
 

-A tag has general form of @c tagname param_1 param_2 ... param_n where param_i is
-either @c paramname="paramvalue" or @c paramname=paramvalue - these two are equivalent.
-Unless stated otherwise, wxHTML is case-insensitive.
+A tag has general form of @c tagname param_1 param_2 ... param_n where param_i
+is either @c paramname="paramvalue" or @c paramname=paramvalue - these two are
+equivalent. Unless stated otherwise, wxHTML is case-insensitive.

 
 

-@subsection overview_html_supptags_commonvalues Table of common parameter values
+@subsection overview_html_supptags_commonvalues Common Parameter Values

 
 We will use these substitutions in tags descriptions:
 
 
 We will use these substitutions in tags descriptions:
 


@@ -490,7 +478,7 @@ We will use these substitutions in tags descriptions:
 @endcode
 
 
 @endcode
 
 

-@subsection overview_html_supptags_list List of supported tags
+@subsection overview_html_supptags_list List of Supported Tags

 
 @code
 A               NAME=[string]
 
 @code
 A               NAME=[string]


@@ -532,7 +520,7 @@ H5
 H6
 I
 IMG             SRC=[url]
 H6
 I
 IMG             SRC=[url]

-                WIDTH=[pixels]
+                WIDTH=[percent|pixels]

                 HEIGHT=[pixels]
                 ALIGN=TEXTTOP
                 ALIGN=CENTER
                 HEIGHT=[pixels]
                 ALIGN=TEXTTOP
                 ALIGN=CENTER


@@ -549,6 +537,7 @@ P               ALIGN=[alignment]
 PRE
 SAMP
 SMALL
 PRE
 SAMP
 SMALL

+SPAN

 STRIKE
 STRONG
 SUB
 STRIKE
 STRONG
 SUB


@@ -582,5 +571,18 @@ U
 UL
 @endcode
 
 UL
 @endcode
 

-*/
+@subsection overview_html_suppstyles_list Supported Styles

 
 

+wxHTML doesn't really have CSS support but it does support a few simple styles:
+you can use @c "text-align", @c "width", @c "vertical-align" and @c
+"background" with all elements and for @c SPAN elements a few other styles are
+additionally recognized:
+
+- @c color
+- @c font-family
+- @c font-size (only in point units)
+- @c font-style (only "oblique", "italic" and "normal" values are supported)
+- @c font-weight (only "bold" and "normal" values are supported)
+- @c text-decoration (only "underline" value is supported)
+
+*/