interface/wx/html/htmlcell.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/htmlcell.h
   3 // Purpose:     interface of wxHtml*Cell
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHtmlColourCell
  11
  12     This cell changes the colour of either the background or the foreground.
  13
  14     @library{wxhtml}
  15     @category{html}
  16 */
  17 class wxHtmlColourCell : public wxHtmlCell
  18 {
  19 public:
  20     /**
  21         Constructor.
  22
  23         @param clr
  24             The color
  25         @param flags
  26             Can be one of following:
  27             - wxHTML_CLR_FOREGROUND: change color of text
  28             - wxHTML_CLR_BACKGROUND: change background color
  29     */
  30     wxHtmlColourCell(const wxColour& clr, int flags = wxHTML_CLR_FOREGROUND);
  31 };
  32
  33
  34
  35 /**
  36     @class wxHtmlWidgetCell
  37
  38     wxHtmlWidgetCell is a class that provides a connection between HTML cells and
  39     widgets (an object derived from wxWindow).
  40     You can use it to display things like forms, input boxes etc. in an HTML window.
  41
  42     wxHtmlWidgetCell takes care of resizing and moving window.
  43
  44     @library{wxhtml}
  45     @category{html}
  46 */
  47 class wxHtmlWidgetCell : public wxHtmlCell
  48 {
  49 public:
  50     /**
  51         Constructor.
  52
  53         @param wnd
  54             Connected window. It is parent window @b must be the wxHtmlWindow object
  55             within which it is displayed!
  56         @param w
  57             Floating width. If non-zero width of wnd window is adjusted so that it is
  58             always w percents of parent container's width. (For example w = 100 means
  59             that the window will always have same width as parent container).
  60     */
  61     wxHtmlWidgetCell(wxWindow* wnd, int w = 0);
  62 };
  63
  64
  65
  66 /**
  67     @class wxHtmlCell
  68
  69     Internal data structure. It represents fragments of parsed HTML page, the
  70     so-called @b cell - a word, picture, table, horizontal line and so on.
  71     It is used by wxHtmlWindow and wxHtmlWinParser to represent HTML page in memory.
  72
  73     You can divide cells into two groups : @e visible cells with non-zero width and
  74     height and @e helper cells (usually with zero width and height) that perform
  75     special actions such as color or font change.
  76
  77     @library{wxhtml}
  78     @category{html}
  79
  80     @see @ref overview_html_cells, wxHtmlContainerCell
  81 */
  82 class wxHtmlCell : public wxObject
  83 {
  84 public:
  85     /**
  86         Constructor.
  87     */
  88     wxHtmlCell();
  89
  90     /**
  91         This method is used to adjust pagebreak position.
  92         The parameter is variable that contains y-coordinate of page break
  93         (= horizontal line that should not be crossed by words, images etc.).
  94         If this cell cannot be divided into two pieces (each one on another page)
  95         then it moves the pagebreak few pixels up.
  96         Returns @true if pagebreak was modified, @false otherwise.
  97
  98         Usage:
  99         @code
 100         while (container->AdjustPagebreak(&p)) {}
 101         @endcode
 102     */
 103     virtual bool AdjustPagebreak(int* pagebreak,
 104                                  wxArrayInt& known_pagebreaks) const;
 105
 106     /**
 107         Renders the cell.
 108
 109         @param dc
 110             Device context to which the cell is to be drawn
 111         @param x,y
 112             Coordinates of parent's upper left corner (origin). You must
 113             add this to m_PosX,m_PosY when passing coordinates to dc's methods
 114             Example:
 115             @code
 116                 dc->DrawText("hello", x + m_PosX, y + m_PosY)
 117             @endcode
 118         @param view_y1
 119             y-coord of the first line visible in window.
 120             This is used to optimize rendering speed
 121         @param view_y2
 122             y-coord of the last line visible in window.
 123             This is used to optimize rendering speed
 124     */
 125     virtual void Draw(wxDC& dc, int x, int y, int view_y1, int view_y2, wxHtmlRenderingInfo& info);
 126
 127     /**
 128         This method is called instead of Draw() when the cell is certainly out of
 129         the screen (and thus invisible). This is not nonsense - some tags (like
 130         wxHtmlColourCell or font setter) must be drawn even if they are invisible!
 131
 132         @param dc
 133             Device context to which the cell is to be drawn.
 134         @param x,y
 135             Coordinates of parent's upper left corner. You must
 136             add this to m_PosX,m_PosY when passing coordinates to dc's methods
 137             Example:
 138             @code
 139                 dc->DrawText("hello", x + m_PosX, y + m_PosY)
 140             @endcode
 141     */
 142     virtual void DrawInvisible(wxDC& cd, int x , int y, wxHtmlRenderingInfo& info);
 143
 144     /**
 145         Returns pointer to itself if this cell matches condition (or if any of the
 146         cells following in the list matches), @NULL otherwise.
 147         (In other words if you call top-level container's Find() it will
 148         return pointer to the first cell that matches the condition)
 149
 150         It is recommended way how to obtain pointer to particular cell or
 151         to cell of some type (e.g. wxHtmlAnchorCell reacts on wxHTML_COND_ISANCHOR
 152         condition).
 153
 154         @param condition
 155             Unique integer identifier of condition
 156         @param param
 157             Optional parameters
 158     */
 159     virtual const wxHtmlCell* Find(int condition, const void* param) const;
 160
 161     /**
 162         Returns descent value of the cell (m_Descent member).
 163         See explanation:
 164         @image html descent.png
 165     */
 166     int GetDescent() const;
 167
 168     /**
 169         Returns pointer to the first cell in the list.
 170         You can then use child's GetNext() method to obtain pointer to the next
 171         cell in list.
 172
 173         @note This shouldn't be used by the end user. If you need some way of
 174               finding particular cell in the list, try Find() method instead.
 175     */
 176     virtual wxHtmlCell* GetFirstChild() const;
 177
 178     /**
 179         Returns height of the cell (m_Height member).
 180     */
 181     int GetHeight() const;
 182
 183     /**
 184         Returns unique cell identifier if there is any, the empty string otherwise.
 185     */
 186     const wxString& GetId() const;
 187
 188     /**
 189         Returns hypertext link if associated with this cell or @NULL otherwise.
 190         See wxHtmlLinkInfo. (Note: this makes sense only for visible tags).
 191
 192         @param x,y
 193             Coordinates of position where the user pressed mouse button.
 194             These coordinates are used e.g. by COLORMAP. Values are relative to the
 195             upper left corner of THIS cell (i.e. from 0 to m_Width or m_Height)
 196     */
 197     virtual wxHtmlLinkInfo* GetLink(int x = 0, int y = 0) const;
 198
 199     /**
 200         Returns cursor to show when mouse pointer is over the cell.
 201
 202         @param window
 203             interface to the parent HTML window
 204     */
 205     virtual wxCursor GetMouseCursor(wxHtmlWindowInterface* window) const;
 206
 207     /**
 208         Returns pointer to the next cell in list (see htmlcell.h if you're
 209         interested in details).
 210     */
 211     wxHtmlCell* GetNext() const;
 212
 213     /**
 214         Returns pointer to parent container.
 215     */
 216     wxHtmlContainerCell* GetParent() const;
 217
 218     /**
 219         Returns X position within parent (the value is relative to parent's
 220         upper left corner). The returned value is meaningful only if
 221         parent's Layout() was called before!
 222     */
 223     int GetPosX() const;
 224
 225     /**
 226         Returns Y position within parent (the value is relative to parent's
 227         upper left corner). The returned value is meaningful only if
 228         parent's Layout() was called before!
 229     */
 230     int GetPosY() const;
 231
 232     /**
 233         Returns width of the cell (m_Width member).
 234     */
 235     int GetWidth() const;
 236
 237     /**
 238         This method performs two actions:
 239         -# adjusts the cell's width according to the fact that maximal possible
 240            width is @e w. (this has sense when working with horizontal lines, tables etc.)
 241         -# prepares layout (=fill-in m_PosX, m_PosY (and sometimes m_Height) members)
 242            based on actual width @e w
 243
 244         It must be called before displaying cells structure because m_PosX and
 245         m_PosY are undefined (or invalid) before calling Layout().
 246     */
 247     virtual void Layout(int w);
 248
 249     /**
 250         This function is simple event handler.
 251         Each time the user clicks mouse button over a cell within wxHtmlWindow
 252         this method of that cell is called.
 253         Default behavior is to call wxHtmlWindow::LoadPage.
 254
 255         @param window
 256             interface to the parent HTML window
 257         @param pos
 258             coordinates of mouse click (this is relative to cell's origin
 259         @param event
 260             mouse event that triggered the call
 261
 262         @return @true if a link was clicked, @false otherwise.
 263
 264         @since 2.7.0 (before OnMouseClick() method served a similar purpose).
 265
 266         @note
 267         If you need more "advanced" event handling you should use wxHtmlBinderCell instead.
 268     */
 269     virtual bool ProcessMouseClick(wxHtmlWindowInterface* window,
 270                                    const wxPoint& pos,
 271                                    const wxMouseEvent& event);
 272
 273     /**
 274         Sets unique cell identifier. Default value is no identifier, i.e. empty string.
 275     */
 276     void SetId(const wxString& id);
 277
 278     /**
 279         Sets the hypertext link associated with this cell.
 280         (Default value is wxHtmlLinkInfo("", "") (no link))
 281     */
 282     void SetLink(const wxHtmlLinkInfo& link);
 283
 284     /**
 285         Sets the next cell in the list. This shouldn't be called by user - it is
 286         to be used only by wxHtmlContainerCell::InsertCell.
 287     */
 288     void SetNext(wxHtmlCell* cell);
 289
 290     /**
 291         Sets parent container of this cell.
 292         This is called from wxHtmlContainerCell::InsertCell.
 293     */
 294     void SetParent(wxHtmlContainerCell* p);
 295
 296     /**
 297         Sets the cell's position within parent container.
 298     */
 299     virtual void SetPos(int x, int y);
 300 };
 301
 302
 303
 304 /**
 305     @class wxHtmlContainerCell
 306
 307     The wxHtmlContainerCell class is an implementation of a cell that may
 308     contain more cells in it. It is heavily used in the wxHTML layout algorithm.
 309
 310     @library{wxhtml}
 311     @category{html}
 312
 313     @see @ref overview_html_cells
 314 */
 315 class wxHtmlContainerCell : public wxHtmlCell
 316 {
 317 public:
 318     /**
 319         Constructor. @a parent is pointer to parent container or @NULL.
 320     */
 321     wxHtmlContainerCell(wxHtmlContainerCell* parent);
 322
 323     /**
 324         Returns container's horizontal alignment.
 325     */
 326     int GetAlignHor() const;
 327
 328     /**
 329         Returns container's vertical alignment.
 330     */
 331     int GetAlignVer() const;
 332
 333     /**
 334         Returns the background colour of the container or @c wxNullColour if no
 335         background colour is set.
 336     */
 337     wxColour GetBackgroundColour();
 338
 339     /**
 340         Returns the indentation. @a ind is one of the @b wxHTML_INDENT_* constants.
 341
 342         @note You must call GetIndentUnits() with same @a ind parameter in order
 343               to correctly interpret the returned integer value.
 344               It is NOT always in pixels!
 345     */
 346     int GetIndent(int ind) const;
 347
 348     /**
 349         Returns the units of indentation for @a ind where @a ind is one
 350         of the @b wxHTML_INDENT_* constants.
 351     */
 352     int GetIndentUnits(int ind) const;
 353
 354     /**
 355         Inserts a new cell into the container.
 356     */
 357     void InsertCell(wxHtmlCell* cell);
 358
 359     /**
 360         Sets the container's alignment (both horizontal and vertical) according to
 361         the values stored in @e tag. (Tags @c ALIGN parameter is extracted.)
 362         In fact it is only a front-end to SetAlignHor() and SetAlignVer().
 363     */
 364     void SetAlign(const wxHtmlTag& tag);
 365
 366     /**
 367         Sets the container's @e horizontal alignment.
 368         During wxHtmlCell::Layout each line is aligned according to @a al value.
 369
 370         @param al
 371             new horizontal alignment. May be one of these values:
 372             - wxHTML_ALIGN_LEFT: lines are left-aligned (default)
 373             - wxHTML_ALIGN_JUSTIFY: lines are justified
 374             - wxHTML_ALIGN_CENTER: lines are centered
 375             - wxHTML_ALIGN_RIGHT: lines are right-aligned
 376     */
 377     void SetAlignHor(int al);
 378
 379     /**
 380         Sets the container's @e vertical alignment. This is per-line alignment!
 381
 382         @param al
 383             new vertical alignment. May be one of these values:
 384             - wxHTML_ALIGN_BOTTOM: cells are over the line (default)
 385             - wxHTML_ALIGN_CENTER: cells are centered on line
 386             - wxHTML_ALIGN_TOP: cells are under the line
 387
 388         @image html alignv.png
 389     */
 390     void SetAlignVer(int al);
 391
 392     /**
 393         Sets the background colour for this container.
 394     */
 395     void SetBackgroundColour(const wxColour& clr);
 396
 397     /**
 398         Sets the border (frame) colours. A border is a rectangle around the container.
 399
 400         @param clr1
 401             Colour of top and left lines
 402         @param clr2
 403             Colour of bottom and right lines
 404     */
 405     void SetBorder(const wxColour& clr1, const wxColour& clr2);
 406
 407     /**
 408         Sets the indentation (free space between borders of container and subcells).
 409
 410         @image html indent.png
 411
 412         @param i
 413             Indentation value.
 414         @param what
 415             Determines which of the four borders we're setting. It is OR
 416             combination of following constants:
 417             - wxHTML_INDENT_TOP: top border
 418             - wxHTML_INDENT_BOTTOM: bottom
 419             - wxHTML_INDENT_LEFT: left
 420             - wxHTML_INDENT_RIGHT: right
 421             - wxHTML_INDENT_HORIZONTAL: left and right
 422             - wxHTML_INDENT_VERTICAL: top and bottom
 423             - wxHTML_INDENT_ALL: all 4 borders
 424         @param units
 425             Units of i. This parameter affects interpretation of value.
 426             - wxHTML_UNITS_PIXELS: @a i is number of pixels
 427             - wxHTML_UNITS_PERCENT: @a i is interpreted as percents of width
 428                                     of parent container
 429     */
 430     void SetIndent(int i, int what, int units = wxHTML_UNITS_PIXELS);
 431
 432     /**
 433         Sets minimal height of the container.
 434         When container's wxHtmlCell::Layout is called, m_Height is set depending
 435         on layout of subcells to the height of area covered by layed-out subcells.
 436         Calling this method guarantees you that the height of container is never
 437         smaller than @a h - even if the subcells cover much smaller area.
 438
 439         @param h
 440             The minimal height.
 441         @param align
 442             If height of the container is lower than the minimum height, empty space
 443             must be inserted somewhere in order to ensure minimal height.
 444             This parameter is one of @c wxHTML_ALIGN_TOP, @c wxHTML_ALIGN_BOTTOM,
 445             @c wxHTML_ALIGN_CENTER. It refers to the contents, not to the
 446             empty place.
 447     */
 448     void SetMinHeight(int h, int align = wxHTML_ALIGN_TOP);
 449
 450     /**
 451         Sets floating width adjustment.
 452
 453         The normal behaviour of container is that its width is the same as the width of
 454         parent container (and thus you can have only one sub-container per line).
 455         You can change this by setting the floating width adjustment.
 456
 457         @param w
 458             Width of the container. If the value is negative it means
 459             complement to full width of parent container.
 460             E.g. @code SetWidthFloat(-50, wxHTML_UNITS_PIXELS) @endcode sets the
 461             width of container to parent's width minus 50 pixels. This is useful when
 462             creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50).
 463         @param units
 464             Units of w This parameter affects the interpretation of  value.
 465             - wxHTML_UNITS_PIXELS: @a w is number of pixels
 466             - wxHTML_UNITS_PERCENT: @a w is interpreted as percents of width
 467                                     of parent container
 468     */
 469     void SetWidthFloat(int w, int units);
 470
 471     /**
 472         Sets floating width adjustment.
 473
 474         The normal behaviour of container is that its width is the same as the width of
 475         parent container (and thus you can have only one sub-container per line).
 476         You can change this by setting the floating width adjustment.
 477
 478         @param tag
 479             In the second version of method, @a w and @a units info is extracted
 480             from tag's WIDTH parameter.
 481         @param pixel_scale
 482             This is number of real pixels that equals to 1 HTML pixel.
 483     */
 484     void SetWidthFloat(const wxHtmlTag& tag,
 485                        double pixel_scale = 1.0);
 486 };
 487
 488
 489
 490 /**
 491     @class wxHtmlLinkInfo
 492
 493     This class stores all necessary information about hypertext links
 494     (as represented by \<A\> tag in HTML documents).
 495     In current implementation it stores URL and target frame name.
 496
 497     @note Frames are not currently supported by wxHTML!
 498
 499     @library{wxhtml}
 500     @category{html}
 501 */
 502 class wxHtmlLinkInfo : public wxObject
 503 {
 504 public:
 505     /**
 506         Default ctor.
 507     */
 508     wxHtmlLinkInfo();
 509
 510     /**
 511         Construct hypertext link from HREF (aka URL) and TARGET (name of target frame).
 512     */
 513     wxHtmlLinkInfo(const wxString& href,
 514                    const wxString& target = wxEmptyString);
 515
 516     /**
 517         Return pointer to event that generated OnLinkClicked() event.
 518         Valid only within wxHtmlWindow::OnLinkClicked, @NULL otherwise.
 519     */
 520     const wxMouseEvent* GetEvent() const;
 521
 522     /**
 523         Return @e HREF value of the \<A\> tag.
 524     */
 525     wxString GetHref() const;
 526
 527     /**
 528         Return pointer to the cell that was clicked.
 529         Valid only within wxHtmlWindow::OnLinkClicked, @NULL otherwise.
 530     */
 531     const wxHtmlCell* GetHtmlCell() const;
 532
 533     /**
 534         Return @e TARGET value of the \<A\> tag (this value is used to specify
 535         in which frame should be the page pointed by @ref GetHref() Href opened).
 536     */
 537     wxString GetTarget() const;
 538 };
 539