Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

revised topic overviews (letters g,h)

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52046 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-02-24 17:26:29 +00:00
parent 42efa4987c
commit c33e257b7a
3 changed files with 331 additions and 270 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/doxygen/overviews/grid.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: grid // Name: grid.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,28 +8,33 @@
/*! /*!
@page grid_overview wxGrid classes overview @page overview_grid wxGrid classes overview
Classes: #wxGrid Classes: #wxGrid
#Introduction
@ref simplewxgridexample_overview @li @ref overview_grid_intro
@ref complexwxgridexample_overview @li @ref overview_grid_simpleexample
@ref gridclassesrelations_overview @li @ref overview_grid_complexexample
@ref keyboardandmouseinwxgrid_overview @li @ref overview_grid_classrelations
@li @ref overview_grid_keyboardmouse
@section introductiontowxgrid Introduction <hr>
@section overview_grid_intro Introduction
wxGrid and its related classes are used for displaying and editing tabular data. wxGrid and its related classes are used for displaying and editing tabular data.
@section simplewxgridexample Getting started: a simple example
@section overview_grid_simpleexample Getting started: a simple example
For simple applications you need only refer to the wxGrid class in your For simple applications you need only refer to the wxGrid class in your
code. This example shows how you might create a grid in a frame or code. This example shows how you might create a grid in a frame or
dialog constructor and illustrates some of the formatting functions. dialog constructor and illustrates some of the formatting functions.
@code @code
// Create a wxGrid object // Create a wxGrid object
grid = new wxGrid( this, grid = new wxGrid( this,
-1, -1,
@@ -66,18 +71,19 @@
@endcode @endcode
@section complexwxgridexample A more complex example @section overview_grid_complexexample A more complex example
Yet to be written Yet to be written
@section wxgridclassesrelations How the wxGrid classes relate to each other
@section overview_grid_classrelations How the wxGrid classes relate to each other
Yet to be written Yet to be written
@section keyboardandmouseinwxgrid Keyboard and mouse actions
@section overview_grid_keyboardmouse Keyboard and mouse actions
Yet to be written Yet to be written
*/ */

40
docs/doxygen/overviews/helloworld.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: helloworld // Name: helloworld.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,17 +8,17 @@
/*! /*!
@page helloworld_overview wxWidgets Hello World sample @page overview_helloworld wxWidgets Hello World sample
As many people have requested a mini-sample to be published here Many people have requested a mini-sample to be published here
so that some quick judgment concerning syntax so that some quick judgment concerning syntax
and basic principles can be made, you can now look at wxWidgets' and basic principles can be made, so here we go.
"Hello World":
You have to include wxWidgets' header files, of course. This can First, you have to include wxWidgets' header files, of course. This can
be done on a file by file basis (such as #include "wx/window.h") be done on a file by file basis (such as <tt>@#include "wx/window.h"</tt>)
or using one global include (#include "wx/wx.h"). This is or using one global include (<tt>@#include "wx/wx.h"</tt>). This is
also useful on platforms which support precompiled headers such also useful on platforms which support precompiled headers such
as all major compilers on the Windows platform. as all major compilers on the Windows platform and GCC on Unix platforms.
@code @code
// //
@@ -54,10 +54,11 @@
giving it a menu and a status bar in its constructor. Also, any class giving it a menu and a status bar in its constructor. Also, any class
that wishes to respond to any "event" (such as mouse clicks or that wishes to respond to any "event" (such as mouse clicks or
messages from the menu or a button) must declare an event table messages from the menu or a button) must declare an event table
using the macro below. Finally, the way to react to such events using the macro below.
must be done in "handlers". In our sample, we react to two menu items,
one for "Quit" and one for displaying an "About" window. These Finally, the way to react to such events must be done in "handlers".
handlers should not be virtual. In our sample, we react to two menu items, one for "Quit" and one for
displaying an "About" window. These handlers should not be virtual.
@code @code
class MyFrame: public wxFrame class MyFrame: public wxFrame
@@ -86,11 +87,13 @@
We then proceed to actually implement an event table in which the events We then proceed to actually implement an event table in which the events
are routed to their respective handler functions in the class MyFrame. are routed to their respective handler functions in the class MyFrame.
There are predefined macros for routing all common events, ranging from There are predefined macros for routing all common events, ranging from
the selection of a list box entry to a resize event when a user resizes the selection of a list box entry to a resize event when a user resizes
a window on the screen. If -1 is given as the ID, the given handler will be a window on the screen. If -1 is given as the ID, the given handler will be
invoked for any event of the specified type, so that you could add just invoked for any event of the specified type, so that you could add just
one entry in the event table for all menu commands or all button commands etc. one entry in the event table for all menu commands or all button commands etc.
The origin of the event can still be distinguished in the event handler as The origin of the event can still be distinguished in the event handler as
the (only) parameter in an event handler is a reference to a wxEvent object, the (only) parameter in an event handler is a reference to a wxEvent object,
which holds various information about the event (such as the ID of and a which holds various information about the event (such as the ID of and a
@@ -120,9 +123,9 @@
bool MyApp::OnInit() bool MyApp::OnInit()
{ {
MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) ); MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
frame-Show( @true ); frame-Show( true );
SetTopWindow( frame ); SetTopWindow( frame );
return @true; return true;
} }
@endcode @endcode
@@ -132,7 +135,7 @@
@code @code
MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size) MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
: wxFrame((wxFrame *)@NULL, -1, title, pos, size) : wxFrame((wxFrame *)NULL, -1, title, pos, size)
{ {
wxMenu *menuFile = new wxMenu; wxMenu *menuFile = new wxMenu;
@@ -158,7 +161,7 @@
@code @code
void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event)) void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
{ {
Close( @true ); Close( true );
} }
@endcode @endcode
@@ -173,6 +176,5 @@
} }
@endcode @endcode
*/ */

