docs/latex/wx/htwindow.tex

   1 %
   2 % automatically generated by HelpGen from
   3 % htmlwindow.tex at 14/Mar/99 20:13:37
   4 %
   5
   6 \section{\class{wxHtmlWindow}}\label{wxhtmlwindow}
   7
   8 wxHtmlWindow is probably the only class you will directly use
   9 unless you want to do something special (like adding new tag
  10 handlers or MIME filters).
  11
  12 The purpose of this class is to display HTML pages (either local
  13 file or downloaded via HTTP protocol) in a window. The width
  14 of the window is constant - given in the constructor - and virtual height
  15 is changed dynamically depending on page size.
  16 Once the window is created you can set its content by calling
  17 \helpref{SetPage(text)}{wxhtmlwindowsetpage},
  18 \helpref{LoadPage(filename)}{wxhtmlwindowloadpage} or
  19 \helpref{LoadFile}{wxhtmlwindowloadfile}.
  20
  21 \wxheading{Note}
  22
  23 wxHtmlWindow uses the \helpref{wxImage}{wximage} class for displaying images.
  24 Don't forget to initialize all image formats you need before loading any page!
  25 (See \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers} and
  26 \helpref{wxImage::AddHandler}{wximageaddhandler}.)
  27
  28 \wxheading{Derived from}
  29
  30 \helpref{wxScrolledWindow}{wxscrolledwindow}
  31
  32 \wxheading{Include files}
  33
  34 <wx/html/htmlwin.h>
  35
  36 \membersection{wxHtmlWindow::wxHtmlWindow}\label{wxhtmlwindowwxhtmlwindow}
  37
  38 \func{}{wxHtmlWindow}{\void}
  39
  40 Default constructor.
  41
  42 \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"}}
  43
  44 Constructor. The parameters are the same as for the \helpref{wxScrolledWindow}{wxscrolledwindow} constructor.
  45
  46 \wxheading{Parameters}
  47
  48 \docparam{style}{wxHW\_SCROLLBAR\_NEVER,  or wxHW\_SCROLLBAR\_AUTO.
  49 Affects the appearance of vertical scrollbar in the window.}
  50
  51 \membersection{wxHtmlWindow::AddFilter}\label{wxhtmlwindowaddfilter}
  52
  53 \func{static void}{AddFilter}{\param{wxHtmlFilter }{*filter}}
  54
  55 Adds \helpref{input filter}{filters} to the static list of available
  56 filters. These filters are present by default:
  57
  58 \begin{itemize}\itemsep=0pt
  59 \item {\tt text/html} MIME type
  60 \item {\tt image/*} MIME types
  61 \item Plain Text filter (this filter is used if no other filter matches)
  62 \end{itemize}
  63
  64 \membersection{wxHtmlWindow::AppendToPage}\label{wxhtmlwindowappendtopage}
  65
  66 \func{bool}{AppendToPage}{\param{const wxString\& }{source}}
  67
  68 Appends HTML fragment to currently displayed text and refreshes the window.
  69
  70 \wxheading{Parameters}
  71
  72 \docparam{source}{HTML code fragment}
  73
  74 \wxheading{Return value}
  75
  76 false if an error occurred, true otherwise.
  77
  78 \membersection{wxHtmlWindow::GetInternalRepresentation}\label{wxhtmlwindowgetinternalrepresentation}
  79
  80 \constfunc{wxHtmlContainerCell*}{GetInternalRepresentation}{\void}
  81
  82 Returns pointer to the top-level container.
  83
  84 See also: \helpref{Cells Overview}{cells},
  85 \helpref{Printing Overview}{printing}
  86
  87 \membersection{wxHtmlWindow::GetOpenedAnchor}\label{wxhtmlwindowgetopenedanchor}
  88
  89 \func{wxString}{GetOpenedAnchor}{\void}
  90
  91 Returns anchor within currently opened page
  92 (see \helpref{GetOpenedPage}{wxhtmlwindowgetopenedpage}).
  93 If no page is opened or if the displayed page wasn't
  94 produced by call to LoadPage, empty string is returned.
  95
  96
  97 \membersection{wxHtmlWindow::GetOpenedPage}\label{wxhtmlwindowgetopenedpage}
  98
  99 \func{wxString}{GetOpenedPage}{\void}
 100
 101 Returns full location of the opened page. If no page is opened or if the displayed page wasn't
 102 produced by call to LoadPage, empty string is returned.
 103
 104 \membersection{wxHtmlWindow::GetOpenedPageTitle}\label{wxhtmlwindowgetopenedpagetitle}
 105
 106 \func{wxString}{GetOpenedPageTitle}{\void}
 107
 108 Returns title of the opened page or wxEmptyString if current page does not contain {\tt <TITLE>} tag.
 109
 110 \membersection{wxHtmlWindow::GetRelatedFrame}\label{wxhtmlwindowgetrelatedframe}
 111
 112 \constfunc{wxFrame*}{GetRelatedFrame}{\void}
 113
 114 Returns the related frame.
 115
 116 \membersection{wxHtmlWindow::HistoryBack}\label{wxhtmlwindowhistoryback}
 117
 118 \func{bool}{HistoryBack}{\void}
 119
 120 Moves back to the previous page. (each page displayed using
 121 \helpref{LoadPage}{wxhtmlwindowloadpage} is stored in history list.)
 122
 123 \membersection{wxHtmlWindow::HistoryCanBack}\label{wxhtmlwindowhistorycanback}
 124
 125 \func{bool}{HistoryCanBack}{\void}
 126
 127 Returns true if it is possible to go back in the history (i.e. HistoryBack()
 128 won't fail).
 129
 130 \membersection{wxHtmlWindow::HistoryCanForward}\label{wxhtmlwindowhistorycanforward}
 131
 132 \func{bool}{HistoryCanForward}{\void}
 133
 134 Returns true if it is possible to go forward in the history (i.e. HistoryBack()
 135 won't fail).
 136
 137
 138 \membersection{wxHtmlWindow::HistoryClear}\label{wxhtmlwindowhistoryclear}
 139
 140 \func{void}{HistoryClear}{\void}
 141
 142 Clears history.
 143
 144 \membersection{wxHtmlWindow::HistoryForward}\label{wxhtmlwindowhistoryforward}
 145
 146 \func{bool}{HistoryForward}{\void}
 147
 148 Moves to next page in history.
 149
 150 \membersection{wxHtmlWindow::LoadFile}\label{wxhtmlwindowloadfile}
 151
 152 \func{virtual bool}{LoadFile}{\param{const wxFileName\& }{filename}}
 153
 154 Loads HTML page from file and displays it.
 155
 156 \wxheading{Return value}
 157
 158 false if an error occurred, true otherwise
 159
 160 \wxheading{See also}
 161
 162 \helpref{LoadPage}{wxhtmlwindowloadpage}
 163
 164 \membersection{wxHtmlWindow::LoadPage}\label{wxhtmlwindowloadpage}
 165
 166 \func{virtual bool}{LoadPage}{\param{const wxString\& }{location}}
 167
 168 Unlike SetPage this function first loads HTML page from {\it location}
 169 and then displays it. See example:
 170
 171 \begin{verbatim}
 172 htmlwin->LoadPage("help/myproject/index.htm");
 173 \end{verbatim}
 174
 175 \wxheading{Parameters}
 176
 177 \docparam{location}{The address of document. See \helpref{wxFileSystem}{wxfilesystem} for details on address format and behaviour of "opener".}
 178
 179 \wxheading{Return value}
 180
 181 false if an error occurred, true otherwise
 182
 183 \wxheading{See also}
 184
 185 \helpref{LoadFile}{wxhtmlwindowloadfile}
 186
 187 \membersection{wxHtmlWindow::OnCellClicked}\label{wxhtmlwindowoncellclicked}
 188
 189 \func{virtual void}{OnCellClicked}{\param{wxHtmlCell }{*cell}, \param{wxCoord }{x}, \param{wxCoord }{y}, \param{const wxMouseEvent\& }{event}}
 190
 191 This method is called when a mouse button is clicked inside wxHtmlWindow.
 192 The default behaviour is to call
 193 \helpref{OnLinkClicked}{wxhtmlwindowonlinkclicked} if the cell contains a
 194 hypertext link.
 195
 196 \wxheading{Parameters}
 197
 198 \docparam{cell}{The cell inside which the mouse was clicked, always a simple
 199 (i.e. non container) cell}
 200
 201 \docparam{x, y}{The logical coordinates of the click point}
 202
 203 \docparam{event}{The mouse event containing other information about the click}
 204
 205 \membersection{wxHtmlWindow::OnCellMouseHover}\label{wxhtmlwindowoncellmousehover}
 206
 207 \func{virtual void}{OnCellMouseHover}{\param{wxHtmlCell }{*cell}, \param{wxCoord }{x}, \param{wxCoord }{y}}
 208
 209 This method is called when a mouse moves over an HTML cell.
 210
 211 \wxheading{Parameters}
 212
 213 \docparam{cell}{The cell inside which the mouse is currently, always a simple
 214 (i.e. non container) cell}
 215
 216 \docparam{x, y}{The logical coordinates of the click point}
 217
 218 \membersection{wxHtmlWindow::OnLinkClicked}\label{wxhtmlwindowonlinkclicked}
 219
 220 \func{virtual void}{OnLinkClicked}{\param{const wxHtmlLinkInfo\& }{link}}
 221
 222 Called when user clicks on hypertext link. Default behaviour is to call
 223 \helpref{LoadPage}{wxhtmlwindowloadpage} and do nothing else.
 224
 225 Also see \helpref{wxHtmlLinkInfo}{wxhtmllinkinfo}.
 226
 227 \membersection{wxHtmlWindow::OnOpeningURL}\label{wxhtmlwindowonopeningurl}
 228
 229 \func{virtual wxHtmlOpeningStatus}{OnOpeningURL}{\param{wxHtmlURLType }{type},\param{const wxString\& }{url}, \param{wxString *}{redirect}}
 230
 231 Called when an URL is being opened (either when the user clicks on a link or
 232 an image is loaded). The URL will be opened only if OnOpeningURL returns
 233 {\tt wxHTML\_OPEN}. This method is called by
 234 \helpref{wxHtmlParser::OpenURL}{wxhtmlparseropenurl}.
 235 You can override OnOpeningURL to selectively block some
 236 URLs (e.g. for security reasons) or to redirect them elsewhere. Default
 237 behaviour is to always return {\tt wxHTML\_OPEN}.
 238
 239 \wxheading{Parameters}
 240
 241 \docparam{type}{Indicates type of the resource. Is one of
 242 \begin{twocollist}\itemsep=0pt
 243 \twocolitem{{\bf wxHTML\_URL\_PAGE}}{Opening a HTML page.}
 244 \twocolitem{{\bf wxHTML\_URL\_IMAGE}}{Opening an image.}
 245 \twocolitem{{\bf wxHTML\_URL\_OTHER}}{Opening a resource that doesn't fall into
 246 any other category.}
 247 \end{twocollist}}
 248
 249 \docparam{url}{URL being opened.}
 250
 251 \docparam{redirect}{Pointer to wxString variable that must be filled with an
 252 URL if OnOpeningURL returns {\tt wxHTML\_REDIRECT}.}
 253
 254 \wxheading{Return value}
 255 \begin{twocollist}\itemsep=0pt
 256 \twocolitem{{\bf wxHTML\_OPEN}}{Open the URL.}
 257 \twocolitem{{\bf wxHTML\_BLOCK}}{Deny access to the URL, \helpref{wxHtmlParser::OpenURL}{wxhtmlparseropenurl} will return NULL.}
 258 \twocolitem{{\bf wxHTML\_REDIRECT}}{Don't open {\it url}, redirect to another
 259 URL. OnOpeningURL must fill {\it *redirect} with the new URL. OnOpeningURL will
 260 be called again on returned URL.}
 261 \end{twocollist}
 262
 263 \membersection{wxHtmlWindow::OnSetTitle}\label{wxhtmlwindowonsettitle}
 264
 265 \func{virtual void}{OnSetTitle}{\param{const wxString\& }{title}}
 266
 267 Called on parsing {\tt <TITLE>} tag.
 268
 269
 270 \membersection{wxHtmlWindow::ReadCustomization}\label{wxhtmlwindowreadcustomization}
 271
 272 \func{virtual void}{ReadCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}
 273
 274 This reads custom settings from wxConfig. It uses the path 'path'
 275 if given, otherwise it saves info into currently selected path.
 276 The values are stored in sub-path {\tt wxHtmlWindow}
 277
 278 Read values: all things set by SetFonts, SetBorders.
 279
 280 \wxheading{Parameters}
 281
 282 \docparam{cfg}{wxConfig from which you want to read the configuration.}
 283
 284 \docparam{path}{Optional path in config tree. If not given current path is used.}
 285
 286 \membersection{wxHtmlWindow::SetBorders}\label{wxhtmlwindowsetborders}
 287
 288 \func{void}{SetBorders}{\param{int }{b}}
 289
 290 This function sets the space between border of window and HTML contents. See image:
 291
 292 \helponly{\image{}{border.bmp}}
 293
 294 \wxheading{Parameters}
 295
 296 \docparam{b}{indentation from borders in pixels}
 297
 298 \membersection{wxHtmlWindow::SetFonts}\label{wxhtmlwindowsetfonts}
 299
 300 \func{void}{SetFonts}{\param{wxString }{normal\_face}, \param{wxString }{fixed\_face}, \param{const int }{*sizes}}
 301
 302 This function sets font sizes and faces.
 303
 304 \wxheading{Parameters}
 305
 306 \docparam{normal\_face}{This is face name for normal (i.e. non-fixed) font.
 307 It can be either empty string (then the default face is chosen) or
 308 platform-specific face name. Examples are "helvetica" under Unix or
 309 "Times New Roman" under Windows.}
 310
 311 \docparam{fixed\_face}{The same thing for fixed face ( <TT>..</TT> )}
 312
 313 \docparam{sizes}{This is an array of 7 items of {\it int} type.
 314 The values represent size of font with HTML size from -2 to +4
 315 ( <FONT SIZE=-2> to <FONT SIZE=+4> )}
 316
 317 \wxheading{Defaults}
 318
 319 Under wxGTK:
 320
 321 \begin{verbatim}
 322     SetFonts("", "", {10, 12, 14, 16, 19, 24, 32});
 323 \end{verbatim}
 324
 325 Under Windows:
 326
 327 \begin{verbatim}
 328     SetFonts("", "", {7, 8, 10, 12, 16, 22, 30});
 329 \end{verbatim}
 330
 331 Although it seems different the fact is that the fonts are of approximately
 332 same size under both platforms (due to wxMSW / wxGTK inconsistency)
 333
 334 \membersection{wxHtmlWindow::SetPage}\label{wxhtmlwindowsetpage}
 335
 336 \func{bool}{SetPage}{\param{const wxString\& }{source}}
 337
 338 Sets HTML page and display it. This won't {\bf load} the page!!
 339 It will display the {\it source}. See example:
 340
 341 \begin{verbatim}
 342 htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
 343 \end{verbatim}
 344
 345 If you want to load a document from some location use
 346 \helpref{LoadPage}{wxhtmlwindowloadpage} instead.
 347
 348 \wxheading{Parameters}
 349
 350 \docparam{source}{The HTML document source to be displayed.}
 351
 352 \wxheading{Return value}
 353
 354 false if an error occurred, true otherwise.
 355
 356 \membersection{wxHtmlWindow::SetRelatedFrame}\label{wxhtmlwindowsetrelatedframe}
 357
 358 \func{void}{SetRelatedFrame}{\param{wxFrame* }{frame}, \param{const wxString\& }{format}}
 359
 360 Sets the frame in which page title will be displayed. {\it format} is format of
 361 frame title, e.g. "HtmlHelp : \%s". It must contain exactly one \%s. This
 362 \%s is substituted with HTML page title.
 363
 364 \membersection{wxHtmlWindow::SetRelatedStatusBar}\label{wxhtmlwindowsetrelatedstatusbar}
 365
 366 \func{void}{SetRelatedStatusBar}{\param{int }{bar}}
 367
 368 {\bf After} calling \helpref{SetRelatedFrame}{wxhtmlwindowsetrelatedframe},
 369 this sets statusbar slot where messages will be displayed.
 370 (Default is -1 = no messages.)
 371
 372 \wxheading{Parameters}
 373
 374 \docparam{bar}{statusbar slot number (0..n)}
 375
 376
 377 \membersection{wxHtmlWindow::WriteCustomization}\label{wxhtmlwindowwritecustomization}
 378
 379 \func{virtual void}{WriteCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}
 380
 381 Saves custom settings into wxConfig. It uses the path 'path'
 382 if given, otherwise it saves info into currently selected path.
 383 Regardless of whether the path is given or not, the function creates sub-path
 384 {\tt wxHtmlWindow}.
 385
 386 Saved values: all things set by SetFonts, SetBorders.
 387
 388 \wxheading{Parameters}
 389
 390 \docparam{cfg}{wxConfig to which you want to save the configuration.}
 391
 392 \docparam{path}{Optional path in config tree. If not given, the current path is used.}
 393