/////////////////////////////////////////////////////////////////////////////
// Name: html/htmlwin.h
-// Purpose: documentation for wxHtmlWindow class
+// Purpose: interface of wxHtmlWindow
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
@class wxHtmlWindow
@headerfile htmlwin.h wx/html/htmlwin.h
-
+
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 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
+ Once the window is created you can set its content by calling
@ref wxHtmlWindow::setpage SetPage(text),
@ref wxHtmlWindow::loadpage LoadPage(filename) or
wxHtmlWindow::LoadFile.
-
+
@beginStyleTable
- @style{wxHW_SCROLLBAR_NEVER}:
+ @style{wxHW_SCROLLBAR_NEVER}
Never display scrollbars, not even when the page is larger than the
window.
- @style{wxHW_SCROLLBAR_AUTO}:
+ @style{wxHW_SCROLLBAR_AUTO}
Display scrollbars only if page's size exceeds window's size.
- @style{wxHW_NO_SELECTION}:
+ @style{wxHW_NO_SELECTION}
Don't allow the user to select text.
@endStyleTable
-
+
@library{wxhtml}
@category{html}
-
- @seealso
- wxHtmlLinkEvent, wxHtmlCellEvent
+
+ @see wxHtmlLinkEvent, wxHtmlCellEvent
*/
class wxHtmlWindow : public wxScrolledWindow
{
public:
//@{
/**
- Constructor. The parameters are the same as for the wxScrolledWindow
+ Constructor. The parameters are the same as wxScrolled::wxScrolled()
constructor.
- @param style
- Window style. See wxHtmlWindow.
+ @param style
+ Window style. See wxHtmlWindow.
*/
wxHtmlWindow();
- wxHtmlWindow(wxWindow parent, wxWindowID id = -1,
- const wxPoint& pos = wxDefaultPosition,
- const wxSize& size = wxDefaultSize,
- long style = wxHW_DEFAULT_STYLE,
- const wxString& name = "htmlWindow");
+ wxHtmlWindow(wxWindow parent, wxWindowID id = -1,
+ const wxPoint& pos = wxDefaultPosition,
+ const wxSize& size = wxDefaultSize,
+ long style = wxHW_DEFAULT_STYLE,
+ const wxString& name = "htmlWindow");
//@}
/**
Adds @ref overview_filters "input filter" to the static list of available
filters. These filters are present by default:
-
@c text/html MIME type
@c image/* MIME types
Plain Text filter (this filter is used if no other filter matches)
static void AddFilter(wxHtmlFilter filter);
/**
- Appends HTML fragment to currently displayed text and refreshes the window.
+ Appends HTML fragment to currently displayed text and refreshes the window.
- @param source
- HTML code fragment
+ @param source
+ HTML code fragment
- @returns @false if an error occurred, @true otherwise.
+ @return @false if an error occurred, @true otherwise.
*/
bool AppendToPage(const wxString& source);
/**
Returns pointer to the top-level container.
-
- See also: @ref overview_cells "Cells Overview",
- @ref overview_printing "Printing Overview"
+ See also: @ref overview_cells "Cells Overview",
+ @ref overview_printing
*/
- wxHtmlContainerCell* GetInternalRepresentation();
+ wxHtmlContainerCell* GetInternalRepresentation() const;
/**
Returns anchor within currently opened page
- (see wxHtmlWindow::GetOpenedPage).
+ (see wxHtmlWindow::GetOpenedPage).
If no page is opened or if the displayed page wasn't
produced by call to LoadPage, empty string is returned.
*/
/**
Returns the related frame.
*/
- wxFrame* GetRelatedFrame();
+ wxFrame* GetRelatedFrame() const;
/**
- Moves back to the previous page. (each page displayed using
+ Moves back to the previous page. (each page displayed using
LoadPage() is stored in history list.)
*/
bool HistoryBack();
/**
Loads HTML page from file and displays it.
- @returns @false if an error occurred, @true otherwise
+ @return @false if an error occurred, @true otherwise
- @sa LoadPage()
+ @see LoadPage()
*/
virtual bool LoadFile(const wxFileName& filename);
/**
- Unlike SetPage this function first loads HTML page from @e location
+ Unlike SetPage this function first loads HTML page from @a location
and then displays it. See example:
- @param location
- The address of document. See wxFileSystem for details on address format and
+ @param location
+ The address of document. See wxFileSystem for details on address format and
behaviour of "opener".
- @returns @false if an error occurred, @true otherwise
+ @return @false if an error occurred, @true otherwise
- @sa LoadFile()
+ @see LoadFile()
*/
virtual bool LoadPage(const wxString& location);
/**
This method is called when a mouse button is clicked inside wxHtmlWindow.
-
The default behaviour is to emit a wxHtmlCellEvent
and, if the event was not processed or skipped, call
OnLinkClicked() if the cell contains an
hypertext link.
-
Overloading this method is deprecated; intercept the event instead.
- @param cell
- The cell inside which the mouse was clicked, always a simple
- (i.e. non-container) cell
-
- @param x, y
- The logical coordinates of the click point
+ @param cell
+ The cell inside which the mouse was clicked, always a simple
+ (i.e. non-container) cell
+ @param x, y
+ The logical coordinates of the click point
+ @param event
+ The mouse event containing other information about the click
- @param event
- The mouse event containing other information about the click
-
- @returns @true if a link was clicked, @false otherwise.
+ @return @true if a link was clicked, @false otherwise.
*/
virtual bool OnCellClicked(wxHtmlCell cell, wxCoord x, wxCoord y,
const wxMouseEvent& event);
Default behaviour is to emit a wxHtmlCellEvent.
Overloading this method is deprecated; intercept the event instead.
- @param cell
- The cell inside which the mouse is currently, always a simple
- (i.e. non-container) cell
-
- @param x, y
- The logical coordinates of the click point
+ @param cell
+ The cell inside which the mouse is currently, always a simple
+ (i.e. non-container) cell
+ @param x, y
+ The logical coordinates of the click point
*/
virtual void OnCellMouseHover(wxHtmlCell cell, wxCoord x,
wxCoord y);
wxHtmlLinkEvent and, if the event was not processed
or skipped, call LoadPage() and do nothing else.
Overloading this method is deprecated; intercept the event instead.
-
Also see wxHtmlLinkInfo.
*/
virtual void OnLinkClicked(const wxHtmlLinkInfo& link);
/**
Called when an URL is being opened (either when the user clicks on a link or
- an image is loaded). The URL will be opened only if OnOpeningURL returns
+ an image is loaded). The URL will be opened only if OnOpeningURL returns
@c wxHTML_OPEN. This method is called by
wxHtmlParser::OpenURL.
You can override OnOpeningURL to selectively block some
URLs (e.g. for security reasons) or to redirect them elsewhere. Default
behaviour is to always return @c wxHTML_OPEN.
- @param type
- Indicates type of the resource. Is one of
+ @param type
+ Indicates type of the resource. Is one of
+
+
+
+
+
+
+ wxHTML_URL_PAGE
+
+
+
+
+ Opening a HTML page.
+
+
- wxHTML_URL_PAGE
+ wxHTML_URL_IMAGE
- Opening a HTML page.
- wxHTML_URL_IMAGE
- Opening an image.
+ Opening an image.
- wxHTML_URL_OTHER
- Opening a resource that doesn't fall into
- any other category.
- @param url
- URL being opened.
- @param redirect
- Pointer to wxString variable that must be filled with an
- URL if OnOpeningURL returns wxHTML_REDIRECT.
+ wxHTML_URL_OTHER
+
+
+
+
+ Opening a resource that doesn't fall into
+ any other category.
+ @param url
+ URL being opened.
+ @param redirect
+ Pointer to wxString variable that must be filled with an
+ URL if OnOpeningURL returns wxHTML_REDIRECT.
*/
virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type,
- const wxString& url,
- wxString * redirect);
+ const wxString& url,
+ wxString* redirect);
/**
Called on parsing @c TITLE tag.
This reads custom settings from wxConfig. It uses the path 'path'
if given, otherwise it saves info into currently selected path.
The values are stored in sub-path @c wxHtmlWindow
-
Read values: all things set by SetFonts, SetBorders.
- @param cfg
- wxConfig from which you want to read the configuration.
-
- @param path
- Optional path in config tree. If not given current path is used.
+ @param cfg
+ wxConfig from which you want to read the configuration.
+ @param path
+ Optional path in config tree. If not given current path is used.
*/
virtual void ReadCustomization(wxConfigBase cfg,
wxString path = wxEmptyString);
/**
Selects all text in the window.
- @sa SelectLine(), SelectWord()
+ @see SelectLine(), SelectWord()
*/
void SelectAll();
/**
- Selects the line of text that @e pos points at. Note that @e pos
+ Selects the line of text that @a pos points at. Note that @e pos
is relative to the top of displayed page, not to window's origin, use
- wxScrolledWindow::CalcUnscrolledPosition
+ wxScrolled::CalcUnscrolledPosition()
to convert physical coordinate.
- @sa SelectAll(), SelectWord()
+ @see SelectAll(), SelectWord()
*/
void SelectLine(const wxPoint& pos);
/**
Selects the word at position @e pos. Note that @e pos
is relative to the top of displayed page, not to window's origin, use
- wxScrolledWindow::CalcUnscrolledPosition
+ wxScrolled::CalcUnscrolledPosition()
to convert physical coordinate.
- @sa SelectAll(), SelectLine()
+ @see SelectAll(), SelectLine()
*/
void SelectWord(const wxPoint& pos);
This function sets the space between border of window and HTML contents. See
image:
- @param b
- indentation from borders in pixels
+ @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.
+ @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.
*/
void SetFonts(const wxString& normal_face,
const wxString& fixed_face,
- const int sizes = @NULL);
+ 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:
- If you want to load a document from some location use
+
+ If you want to load a document from some location use
LoadPage() instead.
- @param source
- The HTML document source to be displayed.
+ @param source
+ The HTML document source to be displayed.
- @returns @false if an error occurred, @true otherwise.
+ @return @false if an error occurred, @true otherwise.
*/
bool SetPage(const wxString& source);
/**
- Sets the frame in which page title will be displayed. @e format is format of
+ Sets the frame in which page title will be displayed. @a format is format of
frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s. This
%s is substituted with HTML page title.
*/
@b After calling SetRelatedFrame(),
this sets statusbar slot where messages will be displayed.
(Default is -1 = no messages.)
-
- @param bar
- statusbar slot number (0..n)
+
+ @param index
+ Statusbar slot number (0..n)
*/
- void SetRelatedStatusBar(int bar);
+ void SetRelatedStatusBar(int index);
+
+ /**
+ @b Sets the associated statusbar where messages will be displayed.
+ Call this instead of SetRelatedFrame() if you want statusbar updates only,
+ no changing of the frame title.
+
+ @param statusbar
+ Statusbar pointer
+ @param index
+ Statusbar slot number (0..n)
+
+ @since 2.9.0
+ */
+ void SetRelatedStatusBar(wxStatusBar* statusbar, int index = 0);
/**
Returns content of currently displayed page as plain text.
/**
Saves custom settings into wxConfig. It uses the path 'path'
if given, otherwise it saves info into currently selected path.
- Regardless of whether the path is given or not, the function creates sub-path
+ Regardless of whether the path is given or not, the function creates sub-path
@c wxHtmlWindow.
-
Saved values: all things set by SetFonts, SetBorders.
- @param cfg
- wxConfig to which you want to save the configuration.
-
- @param path
- Optional path in config tree. If not given, the current path is used.
+ @param cfg
+ wxConfig to which you want to save the configuration.
+ @param path
+ Optional path in config tree. If not given, the current path is used.
*/
virtual void WriteCustomization(wxConfigBase cfg,
wxString path = wxEmptyString);
};
+
/**
@class wxHtmlLinkEvent
@headerfile htmlwin.h wx/html/htmlwin.h
-
+
This event class is used for the events generated by wxHtmlWindow.
-
+
@library{wxhtml}
@category{FIXME}
*/
/**
The constructor is not normally used by the user code.
*/
- wxHyperlinkEvent(int id, const wxHtmlLinkInfo & linkinfo);
+ wxHyperlinkEvent(int id, const wxHtmlLinkInfo& linkinfo);
/**
Returns the wxHtmlLinkInfo which contains info about the cell clicked and the
hyperlink it contains.
*/
- const wxHtmlLinkInfo GetLinkInfo();
+ const wxHtmlLinkInfo GetLinkInfo() const;
};
+
/**
@class wxHtmlCellEvent
@headerfile htmlwin.h wx/html/htmlwin.h
-
+
This event class is used for the events generated by wxHtmlWindow.
-
+
@library{wxhtml}
@category{FIXME}
*/
The constructor is not normally used by the user code.
*/
wxHtmlCellEvent(wxEventType commandType, int id,
- wxHtmlCell * cell,
- const wxPoint & point);
+ wxHtmlCell* cell,
+ const wxPoint& point);
/**
Returns the wxHtmlCellEvent associated with the event.
*/
- wxHtmlCell * GetCell();
+ wxHtmlCell* GetCell() const;
/**
Returns @true if @ref setlinkclicked() SetLinkClicked(@true) has previously
been called;
@false otherwise.
*/
- bool GetLinkClicked();
+ bool GetLinkClicked() const;
/**
Returns the wxPoint associated with the event.
*/
- wxPoint GetPoint();
+ wxPoint GetPoint() const;
/**
Call this function with @c linkclicked set to @true if the cell which has
*/
bool SetLinkClicked(bool linkclicked);
};
+
projects / wxWidgets.git / blobdiff