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