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