]> git.saurik.com Git - wxWidgets.git/blobdiff - docs/latex/wx/htwindow.tex
change wxTextValidator to use wxArrayString instead of wxStringList
[wxWidgets.git] / docs / latex / wx / htwindow.tex
index 755971ed4a675f94bc4e720e4a6d81e68ef13be5..45a4da383382bec7900ffa884bb288a03cff53d2 100644 (file)
@@ -13,17 +13,37 @@ 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.
 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}. 
+Once the window is created you can set its content by calling 
+\helpref{SetPage(text)}{wxhtmlwindowsetpage},
+\helpref{LoadPage(filename)}{wxhtmlwindowloadpage} or
+\helpref{LoadFile}{wxhtmlwindowloadfile}.
+
+\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}
 
 
 \wxheading{Derived from}
 
-wxScrolledWindow
+\helpref{wxScrolledWindow}{wxscrolledwindow}
 
 \wxheading{Include files}
 
 
 \wxheading{Include files}
 
-<wxhtml/wxhtmlwin.h>
+<wx/html/htmlwin.h>
+
+\wxheading{Window styles}
+
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxHW\_SCROLLBAR\_NEVER}}{Never display scrollbars, not
+even when the page is larger than the window.}
+\twocolitem{\windowstyle{wxHW\_SCROLLBAR\_AUTO}}{Display scrollbars only if
+page's size exceeds window's size.}
+\twocolitem{\windowstyle{wxHW\_NO\_SELECTION}}{Don't allow the user to select
+text.}
+\end{twocollist}
 
 \membersection{wxHtmlWindow::wxHtmlWindow}\label{wxhtmlwindowwxhtmlwindow}
 
 
 \membersection{wxHtmlWindow::wxHtmlWindow}\label{wxhtmlwindowwxhtmlwindow}
 
@@ -31,14 +51,13 @@ wxScrolledWindow
 
 Default constructor.
 
 
 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 the same as for the \helpref{wxScrolledWindow}{wxscrolledwindow} constructor.
 
 \wxheading{Parameters}
 
 
 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 the appearance of vertical scrollbar in the window.}
+\docparam{style}{Window style. See \helpref{wxHtmlWindow}{wxhtmlwindow}.}
 
 \membersection{wxHtmlWindow::AddFilter}\label{wxhtmlwindowaddfilter}
 
 
 \membersection{wxHtmlWindow::AddFilter}\label{wxhtmlwindowaddfilter}
 
@@ -53,6 +72,20 @@ filters. These filters are present by default:
 \item Plain Text filter (this filter is used if no other filter matches)
 \end{itemize}
 
 \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}
 \membersection{wxHtmlWindow::GetInternalRepresentation}\label{wxhtmlwindowgetinternalrepresentation}
 
 \constfunc{wxHtmlContainerCell*}{GetInternalRepresentation}{\void}
@@ -62,6 +95,16 @@ Returns pointer to the top-level container.
 See also: \helpref{Cells Overview}{cells}, 
 \helpref{Printing Overview}{printing}
 
 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}
 \membersection{wxHtmlWindow::GetOpenedPage}\label{wxhtmlwindowgetopenedpage}
 
 \func{wxString}{GetOpenedPage}{\void}
@@ -69,6 +112,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.
 
 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 <TITLE>} tag.
+
 \membersection{wxHtmlWindow::GetRelatedFrame}\label{wxhtmlwindowgetrelatedframe}
 
 \constfunc{wxFrame*}{GetRelatedFrame}{\void}
 \membersection{wxHtmlWindow::GetRelatedFrame}\label{wxhtmlwindowgetrelatedframe}
 
 \constfunc{wxFrame*}{GetRelatedFrame}{\void}
@@ -82,6 +131,21 @@ Returns the related frame.
 Moves back to the previous page. (each page displayed using 
 \helpref{LoadPage}{wxhtmlwindowloadpage} is stored in history list.)
 
 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}
 \membersection{wxHtmlWindow::HistoryClear}\label{wxhtmlwindowhistoryclear}
 
 \func{void}{HistoryClear}{\void}
@@ -94,15 +158,29 @@ Clears history.
 
 Moves to next page in history.
 
 
 Moves to next page in history.
 
+\membersection{wxHtmlWindow::LoadFile}\label{wxhtmlwindowloadfile}
+
+\func{virtual bool}{LoadFile}{\param{const wxFileName\& }{filename}}
+
+Loads HTML page from file and displays it.
+
+\wxheading{Return value}
+
+false if an error occurred, true otherwise
+
+\wxheading{See also}
+
+\helpref{LoadPage}{wxhtmlwindowloadpage}
+
 \membersection{wxHtmlWindow::LoadPage}\label{wxhtmlwindowloadpage}
 
 \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} 
 and then displays it. See example:
 
 \begin{verbatim}
 
 Unlike SetPage this function first loads HTML page from {\it location} 
 and then displays it. See example:
 
 \begin{verbatim}
-htmlwin -> SetPage("help/myproject/index.htm");
+htmlwin->LoadPage("help/myproject/index.htm");
 \end{verbatim}
 
 \wxheading{Parameters}
 \end{verbatim}
 
 \wxheading{Parameters}
@@ -111,15 +189,95 @@ htmlwin -> SetPage("help/myproject/index.htm");
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 
-FALSE if an error occured, TRUE otherwise
+false if an error occurred, true otherwise
+
+\wxheading{See also}
+
+\helpref{LoadFile}{wxhtmlwindowloadfile}
+
+\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}
 
 
 \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.
 
 
 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}}
 \membersection{wxHtmlWindow::ReadCustomization}\label{wxhtmlwindowreadcustomization}
 
 \func{virtual void}{ReadCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}
