]>
git.saurik.com Git - wxWidgets.git/blob - interface/html/htmlwin.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: html/htmlwin.h
3 // Purpose: interface of wxHtmlWindow
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
11 @headerfile htmlwin.h wx/html/htmlwin.h
13 wxHtmlWindow is probably the only class you will directly use
14 unless you want to do something special (like adding new tag
15 handlers or MIME filters).
17 The purpose of this class is to display HTML pages (either local
18 file or downloaded via HTTP protocol) in a window. The width
19 of the window is constant - given in the constructor - and virtual height
20 is changed dynamically depending on page size.
21 Once the window is created you can set its content by calling
22 @ref wxHtmlWindow::setpage SetPage(text),
23 @ref wxHtmlWindow::loadpage LoadPage(filename) or
24 wxHtmlWindow::LoadFile.
27 @style{wxHW_SCROLLBAR_NEVER}
28 Never display scrollbars, not even when the page is larger than the
30 @style{wxHW_SCROLLBAR_AUTO}
31 Display scrollbars only if page's size exceeds window's size.
32 @style{wxHW_NO_SELECTION}
33 Don't allow the user to select text.
39 @see wxHtmlLinkEvent, wxHtmlCellEvent
41 class wxHtmlWindow
: public wxScrolledWindow
46 Constructor. The parameters are the same as wxScrolled::wxScrolled()
50 Window style. See wxHtmlWindow.
53 wxHtmlWindow(wxWindow parent
, wxWindowID id
= -1,
54 const wxPoint
& pos
= wxDefaultPosition
,
55 const wxSize
& size
= wxDefaultSize
,
56 long style
= wxHW_DEFAULT_STYLE
,
57 const wxString
& name
= "htmlWindow");
61 Adds @ref overview_filters "input filter" to the static list of available
62 filters. These filters are present by default:
63 @c text/html MIME type
65 Plain Text filter (this filter is used if no other filter matches)
67 static void AddFilter(wxHtmlFilter filter
);
70 Appends HTML fragment to currently displayed text and refreshes the window.
75 @return @false if an error occurred, @true otherwise.
77 bool AppendToPage(const wxString
& source
);
80 Returns pointer to the top-level container.
81 See also: @ref overview_cells "Cells Overview",
82 @ref overview_printing
84 wxHtmlContainerCell
* GetInternalRepresentation() const;
87 Returns anchor within currently opened page
88 (see wxHtmlWindow::GetOpenedPage).
89 If no page is opened or if the displayed page wasn't
90 produced by call to LoadPage, empty string is returned.
92 wxString
GetOpenedAnchor();
95 Returns full location of the opened page. If no page is opened or if the
97 produced by call to LoadPage, empty string is returned.
99 wxString
GetOpenedPage();
102 Returns title of the opened page or wxEmptyString if current page does not
103 contain @c TITLE tag.
105 wxString
GetOpenedPageTitle();
108 Returns the related frame.
110 wxFrame
* GetRelatedFrame() const;
113 Moves back to the previous page. (each page displayed using
114 LoadPage() is stored in history list.)
119 Returns @true if it is possible to go back in the history (i.e. HistoryBack()
122 bool HistoryCanBack();
125 Returns @true if it is possible to go forward in the history (i.e. HistoryBack()
128 bool HistoryCanForward();
136 Moves to next page in history.
138 bool HistoryForward();
141 Loads HTML page from file and displays it.
143 @return @false if an error occurred, @true otherwise
147 virtual bool LoadFile(const wxFileName
& filename
);
150 Unlike SetPage this function first loads HTML page from @a location
151 and then displays it. See example:
154 The address of document. See wxFileSystem for details on address format and
155 behaviour of "opener".
157 @return @false if an error occurred, @true otherwise
161 virtual bool LoadPage(const wxString
& location
);
164 This method is called when a mouse button is clicked inside wxHtmlWindow.
165 The default behaviour is to emit a wxHtmlCellEvent
166 and, if the event was not processed or skipped, call
167 OnLinkClicked() if the cell contains an
169 Overloading this method is deprecated; intercept the event instead.
172 The cell inside which the mouse was clicked, always a simple
173 (i.e. non-container) cell
175 The logical coordinates of the click point
177 The mouse event containing other information about the click
179 @return @true if a link was clicked, @false otherwise.
181 virtual bool OnCellClicked(wxHtmlCell cell
, wxCoord x
, wxCoord y
,
182 const wxMouseEvent
& event
);
185 This method is called when a mouse moves over an HTML cell.
186 Default behaviour is to emit a wxHtmlCellEvent.
187 Overloading this method is deprecated; intercept the event instead.
190 The cell inside which the mouse is currently, always a simple
191 (i.e. non-container) cell
193 The logical coordinates of the click point
195 virtual void OnCellMouseHover(wxHtmlCell cell
, wxCoord x
,
199 Called when user clicks on hypertext link. Default behaviour is to emit a
200 wxHtmlLinkEvent and, if the event was not processed
201 or skipped, call LoadPage() and do nothing else.
202 Overloading this method is deprecated; intercept the event instead.
203 Also see wxHtmlLinkInfo.
205 virtual void OnLinkClicked(const wxHtmlLinkInfo
& link
);
208 Called when an URL is being opened (either when the user clicks on a link or
209 an image is loaded). The URL will be opened only if OnOpeningURL returns
210 @c wxHTML_OPEN. This method is called by
211 wxHtmlParser::OpenURL.
212 You can override OnOpeningURL to selectively block some
213 URLs (e.g. for security reasons) or to redirect them elsewhere. Default
214 behaviour is to always return @c wxHTML_OPEN.
217 Indicates type of the resource. Is one of
251 Opening a resource that doesn't fall into
256 Pointer to wxString variable that must be filled with an
257 URL if OnOpeningURL returns wxHTML_REDIRECT.
259 virtual wxHtmlOpeningStatus
OnOpeningURL(wxHtmlURLType type
,
264 Called on parsing @c TITLE tag.
266 virtual void OnSetTitle(const wxString
& title
);
269 This reads custom settings from wxConfig. It uses the path 'path'
270 if given, otherwise it saves info into currently selected path.
271 The values are stored in sub-path @c wxHtmlWindow
272 Read values: all things set by SetFonts, SetBorders.
275 wxConfig from which you want to read the configuration.
277 Optional path in config tree. If not given current path is used.
279 virtual void ReadCustomization(wxConfigBase cfg
,
280 wxString path
= wxEmptyString
);
283 Selects all text in the window.
285 @see SelectLine(), SelectWord()
290 Selects the line of text that @a pos points at. Note that @e pos
291 is relative to the top of displayed page, not to window's origin, use
292 wxScrolled::CalcUnscrolledPosition()
293 to convert physical coordinate.
295 @see SelectAll(), SelectWord()
297 void SelectLine(const wxPoint
& pos
);
300 Selects the word at position @e pos. Note that @e pos
301 is relative to the top of displayed page, not to window's origin, use
302 wxScrolled::CalcUnscrolledPosition()
303 to convert physical coordinate.
305 @see SelectAll(), SelectLine()
307 void SelectWord(const wxPoint
& pos
);
310 Returns current selection as plain text. Returns empty string if no text
311 is currently selected.
313 wxString
SelectionToText();
316 This function sets the space between border of window and HTML contents. See
320 indentation from borders in pixels
322 void SetBorders(int b
);
325 This function sets font sizes and faces.
328 This is face name for normal (i.e. non-fixed) font.
329 It can be either empty string (then the default face is chosen) or
330 platform-specific face name. Examples are "helvetica" under Unix or
331 "Times New Roman" under Windows.
333 The same thing for fixed face ( TT../TT )
335 This is an array of 7 items of int type.
336 The values represent size of font with HTML size from -2 to +4
337 ( FONT SIZE=-2 to FONT SIZE=+4 ). Default sizes are used if sizes
340 void SetFonts(const wxString
& normal_face
,
341 const wxString
& fixed_face
,
342 const int sizes
= NULL
);
345 Sets HTML page and display it. This won't @b load the page!!
346 It will display the @e source. See example:
348 If you want to load a document from some location use
352 The HTML document source to be displayed.
354 @return @false if an error occurred, @true otherwise.
356 bool SetPage(const wxString
& source
);
359 Sets the frame in which page title will be displayed. @a format is format of
360 frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s. This
361 %s is substituted with HTML page title.
363 void SetRelatedFrame(wxFrame
* frame
, const wxString
& format
);
366 @b After calling SetRelatedFrame(),
367 this sets statusbar slot where messages will be displayed.
368 (Default is -1 = no messages.)
371 Statusbar slot number (0..n)
373 void SetRelatedStatusBar(int index
);
376 @b Sets the associated statusbar where messages will be displayed.
377 Call this instead of SetRelatedFrame() if you want statusbar updates only,
378 no changing of the frame title.
383 Statusbar slot number (0..n)
387 void SetRelatedStatusBar(wxStatusBar
* statusbar
, int index
= 0);
390 Returns content of currently displayed page as plain text.
395 Saves custom settings into wxConfig. It uses the path 'path'
396 if given, otherwise it saves info into currently selected path.
397 Regardless of whether the path is given or not, the function creates sub-path
399 Saved values: all things set by SetFonts, SetBorders.
402 wxConfig to which you want to save the configuration.
404 Optional path in config tree. If not given, the current path is used.
406 virtual void WriteCustomization(wxConfigBase cfg
,
407 wxString path
= wxEmptyString
);
413 @class wxHtmlLinkEvent
414 @headerfile htmlwin.h wx/html/htmlwin.h
416 This event class is used for the events generated by wxHtmlWindow.
421 class wxHtmlLinkEvent
: public wxCommandEvent
425 The constructor is not normally used by the user code.
427 wxHyperlinkEvent(int id
, const wxHtmlLinkInfo
& linkinfo
);
430 Returns the wxHtmlLinkInfo which contains info about the cell clicked and the
431 hyperlink it contains.
433 const wxHtmlLinkInfo
GetLinkInfo() const;
439 @class wxHtmlCellEvent
440 @headerfile htmlwin.h wx/html/htmlwin.h
442 This event class is used for the events generated by wxHtmlWindow.
447 class wxHtmlCellEvent
: public wxCommandEvent
451 The constructor is not normally used by the user code.
453 wxHtmlCellEvent(wxEventType commandType
, int id
,
455 const wxPoint
& point
);
458 Returns the wxHtmlCellEvent associated with the event.
460 wxHtmlCell
* GetCell() const;
463 Returns @true if @ref setlinkclicked() SetLinkClicked(@true) has previously
467 bool GetLinkClicked() const;
470 Returns the wxPoint associated with the event.
472 wxPoint
GetPoint() const;
475 Call this function with @c linkclicked set to @true if the cell which has
476 been clicked contained a link or
477 @false otherwise (which is the default). With this function the event handler
478 can return info to the
479 wxHtmlWindow which sent the event.
481 bool SetLinkClicked(bool linkclicked
);