]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/html/htmlcell.h
Fix interface definition of GetMouseCursorAt
[wxWidgets.git] / 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 @see GetMouseCursorAt()
324 */
325 virtual wxCursor GetMouseCursor(wxHtmlWindowInterface* window) const;
326
327 /**
328 Returns cursor to show when mouse pointer is over the specified point.
329
330 This function should be overridden instead of GetMouseCursorAt() if
331 the cursor should depend on the exact position of the mouse in the
332 window.
333
334 @param window
335 interface to the parent HTML window
336
337 @since 3.0
338 */
339 virtual wxCursor GetMouseCursorAt(wxHtmlWindowInterface* window,
340 const wxPoint& rePos) const;
341
342 /**
343 Returns pointer to the next cell in list (see htmlcell.h if you're
344 interested in details).
345 */
346 wxHtmlCell* GetNext() const;
347
348 /**
349 Returns pointer to parent container.
350 */
351 wxHtmlContainerCell* GetParent() const;
352
353 /**
354 Returns X position within parent (the value is relative to parent's
355 upper left corner). The returned value is meaningful only if
356 parent's Layout() was called before!
357 */
358 int GetPosX() const;
359
360 /**
361 Returns Y position within parent (the value is relative to parent's
362 upper left corner). The returned value is meaningful only if
363 parent's Layout() was called before!
364 */
365 int GetPosY() const;
366
367 /**
368 Returns width of the cell (m_Width member).
369 */
370 int GetWidth() const;
371
372 /**
373 Layouts the cell.
374
375 This method performs two actions:
376 -# adjusts the cell's width according to the fact that maximal possible
377 width is @e w (this has sense when working with horizontal lines, tables etc.)
378 -# prepares layout (=fill-in m_PosX, m_PosY (and sometimes m_Height) members)
379 based on actual width @e w
380
381 It must be called before displaying cells structure because m_PosX and
382 m_PosY are undefined (or invalid) before calling Layout().
383 */
384 virtual void Layout(int w);
385
386 /**
387 This function is simple event handler.
388 Each time the user clicks mouse button over a cell within wxHtmlWindow
389 this method of that cell is called.
390 Default behaviour is to call wxHtmlWindow::LoadPage.
391
392 @param window
393 interface to the parent HTML window
394 @param pos
395 coordinates of mouse click (this is relative to cell's origin
396 @param event
397 mouse event that triggered the call
398
399 @return @true if a link was clicked, @false otherwise.
400
401 @since 2.7.0 (before OnMouseClick() method served a similar purpose).
402
403 @note
404 If you need more "advanced" event handling you should use wxHtmlBinderCell instead.
405 */
406 virtual bool ProcessMouseClick(wxHtmlWindowInterface* window,
407 const wxPoint& pos,
408 const wxMouseEvent& event);
409
410 /**
411 Sets unique cell identifier. Default value is no identifier, i.e. empty string.
412 */
413 void SetId(const wxString& id);
414
415 /**
416 Sets the hypertext link associated with this cell.
417 (Default value is wxHtmlLinkInfo("", "") (no link))
418 */
419 void SetLink(const wxHtmlLinkInfo& link);
420
421 /**
422 Sets the next cell in the list. This shouldn't be called by user - it is
423 to be used only by wxHtmlContainerCell::InsertCell.
424 */
425 void SetNext(wxHtmlCell* cell);
426
427 /**
428 Sets parent container of this cell.
429 This is called from wxHtmlContainerCell::InsertCell.
430 */
431 void SetParent(wxHtmlContainerCell* p);
432
433 /**
434 Sets the cell's position within parent container.
435 */
436 virtual void SetPos(int x, int y);
437 };
438
439
440
441 /**
442 @class wxHtmlContainerCell
443
444 The wxHtmlContainerCell class is an implementation of a cell that may
445 contain more cells in it. It is heavily used in the wxHTML layout algorithm.
446
447 @library{wxhtml}
448 @category{html}
449
450 @see @ref overview_html_cells
451 */
452 class wxHtmlContainerCell : public wxHtmlCell
453 {
454 public:
455 /**
456 Constructor. @a parent is pointer to parent container or @NULL.
457 */
458 wxHtmlContainerCell(wxHtmlContainerCell* parent);
459
460 /**
461 Returns container's horizontal alignment.
462 */
463 int GetAlignHor() const;
464
465 /**
466 Returns container's vertical alignment.
467 */
468 int GetAlignVer() const;
469
470 /**
471 Returns the background colour of the container or @c wxNullColour if no
472 background colour is set.
473 */
474 wxColour GetBackgroundColour();
475
476 /**
477 Returns the indentation. @a ind is one of the @b wxHTML_INDENT_* constants.
478
479 @note You must call GetIndentUnits() with same @a ind parameter in order
480 to correctly interpret the returned integer value.
481 It is NOT always in pixels!
482 */
483 int GetIndent(int ind) const;
484
485 /**
486 Returns the units of indentation for @a ind where @a ind is one
487 of the @b wxHTML_INDENT_* constants.
488 */
489 int GetIndentUnits(int ind) const;
490
491 /**
492 Inserts a new cell into the container.
493 */
494 void InsertCell(wxHtmlCell* cell);
495
496 /**
497 Sets the container's alignment (both horizontal and vertical) according to
498 the values stored in @e tag. (Tags @c ALIGN parameter is extracted.)
499 In fact it is only a front-end to SetAlignHor() and SetAlignVer().
500 */
501 void SetAlign(const wxHtmlTag& tag);
502
503 /**
504 Sets the container's @e horizontal alignment.
505 During wxHtmlCell::Layout each line is aligned according to @a al value.
506
507 @param al
508 new horizontal alignment. May be one of these values:
509 - wxHTML_ALIGN_LEFT: lines are left-aligned (default)
510 - wxHTML_ALIGN_JUSTIFY: lines are justified
511 - wxHTML_ALIGN_CENTER: lines are centered
512 - wxHTML_ALIGN_RIGHT: lines are right-aligned
513 */
514 void SetAlignHor(int al);
515
516 /**
517 Sets the container's @e vertical alignment. This is per-line alignment!
518
519 @param al
520 new vertical alignment. May be one of these values:
521 - wxHTML_ALIGN_BOTTOM: cells are over the line (default)
522 - wxHTML_ALIGN_CENTER: cells are centered on line
523 - wxHTML_ALIGN_TOP: cells are under the line
524
525 @image html htmlcontcell_alignv.png
526 */
527 void SetAlignVer(int al);
528
529 /**
530 Sets the background colour for this container.
531 */
532 void SetBackgroundColour(const wxColour& clr);
533
534 /**
535 Sets the border (frame) colours. A border is a rectangle around the container.
536
537 @param clr1
538 Colour of top and left lines
539 @param clr2
540 Colour of bottom and right lines
541 @param border
542 Size of the border in pixels
543 */
544 void SetBorder(const wxColour& clr1, const wxColour& clr2, int border = 1);
545
546 /**
547 Sets the indentation (free space between borders of container and subcells).
548
549 @image html htmlcontcell_indent.png
550
551 @param i
552 Indentation value.
553 @param what
554 Determines which of the four borders we're setting. It is OR
555 combination of following constants:
556 - wxHTML_INDENT_TOP: top border
557 - wxHTML_INDENT_BOTTOM: bottom
558 - wxHTML_INDENT_LEFT: left
559 - wxHTML_INDENT_RIGHT: right
560 - wxHTML_INDENT_HORIZONTAL: left and right
561 - wxHTML_INDENT_VERTICAL: top and bottom
562 - wxHTML_INDENT_ALL: all 4 borders
563 @param units
564 Units of i. This parameter affects interpretation of value.
565 - wxHTML_UNITS_PIXELS: @a i is number of pixels
566 - wxHTML_UNITS_PERCENT: @a i is interpreted as percents of width
567 of parent container
568 */
569 void SetIndent(int i, int what, int units = wxHTML_UNITS_PIXELS);
570
571 /**
572 Sets minimal height of the container.
573 When container's wxHtmlCell::Layout is called, m_Height is set depending
574 on layout of subcells to the height of area covered by layed-out subcells.
575 Calling this method guarantees you that the height of container is never
576 smaller than @a h - even if the subcells cover much smaller area.
577
578 @param h
579 The minimal height.
580 @param align
581 If height of the container is lower than the minimum height, empty space
582 must be inserted somewhere in order to ensure minimal height.
583 This parameter is one of @c wxHTML_ALIGN_TOP, @c wxHTML_ALIGN_BOTTOM,
584 @c wxHTML_ALIGN_CENTER. It refers to the contents, not to the
585 empty place.
586 */
587 void SetMinHeight(int h, int align = wxHTML_ALIGN_TOP);
588
589 /**
590 Sets floating width adjustment.
591
592 The normal behaviour of container is that its width is the same as the width of
593 parent container (and thus you can have only one sub-container per line).
594 You can change this by setting the floating width adjustment.
595
596 @param w
597 Width of the container. If the value is negative it means
598 complement to full width of parent container.
599 E.g. @code SetWidthFloat(-50, wxHTML_UNITS_PIXELS) @endcode sets the
600 width of container to parent's width minus 50 pixels. This is useful when
601 creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50).
602 @param units
603 Units of w This parameter affects the interpretation of value.
604 - wxHTML_UNITS_PIXELS: @a w is number of pixels
605 - wxHTML_UNITS_PERCENT: @a w is interpreted as percents of width
606 of parent container
607 */
608 void SetWidthFloat(int w, int units);
609
610 /**
611 Sets floating width adjustment.
612
613 The normal behaviour of container is that its width is the same as the width of
614 parent container (and thus you can have only one sub-container per line).
615 You can change this by setting the floating width adjustment.
616
617 @param tag
618 In the second version of method, @a w and @a units info is extracted
619 from tag's WIDTH parameter.
620 @param pixel_scale
621 This is number of real pixels that equals to 1 HTML pixel.
622 */
623 void SetWidthFloat(const wxHtmlTag& tag,
624 double pixel_scale = 1.0);
625 };
626
627
628
629 /**
630 @class wxHtmlLinkInfo
631
632 This class stores all necessary information about hypertext links
633 (as represented by \<A\> tag in HTML documents).
634 In current implementation it stores URL and target frame name.
635
636 @note Frames are not currently supported by wxHTML!
637
638 @library{wxhtml}
639 @category{html}
640 */
641 class wxHtmlLinkInfo : public wxObject
642 {
643 public:
644 /**
645 Default ctor.
646 */
647 wxHtmlLinkInfo();
648
649 /**
650 Construct hypertext link from HREF (aka URL) and TARGET (name of target frame).
651 */
652 wxHtmlLinkInfo(const wxString& href,
653 const wxString& target = wxEmptyString);
654
655 /**
656 Return pointer to event that generated OnLinkClicked() event.
657 Valid only within wxHtmlWindow::OnLinkClicked, @NULL otherwise.
658 */
659 const wxMouseEvent* GetEvent() const;
660
661 /**
662 Return @e HREF value of the \<A\> tag.
663 */
664 wxString GetHref() const;
665
666 /**
667 Return pointer to the cell that was clicked.
668 Valid only within wxHtmlWindow::OnLinkClicked, @NULL otherwise.
669 */
670 const wxHtmlCell* GetHtmlCell() const;
671
672 /**
673 Return @e TARGET value of the \<A\> tag (this value is used to specify
674 in which frame should be the page pointed by @ref GetHref() Href opened).
675 */
676 wxString GetTarget() const;
677 };
678
679 /**
680 @class wxHtmlColourCell
681
682 This cell changes the colour of either the background or the foreground.
683
684 @library{wxhtml}
685 @category{html}
686 */
687 class wxHtmlColourCell : public wxHtmlCell
688 {
689 public:
690 /**
691 Constructor.
692
693 @param clr
694 The color
695 @param flags
696 Can be one of following:
697 - wxHTML_CLR_FOREGROUND: change color of text
698 - wxHTML_CLR_BACKGROUND: change background color
699 */
700 wxHtmlColourCell(const wxColour& clr, int flags = wxHTML_CLR_FOREGROUND);
701 };
702
703
704
705 /**
706 @class wxHtmlWidgetCell
707
708 wxHtmlWidgetCell is a class that provides a connection between HTML cells and
709 widgets (an object derived from wxWindow).
710 You can use it to display things like forms, input boxes etc. in an HTML window.
711
712 wxHtmlWidgetCell takes care of resizing and moving window.
713
714 @library{wxhtml}
715 @category{html}
716 */
717 class wxHtmlWidgetCell : public wxHtmlCell
718 {
719 public:
720 /**
721 Constructor.
722
723 @param wnd
724 Connected window. It is parent window @b must be the wxHtmlWindow object
725 within which it is displayed!
726 @param w
727 Floating width. If non-zero width of wnd window is adjusted so that it is
728 always w percents of parent container's width. (For example w = 100 means
729 that the window will always have same width as parent container).
730 */
731 wxHtmlWidgetCell(wxWindow* wnd, int w = 0);
732 };
733
734
735
736 /**
737 @class wxHtmlWordCell
738
739 This html cell represents a single word or text fragment in the document stream.
740
741 @library{wxhtml}
742 @category{html}
743 */
744 class wxHtmlWordCell : public wxHtmlCell
745 {
746 public:
747 wxHtmlWordCell(const wxString& word, const wxDC& dc);
748 };
749
750
751 /**
752 @class wxHtmlWordWithTabsCell
753
754 wxHtmlWordCell is a specialization for storing text fragments with
755 embedded tab characters.
756
757 @library{wxhtml}
758 @category{html}
759 */
760 class wxHtmlWordWithTabsCell : public wxHtmlWordCell
761 {
762 public:
763 wxHtmlWordWithTabsCell(const wxString& word,
764 const wxString& wordOrig,
765 size_t linepos,
766 const wxDC& dc);
767 };
768
769
770 /**
771 @class wxHtmlFontCell
772
773 This cell represents a font change in the document stream.
774
775 @library{wxhtml}
776 @category{html}
777 */
778 class wxHtmlFontCell : public wxHtmlCell
779 {
780 public:
781 wxHtmlFontCell(wxFont *font);
782 };