interface/wx/html/htmlcell.h

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