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