interface/html/winpars.h

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