]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/html/htmlwin.h
Add missing code tag before lots of wxEventTypes in the documentation. Although most...
[wxWidgets.git] / interface / wx / html / htmlwin.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: html/htmlwin.h
3// Purpose: interface of wxHtmlWindow
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows licence
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxHtmlWindow
11
12 wxHtmlWindow is probably the only class you will directly use unless you want
13 to do something special (like adding new tag handlers or MIME filters).
14
15 The purpose of this class is to display HTML pages (either local file or
16 downloaded via HTTP protocol) in a window.
17 The width of the window is constant - given in the constructor - and virtual height
18 is changed dynamically depending on page size.
19 Once the window is created you can set its content by calling SetPage() with raw HTML,
20 LoadPage() with a wxFileSystem location or LoadFile() with a filename.
21
22 @note
23 wxHtmlWindow uses the wxImage class for displaying images, as such you need to
24 initialize the handlers for any image formats you use before loading a page.
25 See ::wxInitAllImageHandlers and wxImage::AddHandler.
26
27 @beginStyleTable
28 @style{wxHW_SCROLLBAR_NEVER}
29 Never display scrollbars, not even when the page is larger than the
30 window.
31 @style{wxHW_SCROLLBAR_AUTO}
32 Display scrollbars only if page's size exceeds window's size.
33 @style{wxHW_NO_SELECTION}
34 Don't allow the user to select text.
35 @endStyleTable
36
37
38 @beginEventEmissionTable{wxHtmlCellEvent, wxHtmlLinkEvent}
39 @event{EVT_HTML_CELL_CLICKED(id, func)}
40 A wxHtmlCell was clicked.
41 @event{EVT_HTML_CELL_HOVER(id, func)}
42 The mouse passed over a wxHtmlCell.
43 @event{EVT_HTML_LINK_CLICKED(id, func)}
44 A wxHtmlCell which contains an hyperlink was clicked.
45 @endEventTable
46
47 @library{wxhtml}
48 @category{html}
49
50 @see wxHtmlLinkEvent, wxHtmlCellEvent
51*/
52class wxHtmlWindow : public wxScrolledWindow
53{
54public:
55 /**
56 Default ctor.
57 */
58 wxHtmlWindow();
59
60 /**
61 Constructor.
62 The parameters are the same as wxScrolled::wxScrolled() constructor.
63 */
64 wxHtmlWindow(wxWindow *parent, wxWindowID id = wxID_ANY,
65 const wxPoint& pos = wxDefaultPosition,
66 const wxSize& size = wxDefaultSize,
67 long style = wxHW_DEFAULT_STYLE,
68 const wxString& name = "htmlWindow");
69
70 /**
71 Adds @ref overview_html_filters "input filter" to the static list of available
72 filters. These filters are present by default:
73 - @c text/html MIME type
74 - @c image/* MIME types
75 - Plain Text filter (this filter is used if no other filter matches)
76 */
77 static void AddFilter(wxHtmlFilter* filter);
78
79 /**
80 Appends HTML fragment to currently displayed text and refreshes the window.
81
82 @param source
83 HTML code fragment
84
85 @return @false if an error occurred, @true otherwise.
86 */
87 bool AppendToPage(const wxString& source);
88
89 /**
90 Returns pointer to the top-level container.
91
92 @see @ref overview_html_cells, @ref overview_printing
93 */
94 wxHtmlContainerCell* GetInternalRepresentation() const;
95
96 /**
97 Returns anchor within currently opened page (see wxHtmlWindow::GetOpenedPage).
98 If no page is opened or if the displayed page wasn't produced by call to
99 LoadPage(), empty string is returned.
100 */
101 wxString GetOpenedAnchor() const;
102
103 /**
104 Returns full location of the opened page.
105 If no page is opened or if the displayed page wasn't produced by call to
106 LoadPage(), empty string is returned.
107 */
108 wxString GetOpenedPage() const;
109
110 /**
111 Returns title of the opened page or wxEmptyString if the current page does not
112 contain \<TITLE\> tag.
113 */
114 wxString GetOpenedPageTitle() const;
115
116 /**
117 Returns the related frame.
118 */
119 wxFrame* GetRelatedFrame() const;
120
121 /**
122 Moves back to the previous page. Only pages displayed using LoadPage()
123 are stored in history list.
124 */
125 bool HistoryBack();
126
127 /**
128 Returns @true if it is possible to go back in the history
129 i.e. HistoryBack() won't fail.
130 */
131 bool HistoryCanBack();
132
133 /**
134 Returns @true if it is possible to go forward in the history
135 i.e. HistoryForward() won't fail.
136 */
137 bool HistoryCanForward();
138
139 /**
140 Clears history.
141 */
142 void HistoryClear();
143
144 /**
145 Moves to next page in history. Only pages displayed using LoadPage()
146 are stored in history list.
147 */
148 bool HistoryForward();
149
150 /**
151 Loads an HTML page from a file and displays it.
152
153 @return @false if an error occurred, @true otherwise
154
155 @see LoadPage()
156 */
157 bool LoadFile(const wxFileName& filename);
158
159 /**
160 Unlike SetPage() this function first loads the HTML page from @a location
161 and then displays it.
162
163 @param location
164 The address of the document.
165 See the @ref overview_fs for details on the address format
166 and wxFileSystem for a description of how the file is opened.
167
168 @return @false if an error occurred, @true otherwise
169
170 @see LoadFile()
171 */
172 virtual bool LoadPage(const wxString& location);
173
174 /**
175 Called when user clicks on hypertext link.
176 Default behaviour is to emit a wxHtmlLinkEvent and, if the event was not
177 processed or skipped, call LoadPage() and do nothing else.
178
179 Overloading this method is deprecated; intercept the event instead.
180
181 Also see wxHtmlLinkInfo.
182 */
183 virtual void OnLinkClicked(const wxHtmlLinkInfo& link);
184
185 /**
186 Called when an URL is being opened (either when the user clicks on a link or
187 an image is loaded). The URL will be opened only if OnOpeningURL() returns
188 @c wxHTML_OPEN. This method is called by wxHtmlParser::OpenURL.
189
190 You can override OnOpeningURL() to selectively block some URLs
191 (e.g. for security reasons) or to redirect them elsewhere.
192 Default behaviour is to always return @c wxHTML_OPEN.
193
194 @param type
195 Indicates type of the resource. Is one of
196 - wxHTML_URL_PAGE: Opening a HTML page.
197 - wxHTML_URL_IMAGE: Opening an image.
198 - wxHTML_URL_OTHER: Opening a resource that doesn't fall into
199 any other category.
200 @param url
201 URL being opened.
202 @param redirect
203 Pointer to wxString variable that must be filled with an
204 URL if OnOpeningURL() returns @c wxHTML_REDIRECT.
205
206 The return value is:
207 - wxHTML_OPEN: Open the URL.
208 - wxHTML_BLOCK: Deny access to the URL, wxHtmlParser::OpenURL will return @NULL.
209 - wxHTML_REDIRECT: Don't open url, redirect to another URL.
210 OnOpeningURL() must fill *redirect with the new URL.
211 OnOpeningURL() will be called again on returned URL.
212 */
213 virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type,
214 const wxString& url,
215 wxString* redirect) const;
216
217 /**
218 Called on parsing \<TITLE\> tag.
219 */
220 virtual void OnSetTitle(const wxString& title);
221
222 /**
223 This reads custom settings from wxConfig. It uses the path 'path'
224 if given, otherwise it saves info into currently selected path.
225 The values are stored in sub-path @c wxHtmlWindow.
226 Read values: all things set by SetFonts(), SetBorders().
227
228 @param cfg
229 wxConfig from which you want to read the configuration.
230 @param path
231 Optional path in config tree. If not given current path is used.
232 */
233 virtual void ReadCustomization(wxConfigBase* cfg,
234 wxString path = wxEmptyString);
235
236 /**
237 Selects all text in the window.
238
239 @see SelectLine(), SelectWord()
240 */
241 void SelectAll();
242
243 /**
244 Selects the line of text that @a pos points at. Note that @e pos
245 is relative to the top of displayed page, not to window's origin, use
246 wxScrolled::CalcUnscrolledPosition()
247 to convert physical coordinate.
248
249 @see SelectAll(), SelectWord()
250 */
251 void SelectLine(const wxPoint& pos);
252
253 /**
254 Selects the word at position @a pos.
255 Note that @a pos is relative to the top of displayed page, not to window's
256 origin, use wxScrolled::CalcUnscrolledPosition() to convert physical coordinate.
257
258 @see SelectAll(), SelectLine()
259 */
260 void SelectWord(const wxPoint& pos);
261
262 /**
263 Returns the current selection as plain text.
264 Returns an empty string if no text is currently selected.
265 */
266 wxString SelectionToText();
267
268 /**
269 This function sets the space between border of window and HTML contents.
270 See image:
271 @image html htmlwin_border.png
272
273 @param b
274 indentation from borders in pixels
275 */
276 void SetBorders(int b);
277
278 /**
279 This function sets font sizes and faces. See wxHtmlDCRenderer::SetFonts
280 for detailed description.
281
282 @see SetSize()
283 */
284 void SetFonts(const wxString& normal_face, const wxString& fixed_face,
285 const int* sizes = NULL);
286
287 /**
288 Sets default font sizes and/or default font size.
289 See wxHtmlDCRenderer::SetStandardFonts for detailed description.
290 @see SetFonts()
291 */
292 void SetStandardFonts(int size = -1,
293 const wxString& normal_face = wxEmptyString,
294 const wxString& fixed_face = wxEmptyString);
295
296 /**
297 Sets the source of a page and displays it, for example:
298 @code
299 htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
300 @endcode
301
302 If you want to load a document from some location use LoadPage() instead.
303
304 @param source
305 The HTML to be displayed.
306
307 @return @false if an error occurred, @true otherwise.
308 */
309 virtual bool SetPage(const wxString& source);
310
311 /**
312 Sets the frame in which page title will be displayed.
313 @a format is the format of the frame title, e.g. "HtmlHelp : %s".
314 It must contain exactly one %s.
315 This %s is substituted with HTML page title.
316 */
317 void SetRelatedFrame(wxFrame* frame, const wxString& format);
318
319 /**
320 @b After calling SetRelatedFrame(), this sets statusbar slot where messages
321 will be displayed. (Default is -1 = no messages.)
322
323 @param index
324 Statusbar slot number (0..n)
325 */
326 void SetRelatedStatusBar(int index);
327
328 /**
329 @b Sets the associated statusbar where messages will be displayed.
330 Call this instead of SetRelatedFrame() if you want statusbar updates only,
331 no changing of the frame title.
332
333 @param statusbar
334 Statusbar pointer
335 @param index
336 Statusbar slot number (0..n)
337
338 @since 2.9.0
339 */
340 void SetRelatedStatusBar(wxStatusBar* statusbar, int index = 0);
341
342 /**
343 Returns content of currently displayed page as plain text.
344 */
345 wxString ToText();
346
347 /**
348 Saves custom settings into wxConfig.
349 It uses the path 'path' if given, otherwise it saves info into currently
350 selected path.
351 Regardless of whether the path is given or not, the function creates
352 sub-path @c wxHtmlWindow.
353
354 Saved values: all things set by SetFonts(), SetBorders().
355
356 @param cfg
357 wxConfig to which you want to save the configuration.
358 @param path
359 Optional path in config tree. If not given, the current path is used.
360 */
361 virtual void WriteCustomization(wxConfigBase* cfg,
362 wxString path = wxEmptyString);
363
364protected:
365
366 /**
367 This method is called when a mouse button is clicked inside wxHtmlWindow.
368 The default behaviour is to emit a wxHtmlCellEvent and, if the event was
369 not processed or skipped, call OnLinkClicked() if the cell contains an
370 hypertext link.
371
372 Overloading this method is deprecated; intercept the event instead.
373
374 @param cell
375 The cell inside which the mouse was clicked, always a simple
376 (i.e. non-container) cell
377 @param x
378 The logical x coordinate of the click point
379 @param y
380 The logical y coordinate of the click point
381 @param event
382 The mouse event containing other information about the click
383
384 @return @true if a link was clicked, @false otherwise.
385 */
386 virtual bool OnCellClicked(wxHtmlCell* cell, wxCoord x, wxCoord y,
387 const wxMouseEvent& event);
388
389 /**
390 This method is called when a mouse moves over an HTML cell.
391 Default behaviour is to emit a wxHtmlCellEvent.
392
393 Overloading this method is deprecated; intercept the event instead.
394
395 @param cell
396 The cell inside which the mouse is currently, always a simple
397 (i.e. non-container) cell
398 @param x
399 The logical x coordinate of the click point
400 @param y
401 The logical y coordinate of the click point
402 */
403 virtual void OnCellMouseHover(wxHtmlCell* cell, wxCoord x, wxCoord y);
404};
405
406
407
408/**
409 @class wxHtmlLinkEvent
410
411 This event class is used for the events generated by wxHtmlWindow.
412
413 @beginEventTable{wxHtmlLinkEvent}
414 @event{EVT_HTML_LINK_CLICKED(id, func)}
415 User clicked on an hyperlink.
416 @endEventTable
417
418 @library{wxhtml}
419 @category{html}
420*/
421class wxHtmlLinkEvent : public wxCommandEvent
422{
423public:
424 /**
425 The constructor is not normally used by the user code.
426 */
427 wxHtmlLinkEvent(int id, const wxHtmlLinkInfo& linkinfo);
428
429 /**
430 Returns the wxHtmlLinkInfo which contains info about the cell clicked
431 and the hyperlink it contains.
432 */
433 const wxHtmlLinkInfo& GetLinkInfo() const;
434};
435
436
437
438/**
439 @class wxHtmlCellEvent
440
441 This event class is used for the events generated by wxHtmlWindow.
442
443 @beginEventTable{wxHtmlCellEvent}
444 @event{EVT_HTML_CELL_HOVER(id, func)}
445 User moved the mouse over a wxHtmlCell.
446 @event{EVT_HTML_CELL_CLICKED(id, func)}
447 User clicked on a wxHtmlCell. When handling this event, remember to use
448 wxHtmlCell::SetLinkClicked(true) if the cell contains a link.
449 @endEventTable
450
451 @library{wxhtml}
452 @category{html}
453*/
454class wxHtmlCellEvent : public wxCommandEvent
455{
456public:
457 /**
458 The constructor is not normally used by the user code.
459 */
460 wxHtmlCellEvent(wxEventType commandType, int id,
461 wxHtmlCell* cell,
462 const wxPoint& point,
463 const wxMouseEvent& ev);
464
465 /**
466 Returns the wxHtmlCellEvent associated with the event.
467 */
468 wxHtmlCell* GetCell() const;
469
470 /**
471 Returns @true if SetLinkClicked(@true) has previously been called;
472 @false otherwise.
473 */
474 bool GetLinkClicked() const;
475
476 /**
477 Returns the wxPoint associated with the event.
478 */
479 wxPoint GetPoint() const;
480
481 /**
482 Call this function with @a linkclicked set to @true if the cell which has
483 been clicked contained a link or @false otherwise (which is the default).
484
485 With this function the event handler can return info to the wxHtmlWindow
486 which sent the event.
487 */
488 void SetLinkClicked(bool linkclicked);
489};
490