docs/latex/wx/htcell.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        htcell.tex
   3 %% Purpose:     wxHtmlCell documentation
   4 %% Author:      wxWidgets Team
   5 %% Modified by:
   6 %% Created:     21/Mar/99 22:45:23
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) wxWidgets Team
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxHtmlCell}}\label{wxhtmlcell}
  13
  14 Internal data structure. It represents fragments of parsed HTML
  15 page, the so-called {\bf cell} - a word, picture, table, horizontal line and so on.
  16 It is used by \helpref{wxHtmlWindow}{wxhtmlwindow} and
  17 \helpref{wxHtmlWinParser}{wxhtmlwinparser} to represent HTML page in memory.
  18
  19 You can divide cells into two groups : {\it visible} cells with non-zero width and
  20 height and {\it helper} cells (usually with zero width and height) that
  21 perform special actions such as color or font change.
  22
  23 \wxheading{Derived from}
  24
  25 \helpref{wxObject}{wxobject}
  26
  27 \wxheading{Include files}
  28
  29 <wx/html/htmlcell.h>
  30
  31 \wxheading{Library}
  32
  33 \helpref{wxHtml}{librarieslist}
  34
  35 \wxheading{See Also}
  36
  37 \helpref{Cells Overview}{cells},
  38 \helpref{wxHtmlContainerCell}{wxhtmlcontainercell}
  39
  40 \latexignore{\rtfignore{\wxheading{Members}}}
  41
  42 \membersection{wxHtmlCell::wxHtmlCell}\label{wxhtmlcellwxhtmlcell}
  43
  44 \func{}{wxHtmlCell}{\void}
  45
  46 Constructor.
  47
  48 \membersection{wxHtmlCell::AdjustPagebreak}\label{wxhtmlcelladjustpagebreak}
  49
  50 \func{virtual bool}{AdjustPagebreak}{\param{int * }{pagebreak}}
  51
  52 This method is used to adjust pagebreak position. The parameter is
  53 variable that contains y-coordinate of page break (= horizontal line that
  54 should not be crossed by words, images etc.). If this cell cannot be divided
  55 into two pieces (each one on another page) then it moves the pagebreak
  56 few pixels up.
  57
  58 Returns true if pagebreak was modified, false otherwise
  59
  60 Usage:
  61 \begin{verbatim}
  62 while (container->AdjustPagebreak(&p)) {}
  63 \end{verbatim}
  64
  65 \membersection{wxHtmlCell::Draw}\label{wxhtmlcelldraw}
  66
  67 \func{virtual void}{Draw}{\param{wxDC\& }{dc}, \param{int }{x}, \param{int }{y}, \param{int }{view\_y1}, \param{int }{view\_y2}}
  68
  69 Renders the cell.
  70
  71 \wxheading{Parameters}
  72
  73 \docparam{dc}{Device context to which the cell is to be drawn}
  74
  75 \docparam{x,y}{Coordinates of parent's upper left corner (origin). You must
  76 add this to m\_PosX,m\_PosY when passing coordinates to dc's methods
  77 Example : {\tt dc -> DrawText("hello", x + m\_PosX, y + m\_PosY)}}
  78
  79 \docparam{view\_y1}{y-coord of the first line visible in window. This is
  80 used to optimize rendering speed}
  81
  82 \docparam{view\_y2}{y-coord of the last line visible in window. This is
  83 used to optimize rendering speed}
  84
  85 \membersection{wxHtmlCell::DrawInvisible}\label{wxhtmlcelldrawinvisible}
  86
  87 \func{virtual void}{DrawInvisible}{\param{wxDC\& }{dc}, \param{int }{x}, \param{int }{y}}
  88
  89 This method is called instead of \helpref{Draw}{wxhtmlcelldraw} when the
  90 cell is certainly out of the screen (and thus invisible). This is not
  91 nonsense - some tags (like \helpref{wxHtmlColourCell}{wxhtmlcolourcell}
  92 or font setter) must be drawn even if they are invisible!
  93
  94 \wxheading{Parameters}
  95
  96 \docparam{dc}{Device context to which the cell is to be drawn}
  97
  98 \docparam{x,y}{Coordinates of parent's upper left corner. You must
  99 add this to m\_PosX,m\_PosY when passing coordinates to dc's methods
 100 Example : {\tt dc -> DrawText("hello", x + m\_PosX, y + m\_PosY)}}
 101
 102 \membersection{wxHtmlCell::Find}\label{wxhtmlcellfind}
 103
 104 \func{virtual const wxHtmlCell*}{Find}{\param{int }{condition}, \param{const void* }{param}}
 105
 106 Returns pointer to itself if this cell matches condition (or if any of the cells
 107 following in the list matches), NULL otherwise.
 108 (In other words if you call top-level container's Find it will
 109 return pointer to the first cell that matches the condition)
 110
 111 It is recommended way how to obtain pointer to particular cell or
 112 to cell of some type (e.g. wxHtmlAnchorCell reacts on
 113 wxHTML\_COND\_ISANCHOR condition)
 114
 115 \wxheading{Parameters}
 116
 117 \docparam{condition}{Unique integer identifier of condition}
 118
 119 \docparam{param}{Optional parameters}
 120
 121 \wxheading{Defined conditions}
 122
 123 \begin{twocollist}\itemsep=0pt
 124 \twocolitem{{\bf wxHTML\_COND\_ISANCHOR}}{Finds particular anchor.
 125 {\it param} is pointer to wxString with name of the anchor.}
 126 \twocolitem{{\bf wxHTML\_COND\_USER}}{User-defined conditions start
 127 from this number.}
 128 \end{twocollist}
 129
 130 \membersection{wxHtmlCell::GetDescent}\label{wxhtmlcellgetdescent}
 131
 132 \constfunc{int}{GetDescent}{\void}
 133
 134 Returns descent value of the cell (m\_Descent member).
 135 \helponly{See explanation:
 136
 137 \image{}{descent.bmp}
 138 }
 139
 140 \membersection{wxHtmlCell::GetFirstChild}\label{wxhtmlcellgetfirstchild}
 141
 142 \func{wxHtmlCell*}{GetFirstChild}{\void}
 143
 144 Returns pointer to the first cell in the list.
 145 You can then use child's \helpref{GetNext}{wxhtmlcellgetnext}
 146 method to obtain pointer to the next cell in list.
 147
 148 {\bf Note:} This shouldn't be used by the end user. If you need some way of
 149 finding particular cell in the list, try \helpref{Find}{wxhtmlcellfind} method
 150 instead.
 151
 152 \membersection{wxHtmlCell::GetHeight}\label{wxhtmlcellgetheight}
 153
 154 \constfunc{int}{GetHeight}{\void}
 155
 156 Returns height of the cell (m\_Height member).
 157
 158 \membersection{wxHtmlCell::GetId}\label{wxhtmlcellgetid}
 159
 160 \constfunc{virtual wxString}{GetId}{\void}
 161
 162 Returns unique cell identifier if there is any, empty string otherwise.
 163
 164 \membersection{wxHtmlCell::GetLink}\label{wxhtmlcellgetlink}
 165
 166 \constfunc{virtual wxHtmlLinkInfo*}{GetLink}{\param{int }{x = 0}, \param{int }{y = 0}}
 167
 168 Returns hypertext link if associated with this cell or NULL otherwise.
 169 See \helpref{wxHtmlLinkInfo}{wxhtmllinkinfo}.
 170 (Note: this makes sense only for visible tags).
 171
 172 \wxheading{Parameters}
 173
 174 \docparam{x,y}{Coordinates of position where the user pressed mouse button.
 175 These coordinates are used e.g. by COLORMAP. Values are relative to the
 176 upper left corner of THIS cell (i.e. from 0 to m\_Width or m\_Height)}
 177
 178 \membersection{wxHtmlCell::GetMouseCursor}\label{wxhtmlcellgetmousecursor}
 179
 180 \func{virtual wxCursor}{GetMouseCursor}{\param{wxHtmlWindowInterface* }{window}}
 181
 182 Returns cursor to show when mouse pointer is over the cell.
 183
 184 \wxheading{Parameters}
 185
 186 \docparam{window}{interface to the parent HTML window}
 187
 188 \newsince{2.7.0} (before \tt{GetCursor} method served a similar purpose, which is now deprecated).
 189
 190
 191 \membersection{wxHtmlCell::GetNext}\label{wxhtmlcellgetnext}
 192
 193 \constfunc{wxHtmlCell*}{GetNext}{\void}
 194
 195 Returns pointer to the next cell in list (see htmlcell.h if you're
 196 interested in details).
 197
 198 \membersection{wxHtmlCell::GetParent}\label{wxhtmlcellgetparent}
 199
 200 \constfunc{wxHtmlContainerCell*}{GetParent}{\void}
 201
 202 Returns pointer to parent container.
 203
 204 \membersection{wxHtmlCell::GetPosX}\label{wxhtmlcellgetposx}
 205
 206 \constfunc{int}{GetPosX}{\void}
 207
 208 Returns X position within parent (the value is relative to parent's
 209 upper left corner). The returned value is meaningful only if
 210 parent's \helpref{Layout}{wxhtmlcelllayout} was called before!
 211
 212 \membersection{wxHtmlCell::GetPosY}\label{wxhtmlcellgetposy}
 213
 214 \constfunc{int}{GetPosY}{\void}
 215
 216 Returns Y position within parent (the value is relative to parent's
 217 upper left corner). The returned value is meaningful only if
 218 parent's \helpref{Layout}{wxhtmlcelllayout} was called before!
 219
 220 \membersection{wxHtmlCell::GetWidth}\label{wxhtmlcellgetwidth}
 221
 222 \constfunc{int}{GetWidth}{\void}
 223
 224 Returns width of the cell (m\_Width member).
 225
 226 \membersection{wxHtmlCell::Layout}\label{wxhtmlcelllayout}
 227
 228 \func{virtual void}{Layout}{\param{int }{w}}
 229
 230 This method performs two actions:
 231
 232 \begin{enumerate}\itemsep=0pt
 233 \item adjusts the cell's width according to the fact that maximal possible width is {\it w}.
 234 (this has sense when working with horizontal lines, tables etc.)
 235 \item prepares layout (=fill-in m\_PosX, m\_PosY (and sometimes m\_Height) members)
 236 based on actual width {\it w}
 237 \end{enumerate}
 238
 239 It must be called before displaying cells structure because
 240 m\_PosX and m\_PosY are undefined (or invalid)
 241 before calling Layout.
 242
 243 \membersection{wxHtmlCell::ProcessMouseClick}\label{wxhtmlcellprocessmouseclick}
 244
 245 \func{virtual bool}{ProcessMouseClick}{\param{wxHtmlWindowInterface* }{window}, \param{const wxPoint\& }{pos}, \param{const wxMouseEvent\& }{event}}
 246
 247 This function is simple event handler. Each time the user clicks mouse button
 248 over a cell within \helpref{wxHtmlWindow}{wxhtmlwindow} this method of that
 249 cell is called. Default behavior is to call
 250 \helpref{wxHtmlWindow::LoadPage}{wxhtmlwindowloadpage}.
 251
 252 \wxheading{Note}
 253
 254 If you need more "advanced" event handling
 255 you should use wxHtmlBinderCell instead.
 256
 257 \wxheading{Parameters}
 258
 259 \docparam{window}{interface to the parent HTML window}
 260
 261 \docparam{pos}{coordinates of mouse click (this is relative to cell's origin}
 262
 263 \docparam{event}{mouse event that triggered the call}
 264
 265 \wxheading{Return value}
 266
 267 \true if a link was clicked, \false otherwise.
 268
 269 \newsince{2.7.0} (before \tt{OnMouseClick} method served a similar purpose).
 270
 271
 272 \membersection{wxHtmlCell::SetId}\label{wxhtmlcellsetid}
 273
 274 \func{void}{SetId}{\param{const wxString\& }{id}}
 275
 276 Sets unique cell identifier. Default value is no identifier, i.e. empty string.
 277
 278 \membersection{wxHtmlCell::SetLink}\label{wxhtmlcellsetlink}
 279
 280 \func{void}{SetLink}{\param{const wxHtmlLinkInfo\& }{link}}
 281
 282 Sets the hypertext link associated with this cell. (Default value
 283 is \helpref{wxHtmlLinkInfo}{wxhtmllinkinfo}("", "") (no link))
 284
 285 \membersection{wxHtmlCell::SetNext}\label{wxhtmlcellsetnext}
 286
 287 \func{void}{SetNext}{\param{wxHtmlCell }{*cell}}
 288
 289 Sets the next cell in the list. This shouldn't be called by user - it is
 290 to be used only by \helpref{wxHtmlContainerCell::InsertCell}{wxhtmlcontainercellinsertcell}.
 291
 292 \membersection{wxHtmlCell::SetParent}\label{wxhtmlcellsetparent}
 293
 294 \func{void}{SetParent}{\param{wxHtmlContainerCell }{*p}}
 295
 296 Sets parent container of this cell. This is called from
 297 \helpref{wxHtmlContainerCell::InsertCell}{wxhtmlcontainercellinsertcell}.
 298
 299 \membersection{wxHtmlCell::SetPos}\label{wxhtmlcellsetpos}
 300
 301 \func{void}{SetPos}{\param{int }{x}, \param{int }{y}}
 302
 303 Sets the cell's position within parent container.
 304