interface/wx/html/winpars.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/winpars.h
   3 // Purpose:     interface of wxHtmlTagsModule
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHtmlTagsModule
  11
  12     This class provides easy way of filling wxHtmlWinParser's table of
  13     tag handlers. It is used almost exclusively together with the set of
  14     @ref overview_html_handlers "TAGS_MODULE_* macros"
  15
  16     @library{wxhtml}
  17     @category{html}
  18
  19     @see @ref overview_html_handlers, wxHtmlTagHandler, wxHtmlWinTagHandler
  20 */
  21 class wxHtmlTagsModule : public wxModule
  22 {
  23 public:
  24     /**
  25         You must override this method. In most common case its body consists
  26         only of lines of the following type:
  27         @code
  28         parser -> AddTagHandler(new MyHandler);
  29         @endcode
  30
  31         It's recommended to use the @b TAGS_MODULE_* macros.
  32
  33         @param parser
  34             Pointer to the parser that requested tables filling.
  35     */
  36     virtual void FillHandlersTable(wxHtmlWinParser* parser);
  37 };
  38
  39
  40
  41 /**
  42     @class wxHtmlWinTagHandler
  43
  44     This is basically wxHtmlTagHandler except that it is extended with protected
  45     member m_WParser pointing to the wxHtmlWinParser object (value of this member
  46     is identical to wxHtmlParser's m_Parser).
  47
  48     @library{wxhtml}
  49     @category{html}
  50 */
  51 class wxHtmlWinTagHandler : public wxHtmlTagHandler
  52 {
  53 public:
  54     /**
  55         Constructor.
  56     */
  57     wxHtmlWinTagHandler();
  58
  59     /**
  60         Assigns @a parser to this handler. Each @b instance of handler
  61         is guaranteed to be called only from the one parser.
  62     */
  63     virtual void SetParser(wxHtmlWinParser* parser);
  64
  65     /**
  66        Returns the parser associated with this tag handler.
  67     */
  68     virtual wxHtmlWinParser* GetParser() const;
  69
  70 protected:
  71     /**
  72         Value of this attribute is identical to value of m_Parser.
  73         The only difference is that m_WParser points to wxHtmlWinParser object
  74         while m_Parser points to wxHtmlParser object. (The same object, but overcast.)
  75     */
  76     wxHtmlWinParser* m_WParser;
  77 };
  78
  79
  80
  81 /**
  82     @class wxHtmlWinParser
  83
  84     This class is derived from wxHtmlParser and its main goal is to parse HTML
  85     input so that it can be displayed in wxHtmlWindow.
  86     It uses a special wxHtmlWinTagHandler.
  87
  88     @note The product of parsing is a wxHtmlCell (resp. wxHtmlContainer) object.
  89
  90     @library{wxhtml}
  91     @category{html}
  92
  93     @see @ref overview_html_handlers
  94 */
  95 class wxHtmlWinParser : public wxHtmlParser
  96 {
  97 public:
  98     /**
  99         Constructor.
 100
 101         Don't use the default one, use the constructor with @a wndIface parameter
 102         (@a wndIface is a pointer to interface object for the associated wxHtmlWindow
 103         or other HTML rendering window such as wxHtmlListBox).
 104     */
 105     wxHtmlWinParser(wxHtmlWindowInterface* wndIface = NULL);
 106
 107     /**
 108         Adds module() to the list of wxHtmlWinParser tag handler.
 109     */
 110     static void AddModule(wxHtmlTagsModule* module);
 111
 112     /**
 113         Closes the container, sets actual container to the parent one
 114         and returns pointer to it (see @ref overview_html_cells).
 115     */
 116     wxHtmlContainerCell* CloseContainer();
 117
 118     /**
 119         Creates font based on current setting (see SetFontSize(), SetFontBold(),
 120         SetFontItalic(), SetFontFixed(), wxHtmlWinParser::SetFontUnderlined)
 121         and returns pointer to it.
 122
 123         If the font was already created only a pointer is returned.
 124     */
 125     virtual wxFont* CreateCurrentFont();
 126
 127     /**
 128         Returns actual text colour.
 129     */
 130     const wxColour& GetActualColor() const;
 131
 132     /**
 133         Returns default horizontal alignment.
 134     */
 135     int GetAlign() const;
 136
 137     /**
 138         Returns (average) char height in standard font.
 139         It is used as DC-independent metrics.
 140
 141         @note This function doesn't return the @e actual height. If you want to
 142               know the height of the current font, call @c GetDC->GetCharHeight().
 143     */
 144     int GetCharHeight() const;
 145
 146     /**
 147         Returns average char width in standard font.
 148         It is used as DC-independent metrics.
 149
 150         @note This function doesn't return the @e actual width. If you want to
 151               know the height of the current font, call @c GetDC->GetCharWidth().
 152     */
 153     int GetCharWidth() const;
 154
 155     /**
 156         Returns pointer to the currently opened container (see @ref overview_html_cells).
 157         Common use:
 158         @code
 159         m_WParser -> GetContainer() -> InsertCell(new ...);
 160         @endcode
 161     */
 162     wxHtmlContainerCell* GetContainer() const;
 163
 164     /**
 165         Returns pointer to the DC used during parsing.
 166     */
 167     wxDC* GetDC();
 168
 169     /**
 170         Returns wxEncodingConverter class used to do conversion between the
 171         @ref GetInputEncoding() "input encoding" and the
 172         @ref GetOutputEncoding() "output encoding".
 173     */
 174     wxEncodingConverter* GetEncodingConverter() const;
 175
 176     /**
 177         Returns @true if actual font is bold, @false otherwise.
 178     */
 179     int GetFontBold() const;
 180
 181     /**
 182         Returns actual font face name.
 183     */
 184     wxString GetFontFace() const;
 185
 186     /**
 187         Returns @true if actual font is fixed face, @false otherwise.
 188     */
 189     int GetFontFixed() const;
 190
 191     /**
 192         Returns @true if actual font is italic, @false otherwise.
 193     */
 194     int GetFontItalic() const;
 195
 196     /**
 197         Returns actual font size (HTML size varies from -2 to +4)
 198     */
 199     int GetFontSize() const;
 200
 201     /**
 202         Returns @true if actual font is underlined, @false otherwise.
 203     */
 204     int GetFontUnderlined() const;
 205
 206     /**
 207         Returns input encoding.
 208     */
 209     wxFontEncoding GetInputEncoding() const;
 210
 211     /**
 212         Returns actual hypertext link.
 213         (This value has a non-empty @ref wxHtmlLinkInfo::GetHref Href string
 214         if the parser is between \<A\> and \</A\> tags, wxEmptyString otherwise.)
 215     */
 216     const wxHtmlLinkInfo& GetLink() const;
 217
 218     /**
 219         Returns the colour of hypertext link text.
 220     */
 221     const wxColour& GetLinkColor() const;
 222
 223     /**
 224         Returns output encoding, i.e. closest match to document's input encoding
 225         that is supported by operating system.
 226     */
 227     wxFontEncoding GetOutputEncoding() const;
 228
 229     /**
 230         Returns associated window (wxHtmlWindow). This may be @NULL!
 231         (You should always test if it is non-@NULL.
 232         For example @c TITLE handler sets window title only if some window is
 233         associated, otherwise it does nothing.
 234    */
 235     wxHtmlWindowInterface* GetWindowInterface();
 236
 237     /**
 238         Opens new container and returns pointer to it (see @ref overview_html_cells).
 239     */
 240     wxHtmlContainerCell* OpenContainer();
 241
 242     /**
 243         Sets actual text colour. Note: this DOESN'T change the colour!
 244         You must create wxHtmlColourCell yourself.
 245     */
 246     void SetActualColor(const wxColour& clr);
 247
 248     /**
 249         Sets default horizontal alignment (see wxHtmlContainerCell::SetAlignHor).
 250         Alignment of newly opened container is set to this value.
 251     */
 252     void SetAlign(int a);
 253
 254     /**
 255         Allows you to directly set opened container.
 256         This is not recommended - you should use OpenContainer() wherever possible.
 257     */
 258     wxHtmlContainerCell* SetContainer(wxHtmlContainerCell* c);
 259
 260     /**
 261         Sets the DC. This must be called before wxHtmlParser::Parse!
 262
 263         @a pixel_scale  can be used when rendering to high-resolution
 264         DCs (e.g. printer) to adjust size of pixel metrics. (Many dimensions in
 265         HTML are given in pixels -- e.g. image sizes. 300x300 image would be only one
 266         inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.)
 267     */
 268     virtual void SetDC(wxDC* dc, double pixel_scale = 1.0e+0);
 269
 270     /**
 271         Sets bold flag of actualfont. @a x is either @true of @false.
 272     */
 273     void SetFontBold(int x);
 274
 275     /**
 276         Sets current font face to @a face. This affects either fixed size
 277         font or proportional, depending on context (whether the parser is
 278         inside @c \<TT\> tag or not).
 279     */
 280     void SetFontFace(const wxString& face);
 281
 282     /**
 283         Sets fixed face flag of actualfont. @a x is either @true of @false.
 284     */
 285     void SetFontFixed(int x);
 286
 287     /**
 288         Sets italic flag of actualfont. @a x is either @true of @false.
 289     */
 290     void SetFontItalic(int x);
 291
 292     /**
 293         Sets actual font size (HTML size varies from 1 to 7).
 294     */
 295     void SetFontSize(int s);
 296
 297     /**
 298         Sets underlined flag of actualfont. @a x is either @true of @false.
 299     */
 300     void SetFontUnderlined(int x);
 301
 302     /**
 303         Sets fonts. See wxHtmlWindow::SetFonts for detailed description.
 304     */
 305     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 306                   const int* sizes = 0);
 307
 308     /**
 309         Sets input encoding. The parser uses this information to build conversion
 310         tables from document's encoding to some encoding supported by operating system.
 311     */
 312     void SetInputEncoding(wxFontEncoding enc);
 313
 314     /**
 315         Sets actual hypertext link.
 316         Empty link is represented by wxHtmlLinkInfo with @e Href equal
 317         to wxEmptyString.
 318     */
 319     void SetLink(const wxHtmlLinkInfo& link);
 320
 321     /**
 322         Sets colour of hypertext link.
 323     */
 324     void SetLinkColor(const wxColour& clr);
 325 };
 326