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