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 \wxheading{Window styles}
  37
  38 \twocolwidtha{5cm}
  39 \begin{twocollist}\itemsep=0pt
  40 \twocolitem{\windowstyle{wxHW\_SCROLLBAR\_NEVER}}{Never display scrollbars, not
  41 even when the page is larger than the window.}
  42 \twocolitem{\windowstyle{wxHW\_SCROLLBAR\_AUTO}}{Display scrollbars only if
  43 page's size exceeds window's size.}
  44 \twocolitem{\windowstyle{wxHW\_NO\_SELECTION}}{Don't allow the user to select
  45 text.}
  46 \end{twocollist}
  47
  48 \membersection{wxHtmlWindow::wxHtmlWindow}\label{wxhtmlwindowwxhtmlwindow}
  49
  50 \func{}{wxHtmlWindow}{\void}
  51
  52 Default constructor.
  53
  54 \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"}}
  55
  56 Constructor. The parameters are the same as for the \helpref{wxScrolledWindow}{wxscrolledwindow} constructor.
  57
  58 \wxheading{Parameters}
  59
  60 \docparam{style}{Window style. See \helpref{wxHtmlWindow}{wxhtmlwindow}.}
  61
  62 \membersection{wxHtmlWindow::AddFilter}\label{wxhtmlwindowaddfilter}
  63
  64 \func{static void}{AddFilter}{\param{wxHtmlFilter }{*filter}}
  65
  66 Adds \helpref{input filter}{filters} to the static list of available
  67 filters. These filters are present by default:
  68
  69 \begin{itemize}\itemsep=0pt
  70 \item {\tt text/html} MIME type
  71 \item {\tt image/*} MIME types
  72 \item Plain Text filter (this filter is used if no other filter matches)
  73 \end{itemize}
  74
  75 \membersection{wxHtmlWindow::AppendToPage}\label{wxhtmlwindowappendtopage}
  76
  77 \func{bool}{AppendToPage}{\param{const wxString\& }{source}}
  78
  79 Appends HTML fragment to currently displayed text and refreshes the window.
  80
  81 \wxheading{Parameters}
  82
  83 \docparam{source}{HTML code fragment}
  84
  85 \wxheading{Return value}
  86
  87 false if an error occurred, true otherwise.
  88
  89 \membersection{wxHtmlWindow::GetInternalRepresentation}\label{wxhtmlwindowgetinternalrepresentation}
  90
  91 \constfunc{wxHtmlContainerCell*}{GetInternalRepresentation}{\void}
  92
  93 Returns pointer to the top-level container.
  94
  95 See also: \helpref{Cells Overview}{cells},
  96 \helpref{Printing Overview}{printing}
  97
  98 \membersection{wxHtmlWindow::GetOpenedAnchor}\label{wxhtmlwindowgetopenedanchor}
  99
 100 \func{wxString}{GetOpenedAnchor}{\void}
 101
 102 Returns anchor within currently opened page
 103 (see \helpref{GetOpenedPage}{wxhtmlwindowgetopenedpage}).
 104 If no page is opened or if the displayed page wasn't
 105 produced by call to LoadPage, empty string is returned.
 106
 107
 108 \membersection{wxHtmlWindow::GetOpenedPage}\label{wxhtmlwindowgetopenedpage}
 109
 110 \func{wxString}{GetOpenedPage}{\void}
 111
 112 Returns full location of the opened page. If no page is opened or if the displayed page wasn't
 113 produced by call to LoadPage, empty string is returned.
 114
 115 \membersection{wxHtmlWindow::GetOpenedPageTitle}\label{wxhtmlwindowgetopenedpagetitle}
 116
 117 \func{wxString}{GetOpenedPageTitle}{\void}
 118
 119 Returns title of the opened page or wxEmptyString if current page does not contain {\tt <TITLE>} tag.
 120
 121 \membersection{wxHtmlWindow::GetRelatedFrame}\label{wxhtmlwindowgetrelatedframe}
 122
 123 \constfunc{wxFrame*}{GetRelatedFrame}{\void}
 124
 125 Returns the related frame.
 126
 127 \membersection{wxHtmlWindow::HistoryBack}\label{wxhtmlwindowhistoryback}
 128
 129 \func{bool}{HistoryBack}{\void}
 130
 131 Moves back to the previous page. (each page displayed using
 132 \helpref{LoadPage}{wxhtmlwindowloadpage} is stored in history list.)
 133
 134 \membersection{wxHtmlWindow::HistoryCanBack}\label{wxhtmlwindowhistorycanback}
 135
 136 \func{bool}{HistoryCanBack}{\void}
 137
 138 Returns true if it is possible to go back in the history (i.e. HistoryBack()
 139 won't fail).
 140
 141 \membersection{wxHtmlWindow::HistoryCanForward}\label{wxhtmlwindowhistorycanforward}
 142
 143 \func{bool}{HistoryCanForward}{\void}
 144
 145 Returns true if it is possible to go forward in the history (i.e. HistoryBack()
 146 won't fail).
 147
 148
 149 \membersection{wxHtmlWindow::HistoryClear}\label{wxhtmlwindowhistoryclear}
 150
 151 \func{void}{HistoryClear}{\void}
 152
 153 Clears history.
 154
 155 \membersection{wxHtmlWindow::HistoryForward}\label{wxhtmlwindowhistoryforward}
 156
 157 \func{bool}{HistoryForward}{\void}
 158
 159 Moves to next page in history.
 160
 161 \membersection{wxHtmlWindow::LoadFile}\label{wxhtmlwindowloadfile}
 162
 163 \func{virtual bool}{LoadFile}{\param{const wxFileName\& }{filename}}
 164
 165 Loads HTML page from file and displays it.
 166
 167 \wxheading{Return value}
 168
 169 false if an error occurred, true otherwise
 170
 171 \wxheading{See also}
 172
 173 \helpref{LoadPage}{wxhtmlwindowloadpage}
 174
 175 \membersection{wxHtmlWindow::LoadPage}\label{wxhtmlwindowloadpage}
 176
 177 \func{virtual bool}{LoadPage}{\param{const wxString\& }{location}}
 178
 179 Unlike SetPage this function first loads HTML page from {\it location}
 180 and then displays it. See example:
 181
 182 \begin{verbatim}
 183 htmlwin->LoadPage("help/myproject/index.htm");
 184 \end{verbatim}
 185
 186 \wxheading{Parameters}
 187
 188 \docparam{location}{The address of document. See \helpref{wxFileSystem}{wxfilesystem} for details on address format and behaviour of "opener".}
 189
 190 \wxheading{Return value}
 191
 192 false if an error occurred, true otherwise
 193
 194 \wxheading{See also}
 195
 196 \helpref{LoadFile}{wxhtmlwindowloadfile}
 197
 198 \membersection{wxHtmlWindow::OnCellClicked}\label{wxhtmlwindowoncellclicked}
 199
 200 \func{virtual void}{OnCellClicked}{\param{wxHtmlCell }{*cell}, \param{wxCoord }{x}, \param{wxCoord }{y}, \param{const wxMouseEvent\& }{event}}
 201
 202 This method is called when a mouse button is clicked inside wxHtmlWindow.
 203 The default behaviour is to call
 204 \helpref{OnLinkClicked}{wxhtmlwindowonlinkclicked} if the cell contains a
 205 hypertext link.
 206
 207 \wxheading{Parameters}
 208
 209 \docparam{cell}{The cell inside which the mouse was clicked, always a simple
 210 (i.e. non container) cell}
 211
 212 \docparam{x, y}{The logical coordinates of the click point}
 213
 214 \docparam{event}{The mouse event containing other information about the click}
 215
 216 \membersection{wxHtmlWindow::OnCellMouseHover}\label{wxhtmlwindowoncellmousehover}
 217
 218 \func{virtual void}{OnCellMouseHover}{\param{wxHtmlCell }{*cell}, \param{wxCoord }{x}, \param{wxCoord }{y}}
 219
 220 This method is called when a mouse moves over an HTML cell.
 221
 222 \wxheading{Parameters}
 223
 224 \docparam{cell}{The cell inside which the mouse is currently, always a simple
 225 (i.e. non container) cell}
 226
 227 \docparam{x, y}{The logical coordinates of the click point}
 228
 229 \membersection{wxHtmlWindow::OnLinkClicked}\label{wxhtmlwindowonlinkclicked}
 230
 231 \func{virtual void}{OnLinkClicked}{\param{const wxHtmlLinkInfo\& }{link}}
 232
 233 Called when user clicks on hypertext link. Default behaviour is to call
 234 \helpref{LoadPage}{wxhtmlwindowloadpage} and do nothing else.
 235
 236 Also see \helpref{wxHtmlLinkInfo}{wxhtmllinkinfo}.
 237
 238 \membersection{wxHtmlWindow::OnOpeningURL}\label{wxhtmlwindowonopeningurl}
 239
 240 \func{virtual wxHtmlOpeningStatus}{OnOpeningURL}{\param{wxHtmlURLType }{type},\param{const wxString\& }{url}, \param{wxString *}{redirect}}
 241
 242 Called when an URL is being opened (either when the user clicks on a link or
 243 an image is loaded). The URL will be opened only if OnOpeningURL returns
 244 {\tt wxHTML\_OPEN}. This method is called by
 245 \helpref{wxHtmlParser::OpenURL}{wxhtmlparseropenurl}.
 246 You can override OnOpeningURL to selectively block some
 247 URLs (e.g. for security reasons) or to redirect them elsewhere. Default
 248 behaviour is to always return {\tt wxHTML\_OPEN}.
 249
 250 \wxheading{Parameters}
 251
 252 \docparam{type}{Indicates type of the resource. Is one of
 253 \begin{twocollist}\itemsep=0pt
 254 \twocolitem{{\bf wxHTML\_URL\_PAGE}}{Opening a HTML page.}
 255 \twocolitem{{\bf wxHTML\_URL\_IMAGE}}{Opening an image.}
 256 \twocolitem{{\bf wxHTML\_URL\_OTHER}}{Opening a resource that doesn't fall into
 257 any other category.}
 258 \end{twocollist}}
 259
 260 \docparam{url}{URL being opened.}
 261
 262 \docparam{redirect}{Pointer to wxString variable that must be filled with an
 263 URL if OnOpeningURL returns {\tt wxHTML\_REDIRECT}.}
 264
 265 \wxheading{Return value}
 266 \begin{twocollist}\itemsep=0pt
 267 \twocolitem{{\bf wxHTML\_OPEN}}{Open the URL.}
 268 \twocolitem{{\bf wxHTML\_BLOCK}}{Deny access to the URL, \helpref{wxHtmlParser::OpenURL}{wxhtmlparseropenurl} will return NULL.}
 269 \twocolitem{{\bf wxHTML\_REDIRECT}}{Don't open {\it url}, redirect to another
 270 URL. OnOpeningURL must fill {\it *redirect} with the new URL. OnOpeningURL will
 271 be called again on returned URL.}
 272 \end{twocollist}
 273
 274 \membersection{wxHtmlWindow::OnSetTitle}\label{wxhtmlwindowonsettitle}
 275
 276 \func{virtual void}{OnSetTitle}{\param{const wxString\& }{title}}
 277
 278 Called on parsing {\tt <TITLE>} tag.
 279
 280
 281 \membersection{wxHtmlWindow::ReadCustomization}\label{wxhtmlwindowreadcustomization}
 282
 283 \func{virtual void}{ReadCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}
 284
 285 This reads custom settings from wxConfig. It uses the path 'path'
 286 if given, otherwise it saves info into currently selected path.
 287 The values are stored in sub-path {\tt wxHtmlWindow}
 288
 289 Read values: all things set by SetFonts, SetBorders.
 290
 291 \wxheading{Parameters}
 292
 293 \docparam{cfg}{wxConfig from which you want to read the configuration.}
 294
 295 \docparam{path}{Optional path in config tree. If not given current path is used.}
 296
 297 \membersection{wxHtmlWindow::SelectAll}\label{wxhtmlwindowselectall}
 298
 299 \func{void}{SelectAll}{\void}
 300
 301 Selects all text in the window.
 302
 303 \wxheading{See also}
 304
 305 \helpref{SelectLine}{wxhtmlwindowselectline},
 306 \helpref{SelectWord}{wxhtmlwindowselectword}
 307
 308 \membersection{wxHtmlWindow::SelectionToText}\label{wxhtmlwindowselectiontotext}
 309
 310 \func{wxString}{SelectionToText}{\void}
 311
 312 Returns current selection as plain text. Returns empty string if no text
 313 is currently selected.
 314
 315 \membersection{wxHtmlWindow::SelectLine}\label{wxhtmlwindowselectline}
 316
 317 \func{void}{SelectLine}{\param{const wxPoint\& }{pos}}
 318
 319 Selects the line of text that \arg{pos} points at. Note that \arg{pos}
 320 is relative to the top of displayed page, not to window's origin, use
 321 \helpref{CalcUnscrolledPosition}{wxscrolledwindowcalcunscrolledposition}
 322 to convert physical coordinate.
 323
 324 \wxheading{See also}
 325
 326 \helpref{SelectAll}{wxhtmlwindowselectall},
 327 \helpref{SelectWord}{wxhtmlwindowselectword}
 328
 329 \membersection{wxHtmlWindow::SelectWord}\label{wxhtmlwindowselectword}
 330
 331 \func{void}{SelectWord}{\param{const wxPoint\& }{pos}}
 332
 333 Selects the word at position \arg{pos}. Note that \arg{pos}
 334 is relative to the top of displayed page, not to window's origin, use
 335 \helpref{CalcUnscrolledPosition}{wxscrolledwindowcalcunscrolledposition}
 336 to convert physical coordinate.
 337
 338 \wxheading{See also}
 339
 340 \helpref{SelectAll}{wxhtmlwindowselectall},
 341 \helpref{SelectLine}{wxhtmlwindowselectline}
 342
 343 \membersection{wxHtmlWindow::SetBorders}\label{wxhtmlwindowsetborders}
 344
 345 \func{void}{SetBorders}{\param{int }{b}}
 346
 347 This function sets the space between border of window and HTML contents. See image:
 348
 349 \helponly{\image{}{border.bmp}}
 350
 351 \wxheading{Parameters}
 352
 353 \docparam{b}{indentation from borders in pixels}
 354
 355 \membersection{wxHtmlWindow::SetFonts}\label{wxhtmlwindowsetfonts}
 356
 357 \func{void}{SetFonts}{\param{const wxString\& }{normal\_face}, \param{const wxString\& }{fixed\_face}, \param{const int }{*sizes = NULL}}
 358
 359 This function sets font sizes and faces.
 360
 361 \wxheading{Parameters}
 362
 363 \docparam{normal\_face}{This is face name for normal (i.e. non-fixed) font.
 364 It can be either empty string (then the default face is chosen) or
 365 platform-specific face name. Examples are "helvetica" under Unix or
 366 "Times New Roman" under Windows.}
 367
 368 \docparam{fixed\_face}{The same thing for fixed face ( <TT>..</TT> )}
 369
 370 \docparam{sizes}{This is an array of 7 items of {\it int} type.
 371 The values represent size of font with HTML size from -2 to +4
 372 ( <FONT SIZE=-2> to <FONT SIZE=+4> ). Default sizes are used if {\it sizes}
 373 is NULL.}
 374
 375 \wxheading{Defaults}
 376
 377 Default font sizes are defined by constants wxHTML\_FONT\_SIZE\_1,
 378 wxHTML\_FONT\_SIZE\_2, ..., wxHTML\_FONT\_SIZE\_7. Note that they differ among
 379 platforms. Default face names are empty strings.
 380
 381 \membersection{wxHtmlWindow::SetPage}\label{wxhtmlwindowsetpage}
 382
 383 \func{bool}{SetPage}{\param{const wxString\& }{source}}
 384
 385 Sets HTML page and display it. This won't {\bf load} the page!!
 386 It will display the {\it source}. See example:
 387
 388 \begin{verbatim}
 389 htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
 390 \end{verbatim}
 391
 392 If you want to load a document from some location use
 393 \helpref{LoadPage}{wxhtmlwindowloadpage} instead.
 394
 395 \wxheading{Parameters}
 396
 397 \docparam{source}{The HTML document source to be displayed.}
 398
 399 \wxheading{Return value}
 400
 401 false if an error occurred, true otherwise.
 402
 403 \membersection{wxHtmlWindow::SetRelatedFrame}\label{wxhtmlwindowsetrelatedframe}
 404
 405 \func{void}{SetRelatedFrame}{\param{wxFrame* }{frame}, \param{const wxString\& }{format}}
 406
 407 Sets the frame in which page title will be displayed. {\it format} is format of
 408 frame title, e.g. "HtmlHelp : \%s". It must contain exactly one \%s. This
 409 \%s is substituted with HTML page title.
 410
 411 \membersection{wxHtmlWindow::SetRelatedStatusBar}\label{wxhtmlwindowsetrelatedstatusbar}
 412
 413 \func{void}{SetRelatedStatusBar}{\param{int }{bar}}
 414
 415 {\bf After} calling \helpref{SetRelatedFrame}{wxhtmlwindowsetrelatedframe},
 416 this sets statusbar slot where messages will be displayed.
 417 (Default is -1 = no messages.)
 418
 419 \wxheading{Parameters}
 420
 421 \docparam{bar}{statusbar slot number (0..n)}
 422
 423 \membersection{wxHtmlWindow::ToText}\label{wxhtmlwindowtotext}
 424
 425 \func{wxString}{ToText}{\void}
 426
 427 Returns content of currently displayed page as plain text.
 428
 429 \membersection{wxHtmlWindow::WriteCustomization}\label{wxhtmlwindowwritecustomization}
 430
 431 \func{virtual void}{WriteCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}
 432
 433 Saves custom settings into wxConfig. It uses the path 'path'
 434 if given, otherwise it saves info into currently selected path.
 435 Regardless of whether the path is given or not, the function creates sub-path
 436 {\tt wxHtmlWindow}.
 437
 438 Saved values: all things set by SetFonts, SetBorders.
 439
 440 \wxheading{Parameters}
 441
 442 \docparam{cfg}{wxConfig to which you want to save the configuration.}
 443
 444 \docparam{path}{Optional path in config tree. If not given, the current path is used.}
 445