// Purpose: interface of wxHtmlWindow
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
wxHtmlWindow is probably the only class you will directly use unless you want
to do something special (like adding new tag handlers or MIME filters).
- The purpose of this class is to display HTML pages (either local file or
- downloaded via HTTP protocol) in a window.
+ The purpose of this class is to display rich content pages (either local file or
+ downloaded via HTTP protocol) in a window based on a subset of the HTML standard.
The width of the window is constant - given in the constructor - and virtual height
is changed dynamically depending on page size.
- Once the window is created you can set its content by calling SetPage(text),
- LoadPage(filename) or wxHtmlWindow::LoadFile.
+ Once the window is created you can set its content by calling SetPage() with raw HTML,
+ LoadPage() with a wxFileSystem location or LoadFile() with a filename.
@note
- wxHtmlWindow uses the wxImage class for displaying images.
- Don't forget to initialize all image formats you need before loading any page!
- (See ::wxInitAllImageHandlers and wxImage::AddHandler.)
+ If you want complete HTML/CSS support as well as a Javascript engine, see instead
+ wxWebView.
+
+ @note
+ wxHtmlWindow uses the wxImage class for displaying images, as such you need to
+ initialize the handlers for any image formats you use before loading a page.
+ See ::wxInitAllImageHandlers and wxImage::AddHandler.
@beginStyleTable
@style{wxHW_SCROLLBAR_NEVER}
@endStyleTable
- @beginEventTable{wxHtmlCellEvent, wxHtmlLinkEvent}
+ @beginEventEmissionTable{wxHtmlCellEvent, wxHtmlLinkEvent}
@event{EVT_HTML_CELL_CLICKED(id, func)}
A wxHtmlCell was clicked.
@event{EVT_HTML_CELL_HOVER(id, func)}
- @c image/* MIME types
- Plain Text filter (this filter is used if no other filter matches)
*/
- static void AddFilter(wxHtmlFilter filter);
+ static void AddFilter(wxHtmlFilter* filter);
/**
Appends HTML fragment to currently displayed text and refreshes the window.
wxString GetOpenedPage() const;
/**
- Returns title of the opened page or wxEmptyString if current page does not
+ Returns title of the opened page or wxEmptyString if the current page does not
contain \<TITLE\> tag.
*/
wxString GetOpenedPageTitle() const;
wxFrame* GetRelatedFrame() const;
/**
- Moves back to the previous page.
- (each page displayed using LoadPage() is stored in history list.)
+ Moves back to the previous page. Only pages displayed using LoadPage()
+ are stored in history list.
*/
bool HistoryBack();
/**
Returns @true if it is possible to go back in the history
- (i.e. HistoryBack() won't fail).
+ i.e. HistoryBack() won't fail.
*/
bool HistoryCanBack();
/**
Returns @true if it is possible to go forward in the history
- (i.e. HistoryBack() won't fail).
+ i.e. HistoryForward() won't fail.
*/
bool HistoryCanForward();
void HistoryClear();
/**
- Moves to next page in history.
+ Moves to next page in history. Only pages displayed using LoadPage()
+ are stored in history list.
*/
bool HistoryForward();
/**
- Loads HTML page from file and displays it.
+ Loads an HTML page from a file and displays it.
@return @false if an error occurred, @true otherwise
bool LoadFile(const wxFileName& filename);
/**
- Unlike SetPage() this function first loads HTML page from @a location
- and then displays it. See example:
+ Unlike SetPage() this function first loads the HTML page from @a location
+ and then displays it.
@param location
- The address of document.
- See wxFileSystem for details on address format and behaviour of "opener".
+ The address of the document.
+ See the @ref overview_fs for details on the address format
+ and wxFileSystem for a description of how the file is opened.
@return @false if an error occurred, @true otherwise
void SelectWord(const wxPoint& pos);
/**
- Returns current selection as plain text.
- Returns empty string if no text is currently selected.
+ Returns the current selection as plain text.
+ Returns an empty string if no text is currently selected.
*/
wxString SelectionToText();
/**
This function sets the space between border of window and HTML contents.
See image:
- @image html border.png
+ @image html htmlwin_border.png
@param b
indentation from borders in pixels
void SetBorders(int b);
/**
- This function sets font sizes and faces.
-
- @param normal_face
- This is face name for normal (i.e. non-fixed) font.
- It can be either empty string (then the default face is chosen) or
- platform-specific face name. Examples are "helvetica" under Unix or
- "Times New Roman" under Windows.
- @param fixed_face
- The same thing for fixed face ( \<TT\>..\</TT\> )
- @param sizes
- This is an array of 7 items of int type.
- The values represent size of font with HTML size from -2 to +4
- ( \<FONT SIZE=-2\> to \<FONT SIZE=+4\> ).
- Default sizes are used if sizes is @NULL.
+ This function sets font sizes and faces. See wxHtmlDCRenderer::SetFonts
+ for detailed description.
- Default font sizes are defined by constants wxHTML_FONT_SIZE_1,
- wxHTML_FONT_SIZE_2, ..., wxHTML_FONT_SIZE_7.
- Note that they differ among platforms. Default face names are empty strings.
+ @see SetSize()
*/
void SetFonts(const wxString& normal_face, const wxString& fixed_face,
const int* sizes = NULL);
/**
- Sets HTML page and display it. This won't @b load the page!!
- It will display the @e source. See example:
+ Sets default font sizes and/or default font size.
+ See wxHtmlDCRenderer::SetStandardFonts for detailed description.
+ @see SetFonts()
+ */
+ void SetStandardFonts(int size = -1,
+ const wxString& normal_face = wxEmptyString,
+ const wxString& fixed_face = wxEmptyString);
+
+ /**
+ Sets the source of a page and displays it, for example:
@code
htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
@endcode
If you want to load a document from some location use LoadPage() instead.
@param source
- The HTML document source to be displayed.
+ The HTML to be displayed.
@return @false if an error occurred, @true otherwise.
*/
projects / wxWidgets.git / blobdiff