1 /////////////////////////////////////////////////////////////////////////////
2 // Name: html/htmlcell.h
3 // Purpose: interface of wxHtml*Cell
4 // Author: wxWidgets team
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
10 @class wxHtmlRenderingStyle
12 wxHtmlSelection is data holder with information about text selection.
13 Selection is defined by two positions (beginning and end of the selection)
14 and two leaf(!) cells at these positions.
24 // this version is used for the user selection defined with the mouse
25 void Set(const wxPoint
& fromPos
, const wxHtmlCell
*fromCell
,
26 const wxPoint
& toPos
, const wxHtmlCell
*toCell
);
27 void Set(const wxHtmlCell
*fromCell
, const wxHtmlCell
*toCell
);
29 const wxHtmlCell
*GetFromCell() const;
30 const wxHtmlCell
*GetToCell() const;
32 // these values are in absolute coordinates:
33 const wxPoint
& GetFromPos() const;
34 const wxPoint
& GetToPos() const;
36 // these are From/ToCell's private data
37 void ClearFromToCharacterPos();
38 bool AreFromToCharacterPosSet() const;
40 void SetFromCharacterPos (wxCoord pos
);
41 void SetToCharacterPos (wxCoord pos
);
42 wxCoord
GetFromCharacterPos () const;
43 wxCoord
GetToCharacterPos () const;
50 enum wxHtmlSelectionState
52 wxHTML_SEL_OUT
, // currently rendered cell is outside the selection
53 wxHTML_SEL_IN
, // ... is inside selection
54 wxHTML_SEL_CHANGING
// ... is the cell on which selection state changes
59 @class wxHtmlRenderingState
61 Selection state is passed to wxHtmlCell::Draw so that it can render itself
62 differently e.g. when inside text selection or outside it.
67 class wxHtmlRenderingState
70 wxHtmlRenderingState();
72 void SetSelectionState(wxHtmlSelectionState s
);
73 wxHtmlSelectionState
GetSelectionState() const;
75 void SetFgColour(const wxColour
& c
);
76 const wxColour
& GetFgColour() const;
77 void SetBgColour(const wxColour
& c
);
78 const wxColour
& GetBgColour() const;
79 void SetBgMode(int m
);
80 int GetBgMode() const;
86 @class wxHtmlRenderingStyle
88 Allows HTML rendering customizations.
89 This class is used when rendering wxHtmlCells as a callback.
94 @see wxHtmlRenderingInfo
96 class wxHtmlRenderingStyle
100 Returns the colour to use for the selected text.
102 virtual wxColour
GetSelectedTextColour(const wxColour
& clr
) = 0;
105 Returns the colour to use for the selected text's background.
107 virtual wxColour
GetSelectedTextBgColour(const wxColour
& clr
) = 0;
112 @class wxHtmlRenderingInfo
114 This class contains information given to cells when drawing them.
115 Contains rendering state, selection information and rendering style object
116 that can be used to customize the output.
121 @see @ref overview_html_cells, wxHtmlCell
123 class wxHtmlRenderingInfo
129 wxHtmlRenderingInfo();
135 void SetSelection(wxHtmlSelection
*s
);
136 wxHtmlSelection
*GetSelection() const;
138 void SetStyle(wxHtmlRenderingStyle
*style
);
139 wxHtmlRenderingStyle
& GetStyle();
141 wxHtmlRenderingState
& GetState();
147 // Flags for wxHtmlCell::FindCellByPos
150 wxHTML_FIND_EXACT
= 1,
151 wxHTML_FIND_NEAREST_BEFORE
= 2,
152 wxHTML_FIND_NEAREST_AFTER
= 4
156 // Superscript/subscript/normal script mode of a cell
157 enum wxHtmlScriptMode
159 wxHTML_SCRIPT_NORMAL
,
168 Internal data structure. It represents fragments of parsed HTML page, the
169 so-called @b cell - a word, picture, table, horizontal line and so on.
170 It is used by wxHtmlWindow and wxHtmlWinParser to represent HTML page in memory.
172 You can divide cells into two groups : @e visible cells with non-zero width and
173 height and @e helper cells (usually with zero width and height) that perform
174 special actions such as color or font change.
179 @see @ref overview_html_cells, wxHtmlContainerCell
181 class wxHtmlCell
: public wxObject
190 This method is used to adjust pagebreak position.
191 The first parameter is a variable that contains the y-coordinate of the page break
192 (= horizontal line that should not be crossed by words, images etc.).
193 If this cell cannot be divided into two pieces (each one on another page)
194 then it either moves the pagebreak a few pixels up, if possible, or, if
195 the cell cannot fit on the page at all, then the cell is forced to
196 split unconditionally.
198 Returns @true if pagebreak was modified, @false otherwise.
201 position in pixel of the pagebreak.
203 @param known_pagebreaks
204 the list of the previous pagebreaks
207 the height in pixel of the page drawable area
211 while (container->AdjustPagebreak(&p, kp, ph)) {}
215 virtual bool AdjustPagebreak(int* pagebreak
,
216 const wxArrayInt
& known_pagebreaks
,
217 int pageHeight
) const;
223 Device context to which the cell is to be drawn.
225 Coordinates of parent's upper left corner (origin). You must
226 add this to m_PosX,m_PosY when passing coordinates to dc's methods
229 dc->DrawText("hello", x + m_PosX, y + m_PosY)
232 y-coord of the first line visible in window.
233 This is used to optimize rendering speed.
235 y-coord of the last line visible in window.
236 This is used to optimize rendering speed.
238 Additional information for the rendering of the cell.
240 virtual void Draw(wxDC
& dc
, int x
, int y
, int view_y1
, int view_y2
, wxHtmlRenderingInfo
& info
);
243 This method is called instead of Draw() when the cell is certainly out of
244 the screen (and thus invisible). This is not nonsense - some tags (like
245 wxHtmlColourCell or font setter) must be drawn even if they are invisible!
248 Device context to which the cell is to be drawn.
250 Coordinates of parent's upper left corner. You must
251 add this to m_PosX,m_PosY when passing coordinates to dc's methods
254 dc->DrawText("hello", x + m_PosX, y + m_PosY)
257 Additional information for the rendering of the cell.
259 virtual void DrawInvisible(wxDC
& dc
, int x
, int y
, wxHtmlRenderingInfo
& info
);
262 Returns pointer to itself if this cell matches condition (or if any of the
263 cells following in the list matches), @NULL otherwise.
264 (In other words if you call top-level container's Find() it will
265 return pointer to the first cell that matches the condition)
267 It is recommended way how to obtain pointer to particular cell or
268 to cell of some type (e.g. wxHtmlAnchorCell reacts on wxHTML_COND_ISANCHOR
272 Unique integer identifier of condition
276 virtual const wxHtmlCell
* Find(int condition
, const void* param
) const;
279 Returns descent value of the cell (m_Descent member).
281 @image html htmlcell_descent.png
283 int GetDescent() const;
286 Returns pointer to the first cell in the list.
287 You can then use child's GetNext() method to obtain pointer to the next
290 @note This shouldn't be used by the end user. If you need some way of
291 finding particular cell in the list, try Find() method instead.
293 virtual wxHtmlCell
* GetFirstChild() const;
296 Returns height of the cell (m_Height member).
298 int GetHeight() const;
301 Returns unique cell identifier if there is any, the empty string otherwise.
303 const wxString
& GetId() const;
306 Returns hypertext link if associated with this cell or @NULL otherwise.
307 See wxHtmlLinkInfo. (Note: this makes sense only for visible tags).
310 Coordinates of position where the user pressed mouse button.
311 These coordinates are used e.g. by COLORMAP. Values are relative to the
312 upper left corner of THIS cell (i.e. from 0 to m_Width or m_Height)
314 virtual wxHtmlLinkInfo
* GetLink(int x
= 0, int y
= 0) const;
317 Returns cursor to show when mouse pointer is over the cell.
320 interface to the parent HTML window
322 @see GetMouseCursorAt()
324 virtual wxCursor
GetMouseCursor(wxHtmlWindowInterface
* window
) const;
327 Returns cursor to show when mouse pointer is over the specified point.
329 This function should be overridden instead of GetMouseCursorAt() if
330 the cursor should depend on the exact position of the mouse in the
334 interface to the parent HTML window
336 Position to show cursor.
340 virtual wxCursor
GetMouseCursorAt(wxHtmlWindowInterface
* window
,
341 const wxPoint
& rePos
) const;
344 Returns pointer to the next cell in list (see htmlcell.h if you're
345 interested in details).
347 wxHtmlCell
* GetNext() const;
350 Returns pointer to parent container.
352 wxHtmlContainerCell
* GetParent() const;
355 Returns X position within parent (the value is relative to parent's
356 upper left corner). The returned value is meaningful only if
357 parent's Layout() was called before!
362 Returns Y position within parent (the value is relative to parent's
363 upper left corner). The returned value is meaningful only if
364 parent's Layout() was called before!
369 Returns width of the cell (m_Width member).
371 int GetWidth() const;
376 This method performs two actions:
377 -# adjusts the cell's width according to the fact that maximal possible
378 width is @e w (this has sense when working with horizontal lines, tables etc.)
379 -# prepares layout (=fill-in m_PosX, m_PosY (and sometimes m_Height) members)
380 based on actual width @e w
382 It must be called before displaying cells structure because m_PosX and
383 m_PosY are undefined (or invalid) before calling Layout().
385 virtual void Layout(int w
);
388 This function is simple event handler.
389 Each time the user clicks mouse button over a cell within wxHtmlWindow
390 this method of that cell is called.
391 Default behaviour is to call wxHtmlWindow::LoadPage.
394 interface to the parent HTML window
396 coordinates of mouse click (this is relative to cell's origin
398 mouse event that triggered the call
400 @return @true if a link was clicked, @false otherwise.
402 @since 2.7.0 (before OnMouseClick() method served a similar purpose).
405 If you need more "advanced" event handling you should use wxHtmlBinderCell instead.
407 virtual bool ProcessMouseClick(wxHtmlWindowInterface
* window
,
409 const wxMouseEvent
& event
);
412 Sets unique cell identifier. Default value is no identifier, i.e. empty string.
414 void SetId(const wxString
& id
);
417 Sets the hypertext link associated with this cell.
418 (Default value is wxHtmlLinkInfo("", "") (no link))
420 void SetLink(const wxHtmlLinkInfo
& link
);
423 Sets the next cell in the list. This shouldn't be called by user - it is
424 to be used only by wxHtmlContainerCell::InsertCell.
426 void SetNext(wxHtmlCell
* cell
);
429 Sets parent container of this cell.
430 This is called from wxHtmlContainerCell::InsertCell.
432 void SetParent(wxHtmlContainerCell
* p
);
435 Sets the cell's position within parent container.
437 virtual void SetPos(int x
, int y
);
443 @class wxHtmlContainerCell
445 The wxHtmlContainerCell class is an implementation of a cell that may
446 contain more cells in it. It is heavily used in the wxHTML layout algorithm.
451 @see @ref overview_html_cells
453 class wxHtmlContainerCell
: public wxHtmlCell
457 Constructor. @a parent is pointer to parent container or @NULL.
459 wxHtmlContainerCell(wxHtmlContainerCell
* parent
);
462 Returns container's horizontal alignment.
464 int GetAlignHor() const;
467 Returns container's vertical alignment.
469 int GetAlignVer() const;
472 Returns the background colour of the container or @c wxNullColour if no
473 background colour is set.
475 wxColour
GetBackgroundColour();
478 Returns the indentation. @a ind is one of the @b wxHTML_INDENT_* constants.
480 @note You must call GetIndentUnits() with same @a ind parameter in order
481 to correctly interpret the returned integer value.
482 It is NOT always in pixels!
484 int GetIndent(int ind
) const;
487 Returns the units of indentation for @a ind where @a ind is one
488 of the @b wxHTML_INDENT_* constants.
490 int GetIndentUnits(int ind
) const;
493 Inserts a new cell into the container.
495 void InsertCell(wxHtmlCell
* cell
);
498 Sets the container's alignment (both horizontal and vertical) according to
499 the values stored in @e tag. (Tags @c ALIGN parameter is extracted.)
500 In fact it is only a front-end to SetAlignHor() and SetAlignVer().
502 void SetAlign(const wxHtmlTag
& tag
);
505 Sets the container's @e horizontal alignment.
506 During wxHtmlCell::Layout each line is aligned according to @a al value.
509 new horizontal alignment. May be one of these values:
510 - wxHTML_ALIGN_LEFT: lines are left-aligned (default)
511 - wxHTML_ALIGN_JUSTIFY: lines are justified
512 - wxHTML_ALIGN_CENTER: lines are centered
513 - wxHTML_ALIGN_RIGHT: lines are right-aligned
515 void SetAlignHor(int al
);
518 Sets the container's @e vertical alignment. This is per-line alignment!
521 new vertical alignment. May be one of these values:
522 - wxHTML_ALIGN_BOTTOM: cells are over the line (default)
523 - wxHTML_ALIGN_CENTER: cells are centered on line
524 - wxHTML_ALIGN_TOP: cells are under the line
526 @image html htmlcontcell_alignv.png
528 void SetAlignVer(int al
);
531 Sets the background colour for this container.
533 void SetBackgroundColour(const wxColour
& clr
);
536 Sets the border (frame) colours. A border is a rectangle around the container.
539 Colour of top and left lines
541 Colour of bottom and right lines
543 Size of the border in pixels
545 void SetBorder(const wxColour
& clr1
, const wxColour
& clr2
, int border
= 1);
548 Sets the indentation (free space between borders of container and subcells).
550 @image html htmlcontcell_indent.png
555 Determines which of the four borders we're setting. It is OR
556 combination of following constants:
557 - wxHTML_INDENT_TOP: top border
558 - wxHTML_INDENT_BOTTOM: bottom
559 - wxHTML_INDENT_LEFT: left
560 - wxHTML_INDENT_RIGHT: right
561 - wxHTML_INDENT_HORIZONTAL: left and right
562 - wxHTML_INDENT_VERTICAL: top and bottom
563 - wxHTML_INDENT_ALL: all 4 borders
565 Units of i. This parameter affects interpretation of value.
566 - wxHTML_UNITS_PIXELS: @a i is number of pixels
567 - wxHTML_UNITS_PERCENT: @a i is interpreted as percents of width
570 void SetIndent(int i
, int what
, int units
= wxHTML_UNITS_PIXELS
);
573 Sets minimal height of the container.
574 When container's wxHtmlCell::Layout is called, m_Height is set depending
575 on layout of subcells to the height of area covered by layed-out subcells.
576 Calling this method guarantees you that the height of container is never
577 smaller than @a h - even if the subcells cover much smaller area.
582 If height of the container is lower than the minimum height, empty space
583 must be inserted somewhere in order to ensure minimal height.
584 This parameter is one of @c wxHTML_ALIGN_TOP, @c wxHTML_ALIGN_BOTTOM,
585 @c wxHTML_ALIGN_CENTER. It refers to the contents, not to the
588 void SetMinHeight(int h
, int align
= wxHTML_ALIGN_TOP
);
591 Sets floating width adjustment.
593 The normal behaviour of container is that its width is the same as the width of
594 parent container (and thus you can have only one sub-container per line).
595 You can change this by setting the floating width adjustment.
598 Width of the container. If the value is negative it means
599 complement to full width of parent container.
600 E.g. @code SetWidthFloat(-50, wxHTML_UNITS_PIXELS) @endcode sets the
601 width of container to parent's width minus 50 pixels. This is useful when
602 creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50).
604 Units of w This parameter affects the interpretation of value.
605 - wxHTML_UNITS_PIXELS: @a w is number of pixels
606 - wxHTML_UNITS_PERCENT: @a w is interpreted as percents of width
609 void SetWidthFloat(int w
, int units
);
612 Sets floating width adjustment.
614 The normal behaviour of container is that its width is the same as the width of
615 parent container (and thus you can have only one sub-container per line).
616 You can change this by setting the floating width adjustment.
619 In the second version of method, @a w and @a units info is extracted
620 from tag's WIDTH parameter.
622 This is number of real pixels that equals to 1 HTML pixel.
624 void SetWidthFloat(const wxHtmlTag
& tag
,
625 double pixel_scale
= 1.0);
631 @class wxHtmlLinkInfo
633 This class stores all necessary information about hypertext links
634 (as represented by \<A\> tag in HTML documents).
635 In current implementation it stores URL and target frame name.
637 @note Frames are not currently supported by wxHTML!
642 class wxHtmlLinkInfo
: public wxObject
651 Construct hypertext link from HREF (aka URL) and TARGET (name of target frame).
653 wxHtmlLinkInfo(const wxString
& href
,
654 const wxString
& target
= wxEmptyString
);
657 Return pointer to event that generated OnLinkClicked() event.
658 Valid only within wxHtmlWindow::OnLinkClicked, @NULL otherwise.
660 const wxMouseEvent
* GetEvent() const;
663 Return @e HREF value of the \<A\> tag.
665 wxString
GetHref() const;
668 Return pointer to the cell that was clicked.
669 Valid only within wxHtmlWindow::OnLinkClicked, @NULL otherwise.
671 const wxHtmlCell
* GetHtmlCell() const;
674 Return @e TARGET value of the \<A\> tag (this value is used to specify
675 in which frame should be the page pointed by @ref GetHref() Href opened).
677 wxString
GetTarget() const;
681 @class wxHtmlColourCell
683 This cell changes the colour of either the background or the foreground.
688 class wxHtmlColourCell
: public wxHtmlCell
697 Can be one of following:
698 - wxHTML_CLR_FOREGROUND: change color of text
699 - wxHTML_CLR_BACKGROUND: change background color
701 wxHtmlColourCell(const wxColour
& clr
, int flags
= wxHTML_CLR_FOREGROUND
);
707 @class wxHtmlWidgetCell
709 wxHtmlWidgetCell is a class that provides a connection between HTML cells and
710 widgets (an object derived from wxWindow).
711 You can use it to display things like forms, input boxes etc. in an HTML window.
713 wxHtmlWidgetCell takes care of resizing and moving window.
718 class wxHtmlWidgetCell
: public wxHtmlCell
725 Connected window. It is parent window @b must be the wxHtmlWindow object
726 within which it is displayed!
728 Floating width. If non-zero width of wnd window is adjusted so that it is
729 always w percents of parent container's width. (For example w = 100 means
730 that the window will always have same width as parent container).
732 wxHtmlWidgetCell(wxWindow
* wnd
, int w
= 0);
738 @class wxHtmlWordCell
740 This html cell represents a single word or text fragment in the document stream.
745 class wxHtmlWordCell
: public wxHtmlCell
748 wxHtmlWordCell(const wxString
& word
, const wxDC
& dc
);
753 @class wxHtmlWordWithTabsCell
755 wxHtmlWordCell is a specialization for storing text fragments with
756 embedded tab characters.
761 class wxHtmlWordWithTabsCell
: public wxHtmlWordCell
764 wxHtmlWordWithTabsCell(const wxString
& word
,
765 const wxString
& wordOrig
,
772 @class wxHtmlFontCell
774 This cell represents a font change in the document stream.
779 class wxHtmlFontCell
: public wxHtmlCell
782 wxHtmlFontCell(wxFont
*font
);