1 /////////////////////////////////////////////////////////////////////////////
2 // Name: html/htmlcell.h
3 // Purpose: interface of wxHtml*Cell
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
11 @class wxHtmlRenderingStyle
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.
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
);
30 const wxHtmlCell
*GetFromCell() const;
31 const wxHtmlCell
*GetToCell() const;
33 // these values are in absolute coordinates:
34 const wxPoint
& GetFromPos() const;
35 const wxPoint
& GetToPos() const;
37 // these are From/ToCell's private data
38 void ClearFromToCharacterPos();
39 bool AreFromToCharacterPosSet() const;
41 void SetFromCharacterPos (wxCoord pos
);
42 void SetToCharacterPos (wxCoord pos
);
43 wxCoord
GetFromCharacterPos () const;
44 wxCoord
GetToCharacterPos () const;
51 enum wxHtmlSelectionState
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
60 @class wxHtmlRenderingState
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.
68 class wxHtmlRenderingState
71 wxHtmlRenderingState();
73 void SetSelectionState(wxHtmlSelectionState s
);
74 wxHtmlSelectionState
GetSelectionState() const;
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;
87 @class wxHtmlRenderingStyle
89 Allows HTML rendering customizations.
90 This class is used when rendering wxHtmlCells as a callback.
95 @see wxHtmlRenderingInfo
97 class wxHtmlRenderingStyle
101 Returns the colour to use for the selected text.
103 virtual wxColour
GetSelectedTextColour(const wxColour
& clr
) = 0;
106 Returns the colour to use for the selected text's background.
108 virtual wxColour
GetSelectedTextBgColour(const wxColour
& clr
) = 0;
113 @class wxHtmlRenderingInfo
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.
122 @see @ref overview_html_cells, wxHtmlCell
124 class wxHtmlRenderingInfo
130 wxHtmlRenderingInfo();
136 void SetSelection(wxHtmlSelection
*s
);
137 wxHtmlSelection
*GetSelection() const;
139 void SetStyle(wxHtmlRenderingStyle
*style
);
140 wxHtmlRenderingStyle
& GetStyle();
142 wxHtmlRenderingState
& GetState();
148 // Flags for wxHtmlCell::FindCellByPos
151 wxHTML_FIND_EXACT
= 1,
152 wxHTML_FIND_NEAREST_BEFORE
= 2,
153 wxHTML_FIND_NEAREST_AFTER
= 4
157 // Superscript/subscript/normal script mode of a cell
158 enum wxHtmlScriptMode
160 wxHTML_SCRIPT_NORMAL
,
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.
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.
180 @see @ref overview_html_cells, wxHtmlContainerCell
182 class wxHtmlCell
: public wxObject
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.
199 Returns @true if pagebreak was modified, @false otherwise.
202 position in pixel of the pagebreak.
204 @param known_pagebreaks
205 the list of the previous pagebreaks
208 the height in pixel of the page drawable area
212 while (container->AdjustPagebreak(&p, kp, ph)) {}
216 virtual bool AdjustPagebreak(int* pagebreak
,
217 const wxArrayInt
& known_pagebreaks
,
218 int pageHeight
) const;
224 Device context to which the cell is to be drawn.
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
230 dc->DrawText("hello", x + m_PosX, y + m_PosY)
233 y-coord of the first line visible in window.
234 This is used to optimize rendering speed.
236 y-coord of the last line visible in window.
237 This is used to optimize rendering speed.
239 Additional information for the rendering of the cell.
241 virtual void Draw(wxDC
& dc
, int x
, int y
, int view_y1
, int view_y2
, wxHtmlRenderingInfo
& info
);
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!
249 Device context to which the cell is to be drawn.
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
255 dc->DrawText("hello", x + m_PosX, y + m_PosY)
258 Additional information for the rendering of the cell.
260 virtual void DrawInvisible(wxDC
& dc
, int x
, int y
, wxHtmlRenderingInfo
& info
);
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)
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
273 Unique integer identifier of condition
277 virtual const wxHtmlCell
* Find(int condition
, const void* param
) const;
280 Returns descent value of the cell (m_Descent member).
282 @image html htmlcell_descent.png
284 int GetDescent() const;
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
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.
294 virtual wxHtmlCell
* GetFirstChild() const;
297 Returns height of the cell (m_Height member).
299 int GetHeight() const;
302 Returns unique cell identifier if there is any, the empty string otherwise.
304 const wxString
& GetId() const;
307 Returns hypertext link if associated with this cell or @NULL otherwise.
308 See wxHtmlLinkInfo. (Note: this makes sense only for visible tags).
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)
315 virtual wxHtmlLinkInfo
* GetLink(int x
= 0, int y
= 0) const;
318 Returns cursor to show when mouse pointer is over the cell.
321 interface to the parent HTML window
323 virtual wxCursor
GetMouseCursor(wxHtmlWindowInterface
* window
) const;
326 Returns pointer to the next cell in list (see htmlcell.h if you're
327 interested in details).
329 wxHtmlCell
* GetNext() const;
332 Returns pointer to parent container.
334 wxHtmlContainerCell
* GetParent() const;
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!
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!
351 Returns width of the cell (m_Width member).
353 int GetWidth() const;
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
364 It must be called before displaying cells structure because m_PosX and
365 m_PosY are undefined (or invalid) before calling Layout().
367 virtual void Layout(int w
);
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.
376 interface to the parent HTML window
378 coordinates of mouse click (this is relative to cell's origin
380 mouse event that triggered the call
382 @return @true if a link was clicked, @false otherwise.
384 @since 2.7.0 (before OnMouseClick() method served a similar purpose).
387 If you need more "advanced" event handling you should use wxHtmlBinderCell instead.
389 virtual bool ProcessMouseClick(wxHtmlWindowInterface
* window
,
391 const wxMouseEvent
& event
);
394 Sets unique cell identifier. Default value is no identifier, i.e. empty string.
396 void SetId(const wxString
& id
);
399 Sets the hypertext link associated with this cell.
400 (Default value is wxHtmlLinkInfo("", "") (no link))
402 void SetLink(const wxHtmlLinkInfo
& link
);
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.
408 void SetNext(wxHtmlCell
* cell
);
411 Sets parent container of this cell.
412 This is called from wxHtmlContainerCell::InsertCell.
414 void SetParent(wxHtmlContainerCell
* p
);
417 Sets the cell's position within parent container.
419 virtual void SetPos(int x
, int y
);
425 @class wxHtmlContainerCell
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.
433 @see @ref overview_html_cells
435 class wxHtmlContainerCell
: public wxHtmlCell
439 Constructor. @a parent is pointer to parent container or @NULL.
441 wxHtmlContainerCell(wxHtmlContainerCell
* parent
);
444 Returns container's horizontal alignment.
446 int GetAlignHor() const;
449 Returns container's vertical alignment.
451 int GetAlignVer() const;
454 Returns the background colour of the container or @c wxNullColour if no
455 background colour is set.
457 wxColour
GetBackgroundColour();
460 Returns the indentation. @a ind is one of the @b wxHTML_INDENT_* constants.
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!
466 int GetIndent(int ind
) const;
469 Returns the units of indentation for @a ind where @a ind is one
470 of the @b wxHTML_INDENT_* constants.
472 int GetIndentUnits(int ind
) const;
475 Inserts a new cell into the container.
477 void InsertCell(wxHtmlCell
* cell
);
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().
484 void SetAlign(const wxHtmlTag
& tag
);
487 Sets the container's @e horizontal alignment.
488 During wxHtmlCell::Layout each line is aligned according to @a al value.
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
497 void SetAlignHor(int al
);
500 Sets the container's @e vertical alignment. This is per-line alignment!
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
508 @image html htmlcontcell_alignv.png
510 void SetAlignVer(int al
);
513 Sets the background colour for this container.
515 void SetBackgroundColour(const wxColour
& clr
);
518 Sets the border (frame) colours. A border is a rectangle around the container.
521 Colour of top and left lines
523 Colour of bottom and right lines
525 Size of the border in pixels
527 void SetBorder(const wxColour
& clr1
, const wxColour
& clr2
, int border
= 1);
530 Sets the indentation (free space between borders of container and subcells).
532 @image html htmlcontcell_indent.png
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
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
552 void SetIndent(int i
, int what
, int units
= wxHTML_UNITS_PIXELS
);
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.
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
570 void SetMinHeight(int h
, int align
= wxHTML_ALIGN_TOP
);
573 Sets floating width adjustment.
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.
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).
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
591 void SetWidthFloat(int w
, int units
);
594 Sets floating width adjustment.
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.
601 In the second version of method, @a w and @a units info is extracted
602 from tag's WIDTH parameter.
604 This is number of real pixels that equals to 1 HTML pixel.
606 void SetWidthFloat(const wxHtmlTag
& tag
,
607 double pixel_scale
= 1.0);
613 @class wxHtmlLinkInfo
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.
619 @note Frames are not currently supported by wxHTML!
624 class wxHtmlLinkInfo
: public wxObject
633 Construct hypertext link from HREF (aka URL) and TARGET (name of target frame).
635 wxHtmlLinkInfo(const wxString
& href
,
636 const wxString
& target
= wxEmptyString
);
639 Return pointer to event that generated OnLinkClicked() event.
640 Valid only within wxHtmlWindow::OnLinkClicked, @NULL otherwise.
642 const wxMouseEvent
* GetEvent() const;
645 Return @e HREF value of the \<A\> tag.
647 wxString
GetHref() const;
650 Return pointer to the cell that was clicked.
651 Valid only within wxHtmlWindow::OnLinkClicked, @NULL otherwise.
653 const wxHtmlCell
* GetHtmlCell() const;
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).
659 wxString
GetTarget() const;
663 @class wxHtmlColourCell
665 This cell changes the colour of either the background or the foreground.
670 class wxHtmlColourCell
: public wxHtmlCell
679 Can be one of following:
680 - wxHTML_CLR_FOREGROUND: change color of text
681 - wxHTML_CLR_BACKGROUND: change background color
683 wxHtmlColourCell(const wxColour
& clr
, int flags
= wxHTML_CLR_FOREGROUND
);
689 @class wxHtmlWidgetCell
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.
695 wxHtmlWidgetCell takes care of resizing and moving window.
700 class wxHtmlWidgetCell
: public wxHtmlCell
707 Connected window. It is parent window @b must be the wxHtmlWindow object
708 within which it is displayed!
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).
714 wxHtmlWidgetCell(wxWindow
* wnd
, int w
= 0);
720 @class wxHtmlWordCell
722 This html cell represents a single word or text fragment in the document stream.
727 class wxHtmlWordCell
: public wxHtmlCell
730 wxHtmlWordCell(const wxString
& word
, const wxDC
& dc
);
735 @class wxHtmlWordWithTabsCell
737 wxHtmlWordCell is a specialization for storing text fragments with
738 embedded tab characters.
743 class wxHtmlWordWithTabsCell
: public wxHtmlWordCell
746 wxHtmlWordWithTabsCell(const wxString
& word
,
747 const wxString
& wordOrig
,
754 @class wxHtmlFontCell
756 This cell represents a font change in the document stream.
761 class wxHtmlFontCell
: public wxHtmlCell
764 wxHtmlFontCell(wxFont
*font
);