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