interface/html/htmlwin.h

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