← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/html/htmlcell.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

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