[wxWidgets.git] / docs / latex / wx / htwindow.tex

%
% automatically generated by HelpGen from
% htmlwindow.tex at 14/Mar/99 20:13:37
%

\section{\class{wxHtmlWindow}}\label{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)

Purpose of this class is to display HTML page (either local
file or downloaded via HTTP protocol) in a window. Width
of window is constant - given in constructor - virtual height
is changed dynamicly depending on page size.
Once the window is created you can set it's content by calling
\helpref{SetPage(text)}{wxhtmlwindowsetpage} or 
\helpref{LoadPage(filename)}{wxhtmlwindowloadpage}. 

\wxheading{Derived from}

wxScrolledWindow

\wxheading{Include files}

<wxhtml/wxhtmlwin.h>

\membersection{wxHtmlWindow::wxHtmlWindow}\label{wxhtmlwindowwxhtmlwindow}

\func{}{wxHtmlWindow}{\void}

Default constructor.

\func{}{wxHtmlWindow}{\param{wxWindow }{*parent}, \param{wxWindowID }{id = -1}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = wxHW_SCROLLBAR_AUTO}, \param{const wxString\& }{name = "htmlWindow"}}

Constructor. The parameters are same as in wxScrollWindow ctor.
(Too lazy to document it once again... :-)

\wxheading{Parameters}

\docparam{style}{wxHW\_SCROLLBAR\_NEVER,  or wxHW\_SCROLLBAR\_AUTO. 
Affects appearance of vertical scrollbar in the window.}

\membersection{wxHtmlWindow::SetPage}\label{wxhtmlwindowsetpage}

\func{bool}{SetPage}{\param{const wxString\& }{source}}

Sets HTML page and display it. This won't {\bf load} the page!!
It will display the {\it source}. See example:

\begin{verbatim}
htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
\end{verbatim}

If you want to load document from some location use
\helpref{LoadPage}{wxhtmlwindowloadpage} instead.

\wxheading{Parameters}

\docparam{source}{The HTML document source to be displayed.}

\wxheading{Return value}

FALSE if an error occured, TRUE otherwise

\membersection{wxHtmlWindow::LoadPage}\label{wxhtmlwindowloadpage}

\func{bool}{LoadPage}{\param{const wxString\& }{location}}

Unlike SetPage this function first loads HTML page from {\it location}
and then displays it. See example:

\begin{verbatim}
htmlwin -> SetPage("help/myproject/index.htm");
\end{verbatim}

\wxheading{Parameters}

\docparam{location}{The address of document. See \helpref{wxFileSystem}{wxfilesystem} for details on address format and behaviour of "opener".}

\wxheading{Return value}

FALSE if an error occured, TRUE otherwise

\membersection{wxHtmlWindow::GetOpenedPage}\label{wxhtmlwindowgetopenedpage}

\func{wxString}{GetOpenedPage}{\void}

Returns full location of the opened page. If no page is opened or if the displayed page wasn't
produced by call to LoadPage, empty string is returned.

\membersection{wxHtmlWindow::SetRelatedFrame}\label{wxhtmlwindowsetrelatedframe}

\func{void}{SetRelatedFrame}{\param{wxFrame* }{frame}, \param{const wxString\& }{format}}

Sets frame in which page title will be displayed. {\it format} is format of
frame title, e.g. "HtmlHelp : \%s". It must contain exactly one \%s. This
\%s is substituted with HTML page title.

\membersection{wxHtmlWindow::GetRelatedFrame}\label{wxhtmlwindowgetrelatedframe}

\constfunc{wxFrame*}{GetRelatedFrame}{\void}

Returns the related frame.

\membersection{wxHtmlWindow::SetRelatedStatusBar}\label{wxhtmlwindowsetrelatedstatusbar}

\func{void}{SetRelatedStatusBar}{\param{int }{bar}}

{\bf After} calling \helpref{SetRelatedFrame}{wxhtmlwindowsetrelatedframe},
this sets statusbar slot where messages will be displayed.
(Default is -1 = no messages.)

\wxheading{Parameters}

\docparam{bar}{statusbar slot number (0..n)}

