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 bool}{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 \wxheading{Return value}
 217
 218 \true if a link was clicked, \false otherwise.
 219
 220 \membersection{wxHtmlWindow::OnCellMouseHover}\label{wxhtmlwindowoncellmousehover}
 221
 222 \func{virtual void}{OnCellMouseHover}{\param{wxHtmlCell }{*cell}, \param{wxCoord }{x}, \param{wxCoord }{y}}
 223
 224 This method is called when a mouse moves over an HTML cell.
 225
 226 \wxheading{Parameters}
 227
 228 \docparam{cell}{The cell inside which the mouse is currently, always a simple
 229 (i.e. non-container) cell}
 230
 231 \docparam{x, y}{The logical coordinates of the click point}
 232
 233 \membersection{wxHtmlWindow::OnLinkClicked}\label{wxhtmlwindowonlinkclicked}
 234
 235 \func{virtual void}{OnLinkClicked}{\param{const wxHtmlLinkInfo\& }{link}}
 236
 237 Called when user clicks on hypertext link. Default behaviour is to call
 238 \helpref{LoadPage}{wxhtmlwindowloadpage} and do nothing else.
 239
 240 Also see \helpref{wxHtmlLinkInfo}{wxhtmllinkinfo}.
 241
 242 \membersection{wxHtmlWindow::OnOpeningURL}\label{wxhtmlwindowonopeningurl}
 243
 244 \func{virtual wxHtmlOpeningStatus}{OnOpeningURL}{\param{wxHtmlURLType }{type},\param{const wxString\& }{url}, \param{wxString *}{redirect}}
 245
 246 Called when an URL is being opened (either when the user clicks on a link or
 247 an image is loaded). The URL will be opened only if OnOpeningURL returns
 248 {\tt wxHTML\_OPEN}. This method is called by
 249 \helpref{wxHtmlParser::OpenURL}{wxhtmlparseropenurl}.
 250 You can override OnOpeningURL to selectively block some
 251 URLs (e.g. for security reasons) or to redirect them elsewhere. Default
 252 behaviour is to always return {\tt wxHTML\_OPEN}.
 253
 254 \wxheading{Parameters}
 255
 256 \docparam{type}{Indicates type of the resource. Is one of
 257 \begin{twocollist}\itemsep=0pt
 258 \twocolitem{{\bf wxHTML\_URL\_PAGE}}{Opening a HTML page.}
 259 \twocolitem{{\bf wxHTML\_URL\_IMAGE}}{Opening an image.}
 260 \twocolitem{{\bf wxHTML\_URL\_OTHER}}{Opening a resource that doesn't fall into
 261 any other category.}
 262 \end{twocollist}}
 263
 264 \docparam{url}{URL being opened.}
 265
 266 \docparam{redirect}{Pointer to wxString variable that must be filled with an
 267 URL if OnOpeningURL returns {\tt wxHTML\_REDIRECT}.}
 268
 269 \wxheading{Return value}
 270 \begin{twocollist}\itemsep=0pt
 271 \twocolitem{{\bf wxHTML\_OPEN}}{Open the URL.}
 272 \twocolitem{{\bf wxHTML\_BLOCK}}{Deny access to the URL, \helpref{wxHtmlParser::OpenURL}{wxhtmlparseropenurl} will return NULL.}
 273 \twocolitem{{\bf wxHTML\_REDIRECT}}{Don't open {\it url}, redirect to another
 274 URL. OnOpeningURL must fill {\it *redirect} with the new URL. OnOpeningURL will
 275 be called again on returned URL.}
 276 \end{twocollist}
 277
 278 \membersection{wxHtmlWindow::OnSetTitle}\label{wxhtmlwindowonsettitle}
 279
 280 \func{virtual void}{OnSetTitle}{\param{const wxString\& }{title}}
 281
 282 Called on parsing {\tt <TITLE>} tag.
 283
 284
 285 \membersection{wxHtmlWindow::ReadCustomization}\label{wxhtmlwindowreadcustomization}
 286
 287 \func{virtual void}{ReadCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}
 288
 289 This reads custom settings from wxConfig. It uses the path 'path'
 290 if given, otherwise it saves info into currently selected path.
 291 The values are stored in sub-path {\tt wxHtmlWindow}
 292
 293 Read values: all things set by SetFonts, SetBorders.
 294
 295 \wxheading{Parameters}
 296
 297 \docparam{cfg}{wxConfig from which you want to read the configuration.}
 298
 299 \docparam{path}{Optional path in config tree. If not given current path is used.}
 300
 301 \membersection{wxHtmlWindow::SelectAll}\label{wxhtmlwindowselectall}
 302
 303 \func{void}{SelectAll}{\void}
 304
 305 Selects all text in the window.
 306
 307 \wxheading{See also}
 308
 309 \helpref{SelectLine}{wxhtmlwindowselectline},
 310 \helpref{SelectWord}{wxhtmlwindowselectword}
 311
 312 \membersection{wxHtmlWindow::SelectionToText}\label{wxhtmlwindowselectiontotext}
 313
 314 \func{wxString}{SelectionToText}{\void}
 315
 316 Returns current selection as plain text. Returns empty string if no text
 317 is currently selected.
 318
 319 \membersection{wxHtmlWindow::SelectLine}\label{wxhtmlwindowselectline}
 320
 321 \func{void}{SelectLine}{\param{const wxPoint\& }{pos}}
 322
 323 Selects the line of text that \arg{pos} points at. Note that \arg{pos}
 324 is relative to the top of displayed page, not to window's origin, use
 325 \helpref{CalcUnscrolledPosition}{wxscrolledwindowcalcunscrolledposition}
 326 to convert physical coordinate.
 327
 328 \wxheading{See also}
 329
 330 \helpref{SelectAll}{wxhtmlwindowselectall},
 331 \helpref{SelectWord}{wxhtmlwindowselectword}
 332
 333 \membersection{wxHtmlWindow::SelectWord}\label{wxhtmlwindowselectword}
 334
 335 \func{void}{SelectWord}{\param{const wxPoint\& }{pos}}
 336
 337 Selects the word at position \arg{pos}. Note that \arg{pos}
 338 is relative to the top of displayed page, not to window's origin, use
 339 \helpref{CalcUnscrolledPosition}{wxscrolledwindowcalcunscrolledposition}
 340 to convert physical coordinate.
 341
 342 \wxheading{See also}
 343
 344 \helpref{SelectAll}{wxhtmlwindowselectall},
 345 \helpref{SelectLine}{wxhtmlwindowselectline}
 346
 347 \membersection{wxHtmlWindow::SetBorders}\label{wxhtmlwindowsetborders}
 348
 349 \func{void}{SetBorders}{\param{int }{b}}
 350
 351 This function sets the space between border of window and HTML contents. See image:
 352
 353 \helponly{\image{}{border.bmp}}
 354
 355 \wxheading{Parameters}
 356
 357 \docparam{b}{indentation from borders in pixels}
 358
 359 \membersection{wxHtmlWindow::SetFonts}\label{wxhtmlwindowsetfonts}
 360
 361 \func{void}{SetFonts}{\param{const wxString\& }{normal\_face}, \param{const wxString\& }{fixed\_face}, \param{const int }{*sizes = NULL}}
 362
 363 This function sets font sizes and faces.
 364
 365 \wxheading{Parameters}
 366
 367 \docparam{normal\_face}{This is face name for normal (i.e. non-fixed) font.
 368 It can be either empty string (then the default face is chosen) or
 369 platform-specific face name. Examples are "helvetica" under Unix or
 370 "Times New Roman" under Windows.}
 371
 372 \docparam{fixed\_face}{The same thing for fixed face ( <TT>..</TT> )}
 373
 374 \docparam{sizes}{This is an array of 7 items of {\it int} type.
 375 The values represent size of font with HTML size from -2 to +4
 376 ( <FONT SIZE=-2> to <FONT SIZE=+4> ). Default sizes are used if {\it sizes}
 377 is NULL.}
 378
 379 \wxheading{Defaults}
 380
 381 Default font sizes are defined by constants wxHTML\_FONT\_SIZE\_1,
 382 wxHTML\_FONT\_SIZE\_2, ..., wxHTML\_FONT\_SIZE\_7. Note that they differ among
 383 platforms. Default face names are empty strings.
 384
 385 \membersection{wxHtmlWindow::SetPage}\label{wxhtmlwindowsetpage}
 386
 387 \func{bool}{SetPage}{\param{const wxString\& }{source}}
 388
 389 Sets HTML page and display it. This won't {\bf load} the page!!
 390 It will display the {\it source}. See example:
 391
 392 \begin{verbatim}
 393 htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
 394 \end{verbatim}
 395
 396 If you want to load a document from some location use
 397 \helpref{LoadPage}{wxhtmlwindowloadpage} instead.
 398
 399 \wxheading{Parameters}
 400
 401 \docparam{source}{The HTML document source to be displayed.}
 402
 403 \wxheading{Return value}
 404
 405 false if an error occurred, true otherwise.
 406
 407 \membersection{wxHtmlWindow::SetRelatedFrame}\label{wxhtmlwindowsetrelatedframe}
 408
 409 \func{void}{SetRelatedFrame}{\param{wxFrame* }{frame}, \param{const wxString\& }{format}}
 410
 411 Sets the frame in which page title will be displayed. {\it format} is format of
 412 frame title, e.g. "HtmlHelp : \%s". It must contain exactly one \%s. This
 413 \%s is substituted with HTML page title.
 414
 415 \membersection{wxHtmlWindow::SetRelatedStatusBar}\label{wxhtmlwindowsetrelatedstatusbar}
 416
 417 \func{void}{SetRelatedStatusBar}{\param{int }{bar}}
 418
 419 {\bf After} calling \helpref{SetRelatedFrame}{wxhtmlwindowsetrelatedframe},
 420 this sets statusbar slot where messages will be displayed.
 421 (Default is -1 = no messages.)
 422
 423 \wxheading{Parameters}
 424
 425 \docparam{bar}{statusbar slot number (0..n)}
 426
 427 \membersection{wxHtmlWindow::ToText}\label{wxhtmlwindowtotext}
 428
 429 \func{wxString}{ToText}{\void}
 430
 431 Returns content of currently displayed page as plain text.
 432
 433 \membersection{wxHtmlWindow::WriteCustomization}\label{wxhtmlwindowwritecustomization}
 434
 435 \func{virtual void}{WriteCustomization}{\param{wxConfigBase }{*cfg}, \param{wxString }{path = wxEmptyString}}
 436
 437 Saves custom settings into wxConfig. It uses the path 'path'
 438 if given, otherwise it saves info into currently selected path.
 439 Regardless of whether the path is given or not, the function creates sub-path
 440 {\tt wxHtmlWindow}.
 441
 442 Saved values: all things set by SetFonts, SetBorders.
 443
 444 \wxheading{Parameters}
 445
 446 \docparam{cfg}{wxConfig to which you want to save the configuration.}
 447
 448 \docparam{path}{Optional path in config tree. If not given, the current path is used.}
 449