X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/559fe022dbd5d4d961402b5c973e5225fa91f17f..9154d8cfff9f6a58ccec94bf242086e7e10ea91b:/docs/latex/wx/htwindow.tex diff --git a/docs/latex/wx/htwindow.tex b/docs/latex/wx/htwindow.tex index 361290ed33..2a821551f8 100644 --- a/docs/latex/wx/htwindow.tex +++ b/docs/latex/wx/htwindow.tex @@ -7,23 +7,30 @@ 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) +handlers or MIME filters). -Purpose of this class is to display HTML page (either local -file or downloaded via HTTP protocol) in a window. Width -of window is constant - given in constructor - virtual height -is changed dynamicly depending on page size. -Once the window is created you can set it's content by calling +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 \helpref{SetPage(text)}{wxhtmlwindowsetpage} or \helpref{LoadPage(filename)}{wxhtmlwindowloadpage}. +\wxheading{Note} + +wxHtmlWindow uses the \helpref{wxImage}{wximage} class for displaying images. +Don't forget to initialize all image formats you need before loading any page! +(See \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers} and +\helpref{wxImage::AddHandler}{wximageaddhandler}.) + \wxheading{Derived from} -wxScrolledWindow +\helpref{wxScrolledWindow}{wxscrolledwindow} \wxheading{Include files} - + \membersection{wxHtmlWindow::wxHtmlWindow}\label{wxhtmlwindowwxhtmlwindow} @@ -31,15 +38,14 @@ wxScrolledWindow Default constructor. -\func{}{wxHtmlWindow}{\param{wxWindow }{*parent}, \param{wxWindowID }{id = -1}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = wxHW_SCROLLBAR_AUTO}, \param{const wxString\& }{name = "htmlWindow"}} +\func{}{wxHtmlWindow}{\param{wxWindow }{*parent}, \param{wxWindowID }{id = -1}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = wxHW\_SCROLLBAR\_AUTO}, \param{const wxString\& }{name = "htmlWindow"}} -Constructor. The parameters are same as in wxScrollWindow ctor. -(Too lazy to document it once again... :-) +Constructor. The parameters are the same as for the \helpref{wxScrolledWindow}{wxscrolledwindow} constructor. \wxheading{Parameters} \docparam{style}{wxHW\_SCROLLBAR\_NEVER, or wxHW\_SCROLLBAR\_AUTO. -Affects appearance of vertical scrollbar in the window.} +Affects the appearance of vertical scrollbar in the window.} \membersection{wxHtmlWindow::AddFilter}\label{wxhtmlwindowaddfilter} @@ -48,12 +54,26 @@ Affects appearance of vertical scrollbar in the window.} Adds \helpref{input filter}{filters} to the static list of available filters. These filters are present by default: -\begin{itemize} +\begin{itemize}\itemsep=0pt \item {\tt text/html} MIME type \item {\tt image/*} MIME types \item Plain Text filter (this filter is used if no other filter matches) \end{itemize} +\membersection{wxHtmlWindow::AppendToPage}\label{wxhtmlwindowappendtopage} + +\func{bool}{AppendToPage}{\param{const wxString\& }{source}} + +Appends HTML fragment to currently displayed text and refreshes the window. + +\wxheading{Parameters} + +\docparam{source}{HTML code fragment} + +\wxheading{Return value} + +FALSE if an error occurred, TRUE otherwise. + \membersection{wxHtmlWindow::GetInternalRepresentation}\label{wxhtmlwindowgetinternalrepresentation} \constfunc{wxHtmlContainerCell*}{GetInternalRepresentation}{\void} @@ -63,6 +83,16 @@ Returns pointer to the top-level container. See also: \helpref{Cells Overview}{cells}, \helpref{Printing Overview}{printing} +\membersection{wxHtmlWindow::GetOpenedAnchor}\label{wxhtmlwindowgetopenedanchor} + +\func{wxString}{GetOpenedAnchor}{\void} + +Returns anchor within currently opened page +(see \helpref{GetOpenedPage}{wxhtmlwindowgetopenedpage}). +If no page is opened or if the displayed page wasn't +produced by call to LoadPage, empty string is returned. + + \membersection{wxHtmlWindow::GetOpenedPage}\label{wxhtmlwindowgetopenedpage} \func{wxString}{GetOpenedPage}{\void} @@ -70,6 +100,12 @@ See also: \helpref{Cells Overview}{cells}, Returns full location of the opened page. If no page is opened or if the displayed page wasn't produced by call to LoadPage, empty string is returned. +\membersection{wxHtmlWindow::GetOpenedPageTitle}\label{wxhtmlwindowgetopenedpagetitle} + +\func{wxString}{GetOpenedPageTitle}{\void} + +Returns title of the opened page or wxEmptyString if current page does not contain {\tt } tag. + \membersection{wxHtmlWindow::GetRelatedFrame}\label{wxhtmlwindowgetrelatedframe} \constfunc{wxFrame*}{GetRelatedFrame}{\void} @@ -83,6 +119,21 @@ Returns the related frame. Moves back to the previous page. (each page displayed using \helpref{LoadPage}{wxhtmlwindowloadpage} is stored in history list.) +\membersection{wxHtmlWindow::HistoryCanBack}\label{wxhtmlwindowhistorycanback} + +\func{bool}{HistoryCanBack}{\void} + +Returns true if it is possible to go back in the history (i.e. HistoryBack() +won't fail). + +\membersection{wxHtmlWindow::HistoryCanForward}\label{wxhtmlwindowhistorycanforward} + +\func{bool}{HistoryCanForward}{\void} + +Returns true if it is possible to go forward in the history (i.e. HistoryBack() +won't fail). + + \membersection{wxHtmlWindow::HistoryClear}\label{wxhtmlwindowhistoryclear} \func{void}{HistoryClear}{\void} @@ -97,9 +148,9 @@ Moves to next page in history. \membersection{wxHtmlWindow::LoadPage}\label{wxhtmlwindowloadpage} -\func{bool}{LoadPage}{\param{const wxString\& }{location}} +\func{virtual bool}{LoadPage}{\param{const wxString\& }{location}} -Unlike SetPage this function first loads HTML page from {\it location} +Unlike SetPage this function first loads HTML page from {\it location} and then displays it. See example: \begin{verbatim} @@ -112,15 +163,91 @@ htmlwin -> SetPage("help/myproject/index.htm"); \wxheading{Return value} -FALSE if an error occured, TRUE otherwise +FALSE if an error occurred, TRUE otherwise + +\membersection{wxHtmlWindow::OnCellClicked}\label{wxhtmlwindowoncellclicked} + +\func{virtual void}{OnCellClicked}{\param{wxHtmlCell }{*cell}, \param{wxCoord }{x}, \param{wxCoord }{y}, \param{const wxMouseEvent\& }{event}} + +This method is called when a mouse button is clicked inside wxHtmlWindow. +The default behaviour is to call +\helpref{OnLinkClicked}{wxhtmlwindowonlinkclicked} if the cell contains a +hypertext link. + +\wxheading{Parameters} + +\docparam{cell}{The cell inside which the mouse was clicked, always a simple +(i.e. non container) cell} + +\docparam{x, y}{The logical coordinates of the click point} + +\docparam{event}{The mouse event containing other information about the click} + +\membersection{wxHtmlWindow::OnCellMouseHover}\label{wxhtmlwindowoncellmousehover} + +\func{virtual void}{OnCellMouseHover}{\param{wxHtmlCell }{*cell}, \param{wxCoord }{x}, \param{wxCoord }{y}} + +This method is called when a mouse moves over an HTML cell. + +\wxheading{Parameters} + +\docparam{cell}{The cell inside which the mouse is currently, always a simple +(i.e. non container) cell} + +\docparam{x, y}{The logical coordinates of the click point} \membersection{wxHtmlWindow::OnLinkClicked}\label{wxhtmlwindowonlinkclicked} -\func{virtual void}{OnLinkClicked}{\param{const wxString\& }{link}} +\func{virtual void}{OnLinkClicked}{\param{const wxHtmlLinkInfo\& }{link}} Called when user clicks on hypertext link. Default behaviour is to call \helpref{LoadPage}{wxhtmlwindowloadpage} and do nothing else. +Also see \helpref{wxHtmlLinkInfo}{wxhtmllinkinfo}. + +\membersection{wxHtmlWindow::OnOpeningURL}\label{wxhtmlwindowonopeningurl} + +\func{virtual wxHtmlOpeningStatus}{OnOpeningURL}{\param{wxHtmlURLType }{type},\param{const wxString\& }{url}, \param{wxString *}{redirect}} + +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 +{\tt wxHTML\_OPEN}. This method is called by +\helpref{wxHtmlParser::OpenURL}{wxhtmlparseropenurl}. +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 {\tt wxHTML\_OPEN}. + +\wxheading{Parameters} + +\docparam{type}{Indicates type of the resource. Is one of +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf wxHTML\_URL\_PAGE}}{Opening a HTML page.} +\twocolitem{{\bf wxHTML\_URL\_IMAGE}}{Opening an image.} +\twocolitem{{\bf wxHTML\_URL\_OTHER}}{Opening a resource that doesn't fall into +any other category.} +\end{twocollist}} + +\docparam{url}{URL being opened.} + +\docparam{redirect}{Pointer to wxString variable that must be filled with an +URL if OnOpeningURL returns {\tt wxHTML\_REDIRECT}.} + +\wxheading{Return value} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf wxHTML\_OPEN}}{Open the URL.} +\twocolitem{{\bf wxHTML\_BLOCK}}{Deny access to the URL, \helpref{wxHtmlParser::OpenURL}{wxhtmlparseropenurl} will return NULL.} +\twocolitem{{\bf wxHTML\_REDIRECT}}{Don't open {\it url}, redirect to another +URL. OnOpeningURL must fill {\it *redirect} with the new URL. OnOpeningURL will +be called again on returned URL.} +\end{twocollist} + +\membersection{wxHtmlWindow::OnSetTitle}\label{wxhtmlwindowonsettitle} + +\func{virtual void}{OnSetTitle}{\param{const wxString\& }{title}} + +Called on parsing {\tt <TITLE>} tag. + + \membersection{wxHtmlWindow::ReadCustomization}\label{wxhtmlwindowreadcustomization} \func{virtual void}{ReadCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}} @@ -129,11 +256,11 @@ 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 {\tt wxHtmlWindow} -Read values : all things set by SetFonts, SetBorders. +Read values: all things set by SetFonts, SetBorders. \wxheading{Parameters} -\docparam{cfg}{wxConfig from which you wanna read configuration} +\docparam{cfg}{wxConfig from which you want to read the configuration.} \docparam{path}{Optional path in config tree. If not given current path is used.} @@ -143,7 +270,7 @@ Read values : all things set by SetFonts, SetBorders. This function sets the space between border of window and HTML contents. See image: -\image{}{border.bmp} +\helponly{\image{}{border.bmp}} \wxheading{Parameters} @@ -151,26 +278,18 @@ This function sets the space between border of window and HTML contents. See ima \membersection{wxHtmlWindow::SetFonts}\label{wxhtmlwindowsetfonts} -\func{void}{SetFonts}{\param{wxString }{normal\_face}, \param{int }{normal\_italic\_mode}, \param{wxString }{fixed\_face}, \param{int }{fixed\_italic\_mode}, \param{const int }{*sizes}} +\func{void}{SetFonts}{\param{wxString }{normal\_face}, \param{wxString }{fixed\_face}, \param{const int }{*sizes}} This function sets font sizes and faces. \wxheading{Parameters} -\docparam{normal_face}{This is face name for normal (i.e. non-fixed) font. +\docparam{normal\_face}{This is face name for normal (i.e. non-fixed) font. It can be either empty string (then the default face is choosen) or platform-specific face name. Examples are "helvetica" under Unix or "Times New Roman" under Windows.} -\docparam{normal_italic_mode}{This is either wxSLANT or wxITALIC. -It determines how -italic (<I>..</I>) text is handled. See wxFont documentation for -details. For example you should use wxSLANT in conjuction with -"helvetica" face or wxITALIC with "times" face.} - -\docparam{fixed_face}{The same thing for fixed face ( <TT>..</TT> )} - -\docparam{fixed_italic_mode}{The same thing for fixed face.} +\docparam{fixed\_face}{The same thing for fixed face ( <TT>..</TT> )} \docparam{sizes}{This is an array of 7 items of {\it int} type. The values represent size of font with HTML size from -2 to +4 @@ -181,13 +300,13 @@ The values represent size of font with HTML size from -2 to +4 Under wxGTK: \begin{verbatim} - SetFonts("", wxSLANT, "", wxSLANT, {10, 12, 14, 16, 19, 24, 32}); + SetFonts("", "", {10, 12, 14, 16, 19, 24, 32}); \end{verbatim} Under Windows: \begin{verbatim} - SetFonts("", wxSLANT, "", wxSLANT, {7, 8, 10, 12, 16, 22, 30}); + SetFonts("", "", {7, 8, 10, 12, 16, 22, 30}); \end{verbatim} Athough it seems different the fact is that the fonts are of approximately @@ -204,7 +323,7 @@ It will display the {\it source}. See example: htmlwin -> SetPage("<html><body>Hello, world!</body></html>"); \end{verbatim} -If you want to load document from some location use +If you want to load a document from some location use \helpref{LoadPage}{wxhtmlwindowloadpage} instead. \wxheading{Parameters} @@ -213,13 +332,13 @@ If you want to load document from some location use \wxheading{Return value} -FALSE if an error occured, TRUE otherwise +FALSE if an error occurred, TRUE otherwise. \membersection{wxHtmlWindow::SetRelatedFrame}\label{wxhtmlwindowsetrelatedframe} \func{void}{SetRelatedFrame}{\param{wxFrame* }{frame}, \param{const wxString\& }{format}} -Sets frame in which page title will be displayed. {\it format} is format of +Sets the frame in which page title will be displayed. {\it format} is format of frame title, e.g. "HtmlHelp : \%s". It must contain exactly one \%s. This \%s is substituted with HTML page title. @@ -235,21 +354,21 @@ this sets statusbar slot where messages will be displayed. \docparam{bar}{statusbar slot number (0..n)} + \membersection{wxHtmlWindow::WriteCustomization}\label{wxhtmlwindowwritecustomization} \func{virtual void}{WriteCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}} Saves custom settings into wxConfig. It uses the path 'path' if given, otherwise it saves info into currently selected path. -Regardless path is given or not the function creates sub-path -{\tt wxHtmlWindow} +Regardless of whether the path is given or not, the function creates sub-path +{\tt wxHtmlWindow}. -Saved values : all things set by SetFonts, SetBorders. +Saved values: all things set by SetFonts, SetBorders. \wxheading{Parameters} -\docparam{cfg}{wxConfig to which you wanna save configuration} - -\docparam{path}{Optional path in config tree. If not given current path is used.} +\docparam{cfg}{wxConfig to which you want to save the configuration.} +\docparam{path}{Optional path in config tree. If not given, the current path is used.}