@@ -136,13 +294,59 @@ Read values: all things set by SetFonts, SetBorders.
 
 \docparam{path}{Optional path in config tree. If not given current path is used.}
 
 
 \docparam{path}{Optional path in config tree. If not given current path is used.}
 
+\membersection{wxHtmlWindow::SelectAll}\label{wxhtmlwindowselectall}
+
+\func{void}{SelectAll}{\void}
+
+Selects all text in the window.
+
+\wxheading{See also}
+
+\helpref{SelectLine}{wxhtmlwindowselectline},
+\helpref{SelectWord}{wxhtmlwindowselectword}
+
+\membersection{wxHtmlWindow::SelectionToText}\label{wxhtmlwindowselectiontotext}
+
+\func{wxString}{SelectionToText}{\void}
+
+Returns current selection as plain text. Returns empty string if no text
+is currently selected.
+
+\membersection{wxHtmlWindow::SelectLine}\label{wxhtmlwindowselectline}
+
+\func{void}{SelectLine}{\param{const wxPoint\& }{pos}}
+
+Selects the line of text that \arg{pos} points at. Note that \arg{pos}
+is relative to the top of displayed page, not to window's origin, use
+\helpref{CalcUnscrolledPosition}{wxscrolledwindowcalcunscrolledposition}
+to convert physical coordinate.
+
+\wxheading{See also}
+
+\helpref{SelectAll}{wxhtmlwindowselectall},
+\helpref{SelectWord}{wxhtmlwindowselectword}
+
+\membersection{wxHtmlWindow::SelectWord}\label{wxhtmlwindowselectword}
+
+\func{void}{SelectWord}{\param{const wxPoint\& }{pos}}
+
+Selects the word at position \arg{pos}. Note that \arg{pos}
+is relative to the top of displayed page, not to window's origin, use
+\helpref{CalcUnscrolledPosition}{wxscrolledwindowcalcunscrolledposition}
+to convert physical coordinate.
+
+\wxheading{See also}
+
+\helpref{SelectAll}{wxhtmlwindowselectall},
+\helpref{SelectLine}{wxhtmlwindowselectline}
+
 \membersection{wxHtmlWindow::SetBorders}\label{wxhtmlwindowsetborders}
 
 \func{void}{SetBorders}{\param{int }{b}}
 
 This function sets the space between border of window and HTML contents. See image:
 
 \membersection{wxHtmlWindow::SetBorders}\label{wxhtmlwindowsetborders}
 
 \func{void}{SetBorders}{\param{int }{b}}
 
 This function sets the space between border of window and HTML contents. See image:
 
-\image{}{border.bmp}
+\helponly{\image{}{border.bmp}}
 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 
@@ -150,47 +354,29 @@ This function sets the space between border of window and HTML contents. See ima
 
 \membersection{wxHtmlWindow::SetFonts}\label{wxhtmlwindowsetfonts}
 
 
 \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 = NULL}}
 
 This function sets font sizes and faces.
 
 \wxheading{Parameters}
 
 \docparam{normal\_face}{This is face name for normal (i.e. non-fixed) font. 
 
 This function sets font sizes and faces.
 
 \wxheading{Parameters}
 
 \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
+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.}
 
 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\_face}{The same thing for fixed face ( <TT>..</TT> )}
 
-\docparam{fixed\_italic\_mode}{The same thing for fixed face.}
-
 \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
 \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
-( <FONT SIZE=-2> to <FONT SIZE=+4> )}
+( <FONT SIZE=-2> to <FONT SIZE=+4> ). Default sizes are used if {\it sizes}
+is NULL.}
 
 \wxheading{Defaults}
 
 
 \wxheading{Defaults}
 
-Under wxGTK:
-
-\begin{verbatim}
-    SetFonts("", wxSLANT, "", wxSLANT, {10, 12, 14, 16, 19, 24, 32});
-\end{verbatim}
-
-Under Windows:
-
-\begin{verbatim}
-    SetFonts("", wxSLANT, "", wxSLANT, {7, 8, 10, 12, 16, 22, 30});
-\end{verbatim}
-
-Athough it seems different the fact is that the fonts are of approximately
-same size under both platforms (due to wxMSW / wxGTK inconsistency)
+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.
 
 \membersection{wxHtmlWindow::SetPage}\label{wxhtmlwindowsetpage}
 
 
 \membersection{wxHtmlWindow::SetPage}\label{wxhtmlwindowsetpage}
 
@@ -212,7 +398,7 @@ If you want to load a document from some location use
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 
-FALSE if an error occured, TRUE otherwise.
+false if an error occurred, true otherwise.
 
 \membersection{wxHtmlWindow::SetRelatedFrame}\label{wxhtmlwindowsetrelatedframe}
 
 
 \membersection{wxHtmlWindow::SetRelatedFrame}\label{wxhtmlwindowsetrelatedframe}
 
@@ -234,6 +420,12 @@ this sets statusbar slot where messages will be displayed.
 
 \docparam{bar}{statusbar slot number (0..n)}
 
 
 \docparam{bar}{statusbar slot number (0..n)}
 
+\membersection{wxHtmlWindow::ToText}\label{wxhtmlwindowtotext}
+
+\func{wxString}{ToText}{\void}
+
+Returns content of currently displayed page as plain text.
+
 \membersection{wxHtmlWindow::WriteCustomization}\label{wxhtmlwindowwritecustomization}
 
 \func{virtual void}{WriteCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}
 \membersection{wxHtmlWindow::WriteCustomization}\label{wxhtmlwindowwritecustomization}
 
 \func{virtual void}{WriteCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}