X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8eb2940f7f226b068007928465096e2b9bec67d0..85136e3bf5dadf921652519e71da5db351fb3194:/docs/latex/wx/htwindow.tex diff --git a/docs/latex/wx/htwindow.tex b/docs/latex/wx/htwindow.tex index bbca02309e..75df9734af 100644 --- a/docs/latex/wx/htwindow.tex +++ b/docs/latex/wx/htwindow.tex @@ -13,17 +13,67 @@ 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}. +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} -wxScrolledWindow +\helpref{wxScrolledWindow}{wxscrolledwindow}\\ +\helpref{wxPanel}{wxpanel}\\ +\helpref{wxWindow}{wxwindow}\\ +\helpref{wxEvtHandler}{wxevthandler}\\ +\helpref{wxObject}{wxobject} \wxheading{Include files} - + + +\wxheading{Library} + +\helpref{wxHtml}{librarieslist} + +\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} + + +\wxheading{Event handling} + +To process input from a wxHtmlWindow, use these event handler macros to direct input to member +functions that take a \helpref{wxHtmlCellEvent}{wxhtmlcellevent} argument or a \helpref{wxHtmlLinkEvent}{wxhtmllinkevent}. + +\twocolwidtha{7cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf EVT\_HTML\_CELL\_CLICKED(id, func)}}{A \helpref{wxHtmlCell}{wxhtmlcell} was clicked.} +\twocolitem{{\bf EVT\_HTML\_CELL\_HOVER(id, func)}}{The mouse passed over a \helpref{wxHtmlCell}{wxhtmlcell}.} +\twocolitem{{\bf EVT\_HTML\_LINK\_CLICKED(id, func)}}{A \helpref{wxHtmlCell}{wxhtmlcell} which contains an hyperlink was clicked.} +\end{twocollist} + + +\wxheading{See also} + +\helpref{wxHtmlLinkEvent}{wxhtmllinkevent}, \helpref{wxHtmlCellEvent}{wxhtmlcellevent} + + + +\latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxHtmlWindow::wxHtmlWindow}\label{wxhtmlwindowwxhtmlwindow} @@ -31,14 +81,13 @@ 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\_DEFAULT\_STYLE}, \param{const wxString\& }{name = "htmlWindow"}} 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} @@ -53,6 +102,20 @@ filters. These filters are present by default: \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} @@ -62,6 +125,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} @@ -88,6 +161,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} @@ -100,15 +188,29 @@ Clears 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} -\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} -htmlwin -> SetPage("help/myproject/index.htm"); +htmlwin->LoadPage("help/myproject/index.htm"); \end{verbatim} \wxheading{Parameters} @@ -117,15 +219,100 @@ htmlwin -> SetPage("help/myproject/index.htm"); \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 bool}{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 emit a \helpref{wxHtmlCellEvent}{wxhtmlcellevent} +and, if the event was not processed or skipped, call +\helpref{OnLinkClicked}{wxhtmlwindowonlinkclicked} if the cell contains an +hypertext link. + +Overloading this method is deprecated; intercept the event instead. + + +\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} + +\wxheading{Return value} + +\true if a link was clicked, \false otherwise. + +\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. +Default behaviour is to emit a \helpref{wxHtmlCellEvent}{wxhtmlcellevent}. +Overloading this method is deprecated; intercept the event instead. + +\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 emit a +\helpref{wxHtmlLinkEvent}{wxhtmllinkevent} and, if the event was not processed +or skipped, call \helpref{LoadPage}{wxhtmlwindowloadpage} and do nothing else. +Overloading this method is deprecated; intercept the event instead. -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} @@ -150,13 +337,59 @@ Read values: all things set by SetFonts, SetBorders. \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: -\image{}{border.bmp} +\helponly{\image{}{border.bmp}} \wxheading{Parameters} @@ -164,14 +397,14 @@ 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{wxString }{fixed\_face}, \param{const int }{*sizes}} +\func{void}{SetFonts}{\param{const wxString\& }{normal\_face}, \param{const 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. -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.} @@ -179,24 +412,14 @@ platform-specific face name. Examples are "helvetica" under Unix or \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 -( to )} +( to ). Default sizes are used if {\it sizes} +is NULL.} \wxheading{Defaults} -Under wxGTK: - -\begin{verbatim} - SetFonts("", "", {10, 12, 14, 16, 19, 24, 32}); -\end{verbatim} - -Under Windows: - -\begin{verbatim} - SetFonts("", "", {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} @@ -218,7 +441,7 @@ If you want to load a 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} @@ -240,6 +463,11 @@ this sets statusbar slot where messages will be displayed. \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} @@ -258,3 +486,127 @@ Saved values: all things set by SetFonts, SetBorders. \docparam{path}{Optional path in config tree. If not given, the current path is used.} + + + + + + +\section{\class{wxHtmlLinkEvent}}\label{wxhtmllinkevent} + +This event class is used for the events generated by \helpref{wxHtmlWindow}{wxhtmlwindow}. + +\wxheading{Derived from} + +\helpref{wxCommandEvent}{wxcommandevent}\\ +\helpref{wxEvent}{wxevent}\\ +\helpref{wxObject}{wxobject} + +\wxheading{Include files} + + + +\wxheading{Library} + +\helpref{wxHtml}{librarieslist} + +\wxheading{Event handling} + +To process input from a wxHtmlLinkEvent, use one of these event handler macros to +direct input to member function that take a \helpref{wxHtmlLinkEvent}{wxhtmllinkevent} argument: + +\twocolwidtha{7cm} +\begin{twocollist} +\twocolitem{{\bf EVT\_HTML\_LINK\_CLICKED(id, func)}}{User clicked on an hyperlink.} +\end{twocollist} + + +\latexignore{\rtfignore{\wxheading{Members}}} + +\membersection{wxHtmlLinkEvent::wxHtmlLinkEvent}\label{wxhtmllinkeventctor} + +\func{}{wxHyperlinkEvent}{\param{int}{ id}, \param{const wxHtmlLinkInfo \&}{ linkinfo}} + +The constructor is not normally used by the user code. + + +\membersection{wxHtmlLinkEvent::GetLinkInfo}\label{wxhtmllinkeventgetlinkinfo} + +\constfunc{const wxHtmlLinkInfo &}{GetLinkInfo}{\void} + +Returns the \helpref{wxHtmlLinkInfo}{wxhtmllinkinfo} which contains info about the cell clicked and the hyperlink it contains. + + + + + + +\section{\class{wxHtmlCellEvent}}\label{wxhtmlcellevent} + +This event class is used for the events generated by \helpref{wxHtmlWindow}{wxhtmlwindow}. + +\wxheading{Derived from} + +\helpref{wxCommandEvent}{wxcommandevent}\\ +\helpref{wxEvent}{wxevent}\\ +\helpref{wxObject}{wxobject} + +\wxheading{Include files} + + + +\wxheading{Library} + +\helpref{wxHtml}{librarieslist} + +\wxheading{Event handling} + +To process input from a wxHtmlCellEvent, use one of these event handler macros to +direct input to member function that take a \helpref{wxHtmlCellEvent}{wxhtmlcellevent} argument: + +\twocolwidtha{7cm} +\begin{twocollist} +\twocolitem{{\bf EVT\_HTML\_CELL\_HOVER(id, func)}}{User moved the mouse over a \helpref{wxHtmlCell}{wxhtmlcell}.} +\twocolitem{{\bf EVT\_HTML\_CELL\_CLICKED(id, func)}}{User clicked on a \helpref{wxHtmlCell}{wxhtmlcell}. When handling this event, remember to use \helpref{wxHtmlCell::SetLinkClicked(true)}{wxhtmlcelleventsetlinkclicked} if the cell contains a link.} +\end{twocollist} + + +\latexignore{\rtfignore{\wxheading{Members}}} + +\membersection{wxHtmlCellEvent::wxHtmlCellEvent}\label{wxhtmlcelleventctor} + +\func{}{wxHtmlCellEvent}{\param{wxEventType}{ commandType}, \param{int}{ id}, \param{wxHtmlCell *}{ cell}, \param{const wxPoint \&}{ point}} + +The constructor is not normally used by the user code. + + +\membersection{wxHtmlCellEvent::GetCell}\label{wxhtmlcelleventgetcell} + +\constfunc{wxHtmlCell *}{GetCell}{\void} + +Returns the \helpref{wxHtmlCellEvent}{wxhtmlcellevent} associated with the event. + + +\membersection{wxHtmlCellEvent::GetPoint}\label{wxhtmlcelleventgetpoint} + +\constfunc{wxPoint}{GetPoint}{\void} + +Returns the \helpref{wxPoint}{wxpoint} associated with the event. + + +\membersection{wxHtmlCellEvent::SetLinkClicked}\label{wxhtmlcelleventsetlinkclicked} + +\func{bool}{SetLinkClicked}{\param{bool}{ linkclicked}} + +Call this function with {\tt linkclicked} set to \true if the cell which has been clicked contained a link or +\false otherwise (which is the default). With this function the event handler can return info to the +wxHtmlWindow which sent the event. + + +\membersection{wxHtmlCellEvent::GetLinkClicked}\label{wxhtmlcelleventgetlinkclicked} + +\constfunc{bool}{GetLinkClicked}{\void} + +Returns \true if \helpref{SetLinkClicked(true)}{wxhtmlcelleventsetlinkclicked} has previously been called; +\false otherwise. +