@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/>.
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.
-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
- 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
@subsection overview_html_quickstart_settingup Setting up wxHtmlWindow
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
@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
-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
-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.
+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.
-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)
@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>
-<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>
-...
+ ...
</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 <li> statement may contain a @c <ul> sub-statement:
+Items in the list may be nested - one @c <li> statement may contain a
+@c <ul> sub-statement:
@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="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
-@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 files except that ID params are ignored
-and sublists are @b not allowed.
@section overview_html_filters Input Filters
register it using wxHtmlWindow::AddFilter.
+
@section overview_html_cells Cells and Containers
This article describes mechanism used by wxHtmlWinParser and
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
-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:
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
@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.
-(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:
@endcode
-@subsection overview_html_supptags_list List of supported tags
+@subsection overview_html_supptags_list List of Supported Tags
@code
A NAME=[string]
UL
@endcode
-@subsection overview_html_suppstyles_list List of supported styles
+@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)
-*/
+- @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)
+*/
projects / wxWidgets.git / blobdiff