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