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