\membersection{wxHtmlWindow::SetFonts}\label{wxhtmlwindowsetfonts}

\func{void}{SetFonts}{\param{wxString }{normal\_face}, \param{int }{normal\_italic\_mode}, \param{wxString }{fixed\_face}, \param{int }{fixed\_italic\_mode}, \param{const int }{*sizes}}

This function sets font sizes and faces.

\wxheading{Parameters}

\docparam{normal_face}{This is face name for normal (i.e. non-fixed) font. 
It can be either empty string (then the default face is choosen) or
platform-specific face name. Examples are "helvetica" under Unix or
"Times New Roman" under Windows.}

\docparam{normal_italic_mode}{This is either wxSLANT or wxITALIC.
It determines how
italic (<I>..</I>) text is handled. See wxFont documentation for
details. For example you should use wxSLANT in conjuction with
"helvetica" face or wxITALIC with "times" face.}

\docparam{fixed_face}{The same thing for fixed face ( <TT>..</TT> )}

\docparam{fixed_italic_mode}{The same thing for fixed face.}

\docparam{sizes}{This is an array of 7 items of {\it int} type.
The values represent size of font with HTML size from -2 to +4
( <FONT SIZE=-2> to <FONT SIZE=+4> )}

\wxheading{Defaults}

Under wxGTK:

\begin{verbatim}
    SetFonts("", wxSLANT, "", wxSLANT, {10, 12, 14, 16, 19, 24, 32});
\end{verbatim}

Under Windows:

\begin{verbatim}
    SetFonts("", wxSLANT, "", wxSLANT, {7, 8, 10, 12, 16, 22, 30});
\end{verbatim}

Athough it seems different the fact is that the fonts are of approximately
same size under both platforms (due to wxMSW / wxGTK inconsistency)

\membersection{wxHtmlWindow::SetBorders}\label{wxhtmlwindowsetborders}

\func{void}{SetBorders}{\param{int }{b}}

This function sets the space between border of window and HTML contents. See image:

\image{}{border.bmp}

\wxheading{Parameters}

\docparam{b}{indentation from borders in pixels}

\membersection{wxHtmlWindow::ReadCustomization}\label{wxhtmlwindowreadcustomization}

\func{virtual void}{ReadCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}

This reads custom settings from wxConfig. It uses the path 'path'
if given, otherwise it saves info into currently selected path.
The values are stored in sub-path {\tt wxHtmlWindow}

Read values : all things set by SetFonts, SetBorders.

\wxheading{Parameters}

\docparam{cfg}{wxConfig from which you wanna read configuration}

\docparam{path}{Optional path in config tree. If not given current path is used.}

\membersection{wxHtmlWindow::WriteCustomization}\label{wxhtmlwindowwritecustomization}

\func{virtual void}{WriteCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}

Saves custom settings into wxConfig. It uses the path 'path'
if given, otherwise it saves info into currently selected path.
Regardless path is given or not the function creates sub-path 
{\tt wxHtmlWindow}

Saved values : all things set by SetFonts, SetBorders.

\wxheading{Parameters}

\docparam{cfg}{wxConfig to which you wanna save configuration}

\docparam{path}{Optional path in config tree. If not given current path is used.}


\membersection{wxHtmlWindow::GetInternalRepresentation}\label{wxhtmlwindowgetinternalrepresentation}

\constfunc{wxHtmlContainerCell*}{GetInternalRepresentation}{\void}

Returns pointer to the top-level container.

See also: \helpref{Cells Overview}{cells}, 
\helpref{Printing Overview}{printing}

\membersection{wxHtmlWindow::AddFilter}\label{wxhtmlwindowaddfilter}

\func{static void}{AddFilter}{\param{wxHtmlFilter }{*filter}}

Adds \helpref{input filter}{filters} to the static list of available
filters. These filters are present by default:

