interface/html/htmlwin.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/htmlwin.h
   3 // Purpose:     documentation for wxHtmlWindow class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHtmlWindow
  11     @headerfile htmlwin.h wx/html/htmlwin.h
  12
  13     wxHtmlWindow is probably the only class you will directly use
  14     unless you want to do something special (like adding new tag
  15     handlers or MIME filters).
  16
  17     The purpose of this class is to display HTML pages (either local
  18     file or downloaded via HTTP protocol) in a window. The width
  19     of the window is constant - given in the constructor - and virtual height
  20     is changed dynamically depending on page size.
  21     Once the window is created you can set its content by calling
  22     @ref wxHtmlWindow::setpage SetPage(text),
  23     @ref wxHtmlWindow::loadpage LoadPage(filename) or
  24     wxHtmlWindow::LoadFile.
  25
  26     @beginStyleTable
  27     @style{wxHW_SCROLLBAR_NEVER}:
  28            Never display scrollbars, not even when the page is larger than the
  29            window.
  30     @style{wxHW_SCROLLBAR_AUTO}:
  31            Display scrollbars only if page's size exceeds window's size.
  32     @style{wxHW_NO_SELECTION}:
  33            Don't allow the user to select text.
  34     @endStyleTable
  35
  36     @library{wxhtml}
  37     @category{html}
  38
  39     @seealso
  40     wxHtmlLinkEvent, wxHtmlCellEvent
  41 */
  42 class wxHtmlWindow : public wxScrolledWindow
  43 {
  44 public:
  45     //@{
  46     /**
  47         Constructor. The parameters are the same as for the wxScrolledWindow
  48         constructor.
  49
  50         @param style
  51             Window style. See wxHtmlWindow.
  52     */
  53     wxHtmlWindow();
  54     wxHtmlWindow(wxWindow parent, wxWindowID id = -1,
  55                  const wxPoint& pos = wxDefaultPosition,
  56                  const wxSize& size = wxDefaultSize,
  57                  long style = wxHW_DEFAULT_STYLE,
  58                  const wxString& name = "htmlWindow");
  59     //@}
  60
  61     /**
  62         Adds @ref overview_filters "input filter" to the static list of available
  63         filters. These filters are present by default:
  64          @c text/html MIME type
  65          @c image/* MIME types
  66          Plain Text filter (this filter is used if no other filter matches)
  67     */
  68     static void AddFilter(wxHtmlFilter filter);
  69
  70     /**
  71         Appends HTML fragment to currently displayed text and refreshes the window.
  72
  73         @param source
  74             HTML code fragment
  75
  76         @returns @false if an error occurred, @true otherwise.
  77     */
  78     bool AppendToPage(const wxString& source);
  79
  80     /**
  81         Returns pointer to the top-level container.
  82         See also: @ref overview_cells "Cells Overview",
  83         @ref overview_printing
  84     */
  85     wxHtmlContainerCell* GetInternalRepresentation() const;
  86
  87     /**
  88         Returns anchor within currently opened page
  89         (see wxHtmlWindow::GetOpenedPage).
  90         If no page is opened or if the displayed page wasn't
  91         produced by call to LoadPage, empty string is returned.
  92     */
  93     wxString GetOpenedAnchor();
  94
  95     /**
  96         Returns full location of the opened page. If no page is opened or if the
  97         displayed page wasn't
  98         produced by call to LoadPage, empty string is returned.
  99     */
 100     wxString GetOpenedPage();
 101
 102     /**
 103         Returns title of the opened page or wxEmptyString if current page does not
 104         contain @c TITLE tag.
 105     */
 106     wxString GetOpenedPageTitle();
 107
 108     /**
 109         Returns the related frame.
 110     */
 111     wxFrame* GetRelatedFrame() const;
 112
 113     /**
 114         Moves back to the previous page. (each page displayed using
 115         LoadPage() is stored in history list.)
 116     */
 117     bool HistoryBack();
 118
 119     /**
 120         Returns @true if it is possible to go back in the history (i.e. HistoryBack()
 121         won't fail).
 122     */
 123     bool HistoryCanBack();
 124
 125     /**
 126         Returns @true if it is possible to go forward in the history (i.e. HistoryBack()
 127         won't fail).
 128     */
 129     bool HistoryCanForward();
 130
 131     /**
 132         Clears history.
 133     */
 134     void HistoryClear();
 135
 136     /**
 137         Moves to next page in history.
 138     */
 139     bool HistoryForward();
 140
 141     /**
 142         Loads HTML page from file and displays it.
 143
 144         @returns @false if an error occurred, @true otherwise
 145
 146         @see LoadPage()
 147     */
 148     virtual bool LoadFile(const wxFileName& filename);
 149
 150     /**
 151         Unlike SetPage this function first loads HTML page from @a location
 152         and then displays it. See example:
 153
 154         @param location
 155             The address of document. See wxFileSystem for details on address format and
 156         behaviour of "opener".
 157
 158         @returns @false if an error occurred, @true otherwise
 159
 160         @see LoadFile()
 161     */
 162     virtual bool LoadPage(const wxString& location);
 163
 164     /**
 165         This method is called when a mouse button is clicked inside wxHtmlWindow.
 166         The default behaviour is to emit a wxHtmlCellEvent
 167         and, if the event was not processed or skipped, call
 168         OnLinkClicked() if the cell contains an
 169         hypertext link.
 170         Overloading this method is deprecated; intercept the event instead.
 171
 172         @param cell
 173             The cell inside which the mouse was clicked, always a simple
 174             (i.e. non-container) cell
 175         @param x, y
 176             The logical coordinates of the click point
 177         @param event
 178             The mouse event containing other information about the click
 179
 180         @returns @true if a link was clicked, @false otherwise.
 181     */
 182     virtual bool OnCellClicked(wxHtmlCell cell, wxCoord x, wxCoord y,
 183                                const wxMouseEvent& event);
 184
 185     /**
 186         This method is called when a mouse moves over an HTML cell.
 187         Default behaviour is to emit a wxHtmlCellEvent.
 188         Overloading this method is deprecated; intercept the event instead.
 189
 190         @param cell
 191             The cell inside which the mouse is currently, always a simple
 192             (i.e. non-container) cell
 193         @param x, y
 194             The logical coordinates of the click point
 195     */
 196     virtual void OnCellMouseHover(wxHtmlCell cell, wxCoord x,
 197                                   wxCoord y);
 198
 199     /**
 200         Called when user clicks on hypertext link. Default behaviour is to emit a
 201         wxHtmlLinkEvent and, if the event was not processed
 202         or skipped, call LoadPage() and do nothing else.
 203         Overloading this method is deprecated; intercept the event instead.
 204         Also see wxHtmlLinkInfo.
 205     */
 206     virtual void OnLinkClicked(const wxHtmlLinkInfo& link);
 207
 208     /**
 209         Called when an URL is being opened (either when the user clicks on a link or
 210         an image is loaded). The URL will be opened only if OnOpeningURL returns
 211         @c wxHTML_OPEN. This method is called by
 212         wxHtmlParser::OpenURL.
 213         You can override OnOpeningURL to selectively block some
 214         URLs (e.g. for security reasons) or to redirect them elsewhere. Default
 215         behaviour is to always return @c wxHTML_OPEN.
 216
 217         @param type
 218             Indicates type of the resource. Is one of
 219
 220
 221
 222
 223
 224
 225             wxHTML_URL_PAGE
 226
 227
 228
 229
 230             Opening a HTML page.
 231
 232
 233
 234
 235
 236             wxHTML_URL_IMAGE
 237
 238
 239
 240
 241             Opening an image.
 242
 243
 244
 245
 246
 247             wxHTML_URL_OTHER
 248
 249
 250
 251
 252             Opening a resource that doesn't fall into
 253             any other category.
 254         @param url
 255             URL being opened.
 256         @param redirect
 257             Pointer to wxString variable that must be filled with an
 258             URL if OnOpeningURL returns wxHTML_REDIRECT.
 259     */
 260     virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type,
 261             const wxString& url,
 262             wxString* redirect);
 263
 264     /**
 265         Called on parsing @c TITLE tag.
 266     */
 267     virtual void OnSetTitle(const wxString& title);
 268
 269     /**
 270         This reads custom settings from wxConfig. It uses the path 'path'
 271         if given, otherwise it saves info into currently selected path.
 272         The values are stored in sub-path @c wxHtmlWindow
 273         Read values: all things set by SetFonts, SetBorders.
 274
 275         @param cfg
 276             wxConfig from which you want to read the configuration.
 277         @param path
 278             Optional path in config tree. If not given current path is used.
 279     */
 280     virtual void ReadCustomization(wxConfigBase cfg,
 281                                    wxString path = wxEmptyString);
 282
 283     /**
 284         Selects all text in the window.
 285
 286         @see SelectLine(), SelectWord()
 287     */
 288     void SelectAll();
 289
 290     /**
 291         Selects the line of text that @a pos points at. Note that @e pos
 292         is relative to the top of displayed page, not to window's origin, use
 293         wxScrolledWindow::CalcUnscrolledPosition
 294         to convert physical coordinate.
 295
 296         @see SelectAll(), SelectWord()
 297     */
 298     void SelectLine(const wxPoint& pos);
 299
 300     /**
 301         Selects the word at position @e pos. Note that @e pos
 302         is relative to the top of displayed page, not to window's origin, use
 303         wxScrolledWindow::CalcUnscrolledPosition
 304         to convert physical coordinate.
 305
 306         @see SelectAll(), SelectLine()
 307     */
 308     void SelectWord(const wxPoint& pos);
 309
 310     /**
 311         Returns current selection as plain text. Returns empty string if no text
 312         is currently selected.
 313     */
 314     wxString SelectionToText();
 315
 316     /**
 317         This function sets the space between border of window and HTML contents. See
 318         image:
 319
 320         @param b
 321             indentation from borders in pixels
 322     */
 323     void SetBorders(int b);
 324
 325     /**
 326         This function sets font sizes and faces.
 327
 328         @param normal_face
 329             This is face name for normal (i.e. non-fixed) font.
 330             It can be either empty string (then the default face is chosen) or
 331             platform-specific face name. Examples are "helvetica" under Unix or
 332             "Times New Roman" under Windows.
 333         @param fixed_face
 334             The same thing for fixed face ( TT../TT )
 335         @param sizes
 336             This is an array of 7 items of int type.
 337             The values represent size of font with HTML size from -2 to +4
 338             ( FONT SIZE=-2 to FONT SIZE=+4 ). Default sizes are used if sizes
 339             is @NULL.
 340     */
 341     void SetFonts(const wxString& normal_face,
 342                   const wxString& fixed_face,
 343                   const int sizes = NULL);
 344
 345     /**
 346         Sets HTML page and display it. This won't @b load the page!!
 347         It will display the @e source. See example:
 348
 349         If you want to load a document from some location use
 350         LoadPage() instead.
 351
 352         @param source
 353             The HTML document source to be displayed.
 354
 355         @returns @false if an error occurred, @true otherwise.
 356     */
 357     bool SetPage(const wxString& source);
 358
 359     /**
 360         Sets the frame in which page title will be displayed. @a 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     void SetRelatedFrame(wxFrame* frame, const wxString& format);
 365
 366     /**
 367         @b After calling SetRelatedFrame(),
 368         this sets statusbar slot where messages will be displayed.
 369         (Default is -1 = no messages.)
 370
 371         @param bar
 372             statusbar slot number (0..n)
 373     */
 374     void SetRelatedStatusBar(int bar);
 375
 376     /**
 377         Returns content of currently displayed page as plain text.
 378     */
 379     wxString ToText();
 380
 381     /**
 382         Saves custom settings into wxConfig. It uses the path 'path'
 383         if given, otherwise it saves info into currently selected path.
 384         Regardless of whether the path is given or not, the function creates sub-path
 385         @c wxHtmlWindow.
 386         Saved values: all things set by SetFonts, SetBorders.
 387
 388         @param cfg
 389             wxConfig to which you want to save the configuration.
 390         @param path
 391             Optional path in config tree. If not given, the current path is used.
 392     */
 393     virtual void WriteCustomization(wxConfigBase cfg,
 394                                     wxString path = wxEmptyString);
 395 };
 396
 397
 398 /**
 399     @class wxHtmlLinkEvent
 400     @headerfile htmlwin.h wx/html/htmlwin.h
 401
 402     This event class is used for the events generated by wxHtmlWindow.
 403
 404     @library{wxhtml}
 405     @category{FIXME}
 406 */
 407 class wxHtmlLinkEvent : public wxCommandEvent
 408 {
 409 public:
 410     /**
 411         The constructor is not normally used by the user code.
 412     */
 413     wxHyperlinkEvent(int id, const wxHtmlLinkInfo& linkinfo);
 414
 415     /**
 416         Returns the wxHtmlLinkInfo which contains info about the cell clicked and the
 417         hyperlink it contains.
 418     */
 419     const wxHtmlLinkInfo GetLinkInfo() const;
 420 };
 421
 422
 423 /**
 424     @class wxHtmlCellEvent
 425     @headerfile htmlwin.h wx/html/htmlwin.h
 426
 427     This event class is used for the events generated by wxHtmlWindow.
 428
 429     @library{wxhtml}
 430     @category{FIXME}
 431 */
 432 class wxHtmlCellEvent : public wxCommandEvent
 433 {
 434 public:
 435     /**
 436         The constructor is not normally used by the user code.
 437     */
 438     wxHtmlCellEvent(wxEventType commandType, int id,
 439                     wxHtmlCell* cell,
 440                     const wxPoint& point);
 441
 442     /**
 443         Returns the wxHtmlCellEvent associated with the event.
 444     */
 445     wxHtmlCell* GetCell() const;
 446
 447     /**
 448         Returns @true if @ref setlinkclicked() SetLinkClicked(@true) has previously
 449         been called;
 450         @false otherwise.
 451     */
 452     bool GetLinkClicked() const;
 453
 454     /**
 455         Returns the wxPoint associated with the event.
 456     */
 457     wxPoint GetPoint() const;
 458
 459     /**
 460         Call this function with @c linkclicked set to @true if the cell which has
 461         been clicked contained a link or
 462         @false otherwise (which is the default). With this function the event handler
 463         can return info to the
 464         wxHtmlWindow which sent the event.
 465     */
 466     bool SetLinkClicked(bool linkclicked);
 467 };