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