523
docs/doxygen/overviews/html.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: html // Name: html.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,63 +8,74 @@
/*! /*!
@page html_overview wxHTML overview @page overview_html wxHTML overview
The wxHTML library provides classes for parsing and displaying HTML. 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 It is not intended to be a high-end HTML browser. If you are looking for
something like that try #http://www.mozilla.org. something like that try http://www.mozilla.org.
wxHTML can be used as a generic rich text viewer - for example to display wxHTML can be used as a generic rich text viewer - for example to display
a nice About Box (like those of GNOME apps) or to display the result of a nice About Box (like those of GNOME apps) or to display the result of
database searching. There is a #wxFileSystem database searching. There is a #wxFileSystem class which allows you to use
class which allows you to use your own virtual file systems. your own virtual file systems.
wxHtmlWindow supports tag handlers. This means that you can easily wxHtmlWindow supports tag handlers. This means that you can easily
extend wxHtml library with new, unsupported tags. Not only that, extend wxHtml library with new, unsupported tags. Not only that,
you can even use your own application-specific tags! you can even use your own application-specific tags!
See @c src/html/m_*.cpp files for details. 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.
@ref htmlquickstart_overview
@ref printing_overview @li @ref overview_html_quickstart
@ref helpformat_overview @li @ref overview_html_printing
@ref filters_overview @li @ref overview_html_helpformats
@ref cells_overview @li @ref overview_html_filters
@ref handlers_overview @li @ref overview_html_cells
@ref htmltagssupported_overview @li @ref overview_html_handlers
@li @ref overview_html_supptags
@section wxhtmlquickstart wxHTML quick start <hr>
@b Displaying HTML
First of all, you must include wx/wxhtml.h. @section overview_html_quickstart wxHTML quick start
Class #wxHtmlWindow (derived from wxScrolledWindow)
is used to display HTML documents. @subsection overview_html_quickstart_disphtml Displaying HTML
It has two important methods: #LoadPage
and #SetPage. First of all, you must include @c wx/wxhtml.h.
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 LoadPage loads and displays HTML file while SetPage displays directly the
passed @b string. See the example: passed @b string. See the example:
@code @code
mywin - LoadPage("test.htm"); mywin - LoadPage("test.htm");
mywin - SetPage("htmlbody" mywin - SetPage("htmlbody"
"h1Error/h1" "h1Error/h1"
"Some error occurred :-H)" "Some error occurred :-H)"
"/body/hmtl"); "/body/hmtl");
@endcode @endcode
@b Displaying Help @subsection overview_html_quickstart_disphelp Displaying Help
See #wxHtmlHelpController. See #wxHtmlHelpController.
@b Setting up wxHtmlWindow
@subsection overview_html_quickstart_settingup Setting up wxHtmlWindow
Because wxHtmlWindow is derived from wxScrolledWindow and not from Because wxHtmlWindow is derived from wxScrolledWindow and not from
wxFrame, it doesn't have visible frame. But the user usually wants to see wxFrame, it doesn't have visible frame. But the user usually wants to see
the title of HTML page displayed somewhere and the frame's titlebar is the title of HTML page displayed somewhere and the frame's titlebar is
the ideal place for it. the ideal place for it.
wxHtmlWindow provides 2 methods in order to handle this: wxHtmlWindow provides 2 methods in order to handle this:
#SetRelatedFrame and wxHtmlWindow::SetRelatedFrame and wxHtmlWindow::SetRelatedStatusBar.
#SetRelatedStatusBar.
See the example: See the example:
@code @code
html = new wxHtmlWindow(this); html = new wxHtmlWindow(this);
html - SetRelatedFrame(this, "HTML : %%s"); html - SetRelatedFrame(this, "HTML : %%s");
html - SetRelatedStatusBar(0); html - SetRelatedStatusBar(0);
@endcode @endcode
@@ -73,44 +84,60 @@
(this points to wxFrame object there) and sets the format of the title. (this points to wxFrame object there) and sets the format of the title.
Page title "Hello, world!" will be displayed as "HTML : Hello, world!" Page title "Hello, world!" will be displayed as "HTML : Hello, world!"
in this example. in this example.
The second command sets which frame's status bar should be used to display The second command sets which frame's status bar should be used to display
browser's messages (such as "Loading..." or "Done" or hypertext links). browser's messages (such as "Loading..." or "Done" or hypertext links).
@b Customizing wxHtmlWindow
@subsection overview_html_quickstart_custom Customizing wxHtmlWindow
You can customize wxHtmlWindow by setting font size, font face and You can customize wxHtmlWindow by setting font size, font face and
borders (space between border of window and displayed HTML). Related functions: borders (space between border of window and displayed HTML). Related functions:
@li wxHtmlWindow::SetFonts
#SetFonts @li wxHtmlWindow::SetBorders
#SetBorders @li wxHtmlWindow::ReadCustomization
#ReadCustomization @li wxHtmlWindow::WriteCustomization
#WriteCustomization
The last two functions are used to store user customization info wxConfig stuff The last two functions are used to store user customization info wxConfig stuff
(for example in the registry under Windows, or in a dotfile under Unix). (for example in the registry under Windows, or in a dotfile under Unix).
@section printing HTML Printing
@section overview_html_printing HTML Printing
The wxHTML library provides printing facilities with several levels of complexity. The wxHTML library provides printing facilities with several levels of complexity.
The easiest way to print an HTML document is to use The easiest way to print an HTML document is to use @ref htmleasyprinting_overview.
@ref htmleasyprinting_overview. 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. 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 helpformat Help Files Format 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.
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 uses a reduced version of MS HTML Workshop 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 @b @true in Tex2RTF can produce these files when generating HTML, if you set
your tex2rtf.ini file. @b htmlWorkshopFiles to @true in your tex2rtf.ini file.
(See #wxHtmlHelpController for help controller description.) (See #wxHtmlHelpController for help controller description.)
A @b book consists of three files: header file, contents file and index file.
You can make a regular zip archive of these files, plus the HTML and any image files, A @b book consists of three files: the header file, the contents file
for wxHTML (or helpview) to read; and the .zip file can optionally be renamed to .htb. and the index file.
@b Header file (.hhp)
Header file must contain these lines (and may contain additional lines which are ignored) : 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)
The header file must contain these lines (and may contain additional lines
which are ignored):
@code @code
Contents file=filename.hhc Contents file=filename.hhc
@@ -120,271 +147,298 @@
@endcode @endcode
All filenames (including the Default topic) are relative to the All filenames (including the Default topic) are relative to the
location of .hhp file. location of the @c .hhp file.
@b Localization note: In addition, .hhp file may contain line
@note For localization, in addition the @c .hhp file may contain the line
@code
Charset=rfc_charset
@endcode
which specifies what charset (e.g. "iso8859_1") was used in contents
and index files. Please note that this line is incompatible with
MS HTML Help Workshop and it would either silently remove it or complain
with some error. See also @ref overview_nonenglish.
@subsection overview_html_helpformats_hhc Contents file (.hhc)
Contents file has HTML syntax and it can be parsed by regular HTML parser.
It contains exactly one list (@c &lt;ul&gt;....@c &lt;/ul&gt; statement):
@code @code
Charset=rfc_charset <ul>
@endcode
which specifies what charset (e.g. "iso8859_1") was used in contents <li><object type="text/sitemap">
and index files. Please note that this line is incompatible with <param name="Name" value="@topic name@">
MS HTML Help Workshop and it would either silently remove it or complain <param name="ID" value=@numeric_id@>
with some error. See also <param name="Local" value="@filename.htm@">
@ref nonenglish_overview. </object>
@b Contents file (.hhc) <li><object type="text/sitemap">
Contents file has HTML syntax and it can be parsed by regular HTML parser. It contains exactly one list <param name="Name" value="@topic name@">
(@c ul....@c /ul statement): <param name="ID" value=@numeric_id@>
<param name="Local" value="@filename.htm@">
@code </object>
ul
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"
param name="Name" value="@topic name@"
param name="ID" value=@numeric_id@
param name="Local" value="@filename.htm@"
/object
... ...
</ul>
/ul
@endcode @endcode
You can modify value attributes of param tags. @e topic name is name of chapter/topic as is displayed in You can modify value attributes of param tags.
contents, @e filename.htm is HTML page name (relative to .hhp file) and @e numeric_id is optional The <em>topic name</em> is name of chapter/topic as is displayed in
- it is used only when you use wxHtmlHelpController::Display(int) contents, <em>filename.htm</em> is the HTML page name (relative to the @c .hhp file)
Items in the list may be nested - one @c li statement may contain a @c ul sub-statement: 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:
@code @code
ul <ul>
li object type="text/sitemap" <li><object type="text/sitemap">
param name="Name" value="Top node" <param name="Name" value="Top node">
param name="Local" value="top.htm" <param name="Local" value="top.htm">
/object </object>
ul <ul>
li object type="text/sitemap" <li><object type="text/sitemap">
param name="Name" value="subnode in topnode" <param name="Name" value="subnode in topnode">
param name="Local" value="subnode1.htm" <param name="Local" value="subnode1.htm">
/object </object>
... ...
/ul </ul>
li object type="text/sitemap" <li><object type="text/sitemap">
param name="Name" value="Another Top" <param name="Name" value="Another Top">
param name="Local" value="top2.htm" <param name="Local" value="top2.htm">
/object </object>
... ...
/ul </ul>
@endcode @endcode
@b Index file (.hhk) @subsection overview_html_helpformats_hhk Index file (.hhk)
Index files have same format as contents file 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 filters Input Filters
@section overview_html_filters Input Filters
The wxHTML library provides a mechanism for reading and displaying The wxHTML library provides a mechanism for reading and displaying
files of many different file formats. files of many different file formats.
wxHtmlWindow::LoadPage can load not
only HTML files but any known file. To make a file type known to wxHtmlWindow wxHtmlWindow::LoadPage can load not only HTML files but any known file.
you must create a #wxHtmlFilter filter and To make a file type known to wxHtmlWindow you must create a #wxHtmlFilter filter and
register it using wxHtmlWindow::AddFilter. register it using wxHtmlWindow::AddFilter.
@section cells Cells and Containers
This article describes mechanism used by @section overview_html_cells Cells and Containers
#wxHtmlWinParser and
This article describes mechanism used by #wxHtmlWinParser and
#wxHtmlWindow to parse and display HTML documents. #wxHtmlWindow to parse and display HTML documents.
@b Cells
@subsection overview_html_cells_cells Cells
You can divide any text (or HTML) into small fragments. Let's call these You can divide any text (or HTML) into small fragments. Let's call these
fragments @b cells. Cell is for example one word, horizontal line, image fragments @b cells. Cell is for example one word, horizontal line, image
or any other part of document. Each cell has width and height (except special or any other part of document. Each cell has width and height (except special
"magic" cells with zero dimensions - e.g. colour changers or font changers). "magic" cells with zero dimensions - e.g. colour changers or font changers).
See #wxHtmlCell. See #wxHtmlCell.
@b Containers
@subsection overview_html_cells_containers Containers
Container is kind of cell that may contain sub-cells. Its size depends Container is kind of cell that may contain sub-cells. Its size depends
on number and sizes of its sub-cells (and also depends on width of window). on number and sizes of its sub-cells (and also depends on width of window).
See #wxHtmlContainerCell, See #wxHtmlContainerCell, wxHtmlCell::Layout.
wxHtmlCell::Layout. This image shows the cells and containers: @image html contbox.bmp
This image shows the cells and containers:
@b Using Containers in Tag Handler @subsection overview_html_cells_conttaghandler Using Containers in Tag Handler
#wxHtmlWinParser provides a user-friendly way
of managing containers. It is based on the idea of opening and closing containers. #wxHtmlWinParser provides a user-friendly way of managing containers.
Use #OpenContainer to open new It is based on the idea of opening and closing containers.
a container @e within an already opened container. This new container is a
@e sub-container of the old one. (If you want to create a new container with Use #OpenContainer to open new a container @e within an already opened container.
the same depth level you can call @c CloseContainer(); OpenContainer();.) This new container is a @e sub-container of the old one. (If you want to create a
Use #CloseContainer to close the new container with the same depth level you can call @c CloseContainer(); OpenContainer();.)
container. This doesn't create a new container with same depth level but
it returns "control" to the parent container. Use #CloseContainer to close the container. This doesn't create a new container
See explanation: with same depth level but it returns "control" to the parent container.
See explanation: @image html cont.bmp
There clearly must be same number of calls to OpenContainer as to There clearly must be same number of calls to OpenContainer as to
CloseContainer. CloseContainer.
@b Example
@subsubsection overview_html_cells_conttaghandler_example Example
This code creates a new paragraph (container at same depth level) This code creates a new paragraph (container at same depth level)
with "Hello, world!": with "Hello, world!":
@code @code
m_WParser - CloseContainer(); m_WParser -> CloseContainer();
c = m_WParser - OpenContainer(); c = m_WParser -> OpenContainer();
m_WParser - AddText("Hello, "); m_WParser -> AddText("Hello, ");
m_WParser - AddText("world!"); m_WParser -> AddText("world!");
m_WParser - CloseContainer(); m_WParser -> CloseContainer();
m_WParser - OpenContainer(); m_WParser -> OpenContainer();
@endcode @endcode
and here is image of the situation: and here is image of the situation: @image html hello.bmp
You can see that there was an opened container before the code was executed. 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 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 new container.
executing. This is general rule that should be followed by tag handlers:
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 leave depth level of containers unmodified (in other words, number of
OpenContainer and CloseContainer calls should be same within #HandleTag's body). OpenContainer and CloseContainer calls should be same within #HandleTag's body).
Notice that it would be usually better to use
wxHtmlContainerCell::InsertCell instead Notice that it would be usually better to use wxHtmlContainerCell::InsertCell instead
of adding text to the parser directly. of adding text to the parser directly.
@section handlers Tag Handlers
@section overview_html_handlers Tag Handlers
The wxHTML library provides architecture of pluggable @e tag handlers. The wxHTML library provides architecture of pluggable @e tag handlers.
Tag handler is class that understands particular HTML tag (or tags) and is Tag handler is class that understands particular HTML tag (or tags) and is
able to interpret it. able to interpret it.
#wxHtmlWinParser has static table of @b modules.
#wxHtmlWinParser has a static table of @b modules.
Each module contains one or more tag handlers. Each time a new wxHtmlWinParser Each module contains one or more tag handlers. Each time a new wxHtmlWinParser
object is constructed all modules are scanned and handlers are added object is constructed all modules are scanned and handlers are added
to wxHtmlParser's list of available handlers (note: wxHtmlParser's list to wxHtmlParser's list of available handlers (note: wxHtmlParser's list
is non-static). is non-static).
@b How it works
Common tag handler's #HandleTag method
works in four steps:
@subsection overview_html_handlers_howworks How it works
Save state of parent parser into local variables Common tag handler's #HandleTag method works in four steps:
Change parser state according to tag's params
Parse text between the tag and paired ending tag (if present)
Restore original parser state
@li Save state of parent parser into local variables
@li Change parser state according to tag's params
@li Parse text between the tag and paired ending tag (if present)
@li Restore original parser state
See #wxHtmlWinParser for methods for modifying See #wxHtmlWinParser for methods for modifying parser's state.
parser's state. In general you can do things like opening/closing containers, In general you can do things like opening/closing containers, changing colors, fonts etc.
changing colors, fonts etc.
@b Providing own tag handlers @subsection overview_html_handlers_custom Providing own tag handlers
You should create new .cpp file and place following lines into it:
You should create a new .cpp file and place the following lines into it:
@code @code
#include mod_templ.h #include <mod_templ.h>
#include forcelink.h #include <forcelink.h>
FORCE_LINK_ME(yourmodulefilenamewithoutcpp) FORCE_LINK_ME(yourmodulefilenamewithoutcpp)
@endcode @endcode
Then you must define handlers and one module. Then you must define handlers and one module.
@b Tag handlers
The handler is derived from #wxHtmlWinTagHandler @subsection overview_html_handlers_tag Tag handlers
(or directly from #wxHtmlTagHandler)
The handler is derived from #wxHtmlWinTagHandler (or directly from #wxHtmlTagHandler).
You can use set of macros to define the handler (see src/html/m_*.cpp files You can use set of macros to define the handler (see src/html/m_*.cpp files
for details). Handler definition must start with @b TAG_HANDLER_BEGIN macro for details). Handler definition must start with @b TAG_HANDLER_BEGIN macro
and end with @b TAG_HANDLER_END macro. I strongly recommend to have a look and end with @b TAG_HANDLER_END macro.
at @e include/wxhtml/mod_templ.h file. Otherwise you won't understand
the structure of macros. See macros reference:
@b TAG_HANDLER_BEGIN(@e name, @e tags)
Starts handler definition. @e name is handler identifier (in fact
part of class name), @e tags is string containing list of tags
supported by this handler (in uppercase). This macro derives new class from
wxHtmlWinTagHandler and implements it is
#GetSupportedTags method.
Example: TAG_HANDLER_BEGIN(FONTS, "B,I,U,T")
@b TAG_HANDLER_VARS
This macro starts block of variables definitions. (Variables are identical
to class attributes.) Example:
@code I strongly recommend to have a look at @e include/wxhtml/mod_templ.h file.
TAG_HANDLER_BEGIN(VARS_ONLY, "CRAZYTAG") Otherwise you won't understand the structure of macros.
TAG_HANDLER_VARS
int my_int_var;
wxString something_else;
TAG_HANDLER_END(VARS_ONLY)
@endcode
This macro is used only in rare cases. See macros reference:
@b TAG_HANDLER_CONSTR(@e name) @li @b TAG_HANDLER_BEGIN(@e name, @e tags):
This macro supplies object constructor. @e name is same name as the one Starts handler definition. @e name is handler identifier (in fact
from TAG_HANDLER_BEGIN macro. Body of constructor follow after part of class name), @e tags is string containing list of tags
this macro (you must use and ). Example: supported by this handler (in uppercase). This macro derives new class from
wxHtmlWinTagHandler and implements it is #GetSupportedTags method.
Example: TAG_HANDLER_BEGIN(FONTS, "B,I,U,T")
@code @li @b TAG_HANDLER_VARS:
TAG_HANDLER_BEGIN(VARS2, "CRAZYTAG") This macro starts block of variables definitions. (Variables are identical
TAG_HANDLER_VARS to class attributes.) Example:
int my_int_var;
TAG_HANDLER_CONSTR(vars2) @code
{ // !!!!!! TAG_HANDLER_BEGIN(VARS_ONLY, "CRAZYTAG")
my_int_var = 666; TAG_HANDLER_VARS
} // !!!!!! int my_int_var;
TAG_HANDLER_END(VARS2) wxString something_else;
@endcode TAG_HANDLER_END(VARS_ONLY)
@endcode
This macro is used only in rare cases.
Never used in wxHTML :-) @li @b TAG_HANDLER_CONSTR(@e name):
@b TAG_HANDLER_PROC(@e varib) This macro supplies object constructor. @e name is same name as the one
This is very important macro. It defines #HandleTag from TAG_HANDLER_BEGIN macro. Body of constructor follow after
method. @e varib is name of parameter passed to the method, usually this macro (you must use { and } ). Example:
@e tag. Body of method follows after this macro.
Note than you must use and ! Example: @code
TAG_HANDLER_BEGIN(VARS2, "CRAZYTAG")
TAG_HANDLER_VARS
int my_int_var;
TAG_HANDLER_CONSTR(vars2)
{ // !!!!!!
my_int_var = 666;
} // !!!!!!
TAG_HANDLER_END(VARS2)
@endcode
Never used in wxHTML :-)
@code @li @b TAG_HANDLER_PROC(@e varib):
TAG_HANDLER_BEGIN(TITLE, "TITLE") This is very important macro. It defines #HandleTag
TAG_HANDLER_PROC(tag) method. @e varib is name of parameter passed to the method, usually
{ @e tag. Body of method follows after this macro.
printf("TITLE found...\n"); Note than you must use { and } !
} Example:
TAG_HANDLER_END(TITLE)
@endcode @code
TAG_HANDLER_BEGIN(TITLE, "TITLE")
TAG_HANDLER_PROC(tag)
{
printf("TITLE found...\n");
}
TAG_HANDLER_END(TITLE)
@endcode
@li @b TAG_HANDLER_END(@e name):
Ends definition of tag handler @e name.
@subsection overview_html_handlers_modules Tags Modules
@b TAG_HANDLER_END(@e name)
Ends definition of tag handler @e name.
@b Tags Modules
You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and
TAGS_MODULE_END to inherit new module from TAGS_MODULE_END to inherit new module from
#wxHtmlTagsModule and to create instance of it. #wxHtmlTagsModule and to create instance of it.
See macros reference: See macros reference:
@b TAGS_MODULE_BEGIN(@e modname)
Begins module definition. @e modname is part of class name and must
be unique.
@b TAGS_MODULE_ADD(@e name)
Adds the handler to this module. @e name is the identifier from
TAG_HANDLER_BEGIN.
@b TAGS_MODULE_END(@e modname)
Ends the definition of module.
@b Example:
@code @li @b TAGS_MODULE_BEGIN(@e modname):
TAGS_MODULE_BEGIN(Examples) Begins module definition. @e modname is part of class name and must be unique.
TAGS_MODULE_ADD(VARS_ONLY) @li @b TAGS_MODULE_ADD(@e name):
TAGS_MODULE_ADD(VARS2) Adds the handler to this module. @e name is the identifier from TAG_HANDLER_BEGIN.
TAGS_MODULE_ADD(TITLE) @li @b TAGS_MODULE_END(@e modname):
TAGS_MODULE_END(Examples) Ends the definition of module.
@endcode Example:
@code
TAGS_MODULE_BEGIN(Examples)
TAGS_MODULE_ADD(VARS_ONLY)
TAGS_MODULE_ADD(VARS2)
TAGS_MODULE_ADD(TITLE)
TAGS_MODULE_END(Examples)
@endcode
@section htmltagssupported Tags supported by wxHTML @section overview_html_supptags Tags supported by wxHTML
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).
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).
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 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 either @c paramname="paramvalue" or @c paramname=paramvalue - these two are equivalent.
otherwise, wxHTML is case-insensitive. Unless stated otherwise, wxHTML is case-insensitive.
@b Table of common parameter values
@subsection overview_html_supptags_commonvalues Table of common parameter values
We will use these substitutions in tags descriptions: We will use these substitutions in tags descriptions:
@code @code
@@ -428,7 +482,7 @@
@endcode @endcode
@b List of supported tags @subsection overview_html_supptags_list List of supported tags
@code @code
A NAME=[string] A NAME=[string]
@@ -520,6 +574,5 @@
UL UL
@endcode @endcode
*/ */