\begin{itemize}
\item {\tt text/html} MIME type
\item {\tt image/*} MIME types
\item Plain Text filter (this filter is used if no other filter matches)
\end{itemize}

\membersection{wxHtmlWindow::HistoryBack}\label{wxhtmlwindowhistoryback}

\func{bool}{HistoryBack}{\void}

Moves back to the previous page. (each page displayed using 
\helpref{LoadPage}{wxhtmlwindowloadpage} is stored in history list.)

\membersection{wxHtmlWindow::HistoryForward}\label{wxhtmlwindowhistoryforward}

\func{bool}{HistoryForward}{\void}

Moves to next page in history.

\membersection{wxHtmlWindow::HistoryClear}\label{wxhtmlwindowhistoryclear}

\func{void}{HistoryClear}{\void}

Clears history.

\membersection{wxHtmlWindow::OnLinkClicked}\label{wxhtmlwindowonlinkclicked}

\func{virtual void}{OnLinkClicked}{\param{const wxString\& }{link}}

Called when user clicks on hypertext link. Default behaviour is to call 
\helpref{LoadPage}{wxhtmlwindowloadpage} and do nothing else.
Commit	Line	Data
704a4b75 VS	1	%
	2	% automatically generated by HelpGen from
	3	% htmlwindow.tex at 14/Mar/99 20:13:37
	4	%
	5
704a4b75 VS	6	\section{\class{wxHtmlWindow}}\label{wxhtmlwindow}
	7
	8	wxHtmlWindow is probably the only class you will directly use
	9	unless you want to do something special (like adding new tag
	10	handlers or MIME filters)
	11
	12	Purpose of this class is to display HTML page (either local
	13	file or downloaded via HTTP protocol) in a window. Width
	14	of window is constant - given in constructor - virtual height
	15	is changed dynamicly depending on page size.
	16	Once the window is created you can set it's content by calling
	17	\helpref{SetPage(text)}{wxhtmlwindowsetpage} or
	18	\helpref{LoadPage(filename)}{wxhtmlwindowloadpage}.
	19
704a4b75 VS	20	\wxheading{Derived from}
	21
	22	wxScrolledWindow
	23
	24	\wxheading{Include files}
	25
	26	<wxhtml/wxhtmlwin.h>
	27
	28	\membersection{wxHtmlWindow::wxHtmlWindow}\label{wxhtmlwindowwxhtmlwindow}
	29
	30	\func{}{wxHtmlWindow}{\void}
	31
	32	Default constructor.
	33
ea8fe90e	34	\func{}{wxHtmlWindow}{\param{wxWindow }{*parent}, \param{wxWindowID }{id = -1}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = wxHW_SCROLLBAR_AUTO}, \param{const wxString\& }{name = "htmlWindow"}}
704a4b75 VS	35
	36	Constructor. The parameters are same as in wxScrollWindow ctor.
	37	(Too lazy to document it once again... :-)
	38
	39	\wxheading{Parameters}
	40
22d6efa8	41	\docparam{style}{wxHW\_SCROLLBAR\_NEVER, or wxHW\_SCROLLBAR\_AUTO.
ea8fe90e	42	Affects appearance of vertical scrollbar in the window.}
704a4b75	43
704a4b75 VS	44	\membersection{wxHtmlWindow::SetPage}\label{wxhtmlwindowsetpage}
	45
	46	\func{bool}{SetPage}{\param{const wxString\& }{source}}
	47
	48	Sets HTML page and display it. This won't {\bf load} the page!!
	49	It will display the {\it source}. See example:
	50
	51	\begin{verbatim}
	52	htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
	53	\end{verbatim}
	54
	55	If you want to load document from some location use
	56	\helpref{LoadPage}{wxhtmlwindowloadpage} instead.
	57
	58	\wxheading{Parameters}
	59
	60	\docparam{source}{The HTML document source to be displayed.}
	61
704a4b75 VS	62	\wxheading{Return value}
	63
	64	FALSE if an error occured, TRUE otherwise
	65
	66	\membersection{wxHtmlWindow::LoadPage}\label{wxhtmlwindowloadpage}
	67
	68	\func{bool}{LoadPage}{\param{const wxString\& }{location}}
	69
	70	Unlike SetPage this function first loads HTML page from {\it location}
	71	and then displays it. See example:
	72
	73	\begin{verbatim}
	74	htmlwin -> SetPage("help/myproject/index.htm");
	75	\end{verbatim}
	76
	77	\wxheading{Parameters}
	78
	79	\docparam{location}{The address of document. See \helpref{wxFileSystem}{wxfilesystem} for details on address format and behaviour of "opener".}
	80
	81	\wxheading{Return value}
	82
	83	FALSE if an error occured, TRUE otherwise
	84
704a4b75 VS	85	\membersection{wxHtmlWindow::GetOpenedPage}\label{wxhtmlwindowgetopenedpage}
	86
	87	\func{wxString}{GetOpenedPage}{\void}
	88
	89	Returns full location of the opened page. If no page is opened or if the displayed page wasn't
	90	produced by call to LoadPage, empty string is returned.
	91
704a4b75 VS	92	\membersection{wxHtmlWindow::SetRelatedFrame}\label{wxhtmlwindowsetrelatedframe}
	93
	94	\func{void}{SetRelatedFrame}{\param{wxFrame* }{frame}, \param{const wxString\& }{format}}
	95
	96	Sets frame in which page title will be displayed. {\it format} is format of
	97	frame title, e.g. "HtmlHelp : \%s". It must contain exactly one \%s. This
	98	\%s is substituted with HTML page title.
	99
704a4b75 VS	100	\membersection{wxHtmlWindow::GetRelatedFrame}\label{wxhtmlwindowgetrelatedframe}
	101
	102	\constfunc{wxFrame*}{GetRelatedFrame}{\void}
	103
	104	Returns the related frame.
	105
704a4b75 VS	106	\membersection{wxHtmlWindow::SetRelatedStatusBar}\label{wxhtmlwindowsetrelatedstatusbar}
	107
	108	\func{void}{SetRelatedStatusBar}{\param{int }{bar}}
	109
	110	{\bf After} calling \helpref{SetRelatedFrame}{wxhtmlwindowsetrelatedframe},
	111	this sets statusbar slot where messages will be displayed.
	112	(Default is -1 = no messages.)
	113
	114	\wxheading{Parameters}
	115
	116	\docparam{bar}{statusbar slot number (0..n)}
	117
	118	\membersection{wxHtmlWindow::SetFonts}\label{wxhtmlwindowsetfonts}
	119
89966d5c	120	\func{void}{SetFonts}{\param{wxString }{normal\_face}, \param{int }{normal\_italic\_mode}, \param{wxString }{fixed\_face}, \param{int }{fixed\_italic\_mode}, \param{const int }{*sizes}}
704a4b75 VS	121
	122	This function sets font sizes and faces.
	123
	124	\wxheading{Parameters}
	125
	126	\docparam{normal_face}{This is face name for normal (i.e. non-fixed) font.
	127	It can be either empty string (then the default face is choosen) or
	128	platform-specific face name. Examples are "helvetica" under Unix or
	129	"Times New Roman" under Windows.}
	130
	131	\docparam{normal_italic_mode}{This is either wxSLANT or wxITALIC.
	132	It determines how
	133	italic (<I>..</I>) text is handled. See wxFont documentation for
	134	details. For example you should use wxSLANT in conjuction with
	135	"helvetica" face or wxITALIC with "times" face.}
	136
	137	\docparam{fixed_face}{The same thing for fixed face ( <TT>..</TT> )}
	138
	139	\docparam{fixed_italic_mode}{The same thing for fixed face.}
	140
	141	\docparam{sizes}{This is an array of 7 items of {\it int} type.
	142	The values represent size of font with HTML size from -2 to +4
	143	( <FONT SIZE=-2> to <FONT SIZE=+4> )}
	144
	145	\wxheading{Defaults}
	146
	147	Under wxGTK:
	148
	149	\begin{verbatim}
	150	SetFonts("", wxSLANT, "", wxSLANT, {10, 12, 14, 16, 19, 24, 32});
	151	\end{verbatim}
	152
	153	Under Windows:
	154
	155	\begin{verbatim}
	156	SetFonts("", wxSLANT, "", wxSLANT, {7, 8, 10, 12, 16, 22, 30});
	157	\end{verbatim}
	158
	159	Athough it seems different the fact is that the fonts are of approximately
	160	same size under both platforms (due to wxMSW / wxGTK inconsistency)
	161
704a4b75 VS	162	\membersection{wxHtmlWindow::SetBorders}\label{wxhtmlwindowsetborders}
	163
	164	\func{void}{SetBorders}{\param{int }{b}}
	165
	166	This function sets the space between border of window and HTML contents. See image:
	167
	168	\image{}{border.bmp}
	169
	170	\wxheading{Parameters}
	171
	172	\docparam{b}{indentation from borders in pixels}
	173
704a4b75 VS	174	\membersection{wxHtmlWindow::ReadCustomization}\label{wxhtmlwindowreadcustomization}
	175
	176	\func{virtual void}{ReadCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}
	177
	178	This reads custom settings from wxConfig. It uses the path 'path'
	179	if given, otherwise it saves info into currently selected path.
	180	The values are stored in sub-path {\tt wxHtmlWindow}
	181
	182	Read values : all things set by SetFonts, SetBorders.
	183
	184	\wxheading{Parameters}
	185
	186	\docparam{cfg}{wxConfig from which you wanna read configuration}
	187
	188	\docparam{path}{Optional path in config tree. If not given current path is used.}
	189
704a4b75 VS	190	\membersection{wxHtmlWindow::WriteCustomization}\label{wxhtmlwindowwritecustomization}
	191
	192	\func{virtual void}{WriteCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}
	193
	194	Saves custom settings into wxConfig. It uses the path 'path'
	195	if given, otherwise it saves info into currently selected path.
22d6efa8	196	Regardless path is given or not the function creates sub-path
704a4b75 VS	197	{\tt wxHtmlWindow}
	198
	199	Saved values : all things set by SetFonts, SetBorders.
	200
	201	\wxheading{Parameters}
	202
	203	\docparam{cfg}{wxConfig to which you wanna save configuration}
	204
	205	\docparam{path}{Optional path in config tree. If not given current path is used.}
	206
	207
	208	\membersection{wxHtmlWindow::GetInternalRepresentation}\label{wxhtmlwindowgetinternalrepresentation}
	209
	210	\constfunc{wxHtmlContainerCell*}{GetInternalRepresentation}{\void}
	211
	212	Returns pointer to the top-level container.
	213
22d6efa8	214	See also: \helpref{Cells Overview}{cells},
704a4b75 VS	215	\helpref{Printing Overview}{printing}
704a4b75 VS	216
704a4b75 VS	217	\membersection{wxHtmlWindow::AddFilter}\label{wxhtmlwindowaddfilter}
	218
	219	\func{static void}{AddFilter}{\param{wxHtmlFilter }{*filter}}
	220
	221	Adds \helpref{input filter}{filters} to the static list of available
	222	filters. These filters are present by default:
	223
	224	\begin{itemize}
	225	\item {\tt text/html} MIME type
	226	\item {\tt image/*} MIME types
	227	\item Plain Text filter (this filter is used if no other filter matches)
	228	\end{itemize}
	229
704a4b75 VS	230	\membersection{wxHtmlWindow::HistoryBack}\label{wxhtmlwindowhistoryback}
	231
	232	\func{bool}{HistoryBack}{\void}
	233
	234	Moves back to the previous page. (each page displayed using
	235	\helpref{LoadPage}{wxhtmlwindowloadpage} is stored in history list.)
	236
704a4b75 VS	237	\membersection{wxHtmlWindow::HistoryForward}\label{wxhtmlwindowhistoryforward}
	238
	239	\func{bool}{HistoryForward}{\void}
	240
	241	Moves to next page in history.
	242
	243	\membersection{wxHtmlWindow::HistoryClear}\label{wxhtmlwindowhistoryclear}
	244
	245	\func{void}{HistoryClear}{\void}
	246
	247	Clears history.
	248
704a4b75 VS	249	\membersection{wxHtmlWindow::OnLinkClicked}\label{wxhtmlwindowonlinkclicked}
	250
	251	\func{virtual void}{OnLinkClicked}{\param{const wxString\& }{link}}
	252
22d6efa8	253	Called when user clicks on hypertext link. Default behaviour is to call
704a4b75 VS	254	\helpref{LoadPage}{wxhtmlwindowloadpage} and do nothing else.
704a4b75 VS	255