docs/latex/wx/htmlcell.tex

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