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

\subsection{Cells and Containers}\label{cells}

This article describes mechanism used by 
\helpref{wxHtmlWinParser}{wxhtmlwinparser} and
\helpref{wxHtmlWindow}{wxhtmlwindow}
to parse and display HTML documents.

\wxheading{Cells}

You can divide any text (or HTML) into small fragments. Let's call these
fragments {\bf cells}. Cell is for example one word, horizontal line, image
or any other part of document. Each cell has width and height (except special
"magic" cells with zero dimensions - e.g. color changers or font changers).

See \helpref{wxHtmlCell}{wxhtmlcell}.

\wxheading{Containers}

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). 

See \helpref{wxHtmlContainerCell}{wxhtmlcontainercell}, 
\helpref{wxHtmlCell::Layout}{wxhtmlcelllayout}.

This image shows you cells\ &\ containers:

\image{}{contbox.bmp}

\wxheading{Using Containers in Tag Handler}

\helpref{wxHtmlWinParser}{wxhtmlwinparser} provides user-friendly way
of managing containers. It's based on idea of opening and closing containers.

Use \helpref{OpenContainer}{wxhtmlwinparseropencontainer} to open new
container {\it within actually opened container}. This new container is 
{\it sub-container} of the old one. (If you want to create new container with
same depth level you can call {\tt CloseContainer(); OpenContainer();}.)

Use \helpref{CloseContaier}{wxhtmlwinparserclosecontainer} to close the 
container. This doesn't create new container with same depth level but
it returns "control" to the parent container.

See explanation:

\image{}{cont.bmp}

It's clear there must be same number of calls to 
OpenContainer as to CloseContainer...

\wxheading{Example}

This code creates new paragraph (container at same depth level)
with "Hello, world!" :

\begin{verbatim}
m_WParser -> CloseContainer();
c = m_WParser -> OpenContainer();

m_WParser -> AddWord("Hello, ");
m_WParser -> AddWord("world!");

m_WParser -> CloseContainer();
m_WParser -> OpenContainer();
\end{verbatim}

and here is image of the situation:

\image{}{hello.bmp}

You can see that there was opened container before running the code. We closed
it, created our own container, then closed our container and opened
new container. The result was that we had {\it 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 \helpref{HandleTag}{wxhtmltaghandlerhandletag}'s body).
Commit	Line	Data
704a4b75 VS	1	\subsection{Cells and Containers}\label{cells}
	2
	3	This article describes mechanism used by
	4	\helpref{wxHtmlWinParser}{wxhtmlwinparser} and
	5	\helpref{wxHtmlWindow}{wxhtmlwindow}
	6	to parse and display HTML documents.
	7
	8	\wxheading{Cells}
	9
	10	You can divide any text (or HTML) into small fragments. Let's call these
	11	fragments {\bf cells}. Cell is for example one word, horizontal line, image
	12	or any other part of document. Each cell has width and height (except special
	13	"magic" cells with zero dimensions - e.g. color changers or font changers).
	14
	15	See \helpref{wxHtmlCell}{wxhtmlcell}.
	16
	17	\wxheading{Containers}
	18
	19	Container is kind of cell that may contain sub-cells. Its size depends
	20	on number and sizes of its sub-cells (and also depends on width of window).
	21
	22	See \helpref{wxHtmlContainerCell}{wxhtmlcontainercell},
	23	\helpref{wxHtmlCell::Layout}{wxhtmlcelllayout}.
	24
	25	This image shows you cells\ &\ containers:
	26
	27	\image{}{contbox.bmp}
	28
	29	\wxheading{Using Containers in Tag Handler}
	30
	31	\helpref{wxHtmlWinParser}{wxhtmlwinparser} provides user-friendly way
	32	of managing containers. It's based on idea of opening and closing containers.
	33
	34	Use \helpref{OpenContainer}{wxhtmlwinparseropencontainer} to open new
	35	container {\it within actually opened container}. This new container is
	36	{\it sub-container} of the old one. (If you want to create new container with
	37	same depth level you can call {\tt CloseContainer(); OpenContainer();}.)
	38
	39	Use \helpref{CloseContaier}{wxhtmlwinparserclosecontainer} to close the
	40	container. This doesn't create new container with same depth level but
	41	it returns "control" to the parent container.
	42
	43	See explanation:
	44
	45	\image{}{cont.bmp}
	46
	47	It's clear there must be same number of calls to
	48	OpenContainer as to CloseContainer...
	49
	50	\wxheading{Example}
	51
	52	This code creates new paragraph (container at same depth level)
	53	with "Hello, world!" :
	54
	55	\begin{verbatim}
	56	m_WParser -> CloseContainer();
	57	c = m_WParser -> OpenContainer();
	58
	59	m_WParser -> AddWord("Hello, ");
	60	m_WParser -> AddWord("world!");
	61
	62	m_WParser -> CloseContainer();
	63	m_WParser -> OpenContainer();
	64	\end{verbatim}
65
66	and here is image of the situation:
67
68	\image{}{hello.bmp}
69
70	You can see that there was opened container before running the code. We closed
71	it, created our own container, then closed our container and opened
72	new container. The result was that we had {\it same depth level} after
73	executing. This is general rule that should be followed by tag handlers :
74	leave depth level of containers unmodified (in other words, number of
75	OpenContainer and CloseContainer calls should be same within \helpref{HandleTag}{wxhtmltaghandlerhandletag}'s body).
76