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