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         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     @class wxHtmlWinTagHandler
  40     @headerfile winpars.h wx/html/winpars.h
  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
  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         @e wndIface parameter (@e 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
 129         @b 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();
 133
 134     /**
 135         Returns average char width in standard font. It is used as DC-independent
 136         metrics.
 137
 138         @b Note: This function doesn't return the @e actual width. If you want to
 139         know the height of the current font, call @c GetDC - GetCharWidth()
 140     */
 141     int GetCharWidth();
 142
 143     /**
 144         Returns pointer to the currently opened container (see Overview).
 145         Common use:
 146     */
 147     wxHtmlContainerCell* GetContainer();
 148
 149     /**
 150         Returns pointer to the DC used during parsing.
 151     */
 152 #define wxDC* GetDC()     /* implementation is private */
 153
 154     /**
 155         Returns wxEncodingConverter class used
 156         to do conversion between @ref getinputencoding() "input encoding"
 157         and @ref getoutputencoding() "output encoding".
 158     */
 159     wxEncodingConverter * GetEncodingConverter();
 160
 161     /**
 162         Returns @true if actual font is bold, @false otherwise.
 163     */
 164     int GetFontBold();
 165
 166     /**
 167         Returns actual font face name.
 168     */
 169     wxString GetFontFace();
 170
 171     /**
 172         Returns @true if actual font is fixed face, @false otherwise.
 173     */
 174     int GetFontFixed();
 175
 176     /**
 177         Returns @true if actual font is italic, @false otherwise.
 178     */
 179     int GetFontItalic();
 180
 181     /**
 182         Returns actual font size (HTML size varies from -2 to +4)
 183     */
 184     int GetFontSize();
 185
 186     /**
 187         Returns @true if actual font is underlined, @false otherwise.
 188     */
 189     int GetFontUnderlined();
 190
 191     /**
 192         Returns input encoding.
 193     */
 194     wxFontEncoding GetInputEncoding();
 195
 196     /**
 197         Returns actual hypertext link. (This value has a non-empty
 198         @ref wxHtmlLinkInfo::gethref Href string
 199         if the parser is between @c A and @c /A tags,
 200         wxEmptyString otherwise.)
 201     */
 202     const wxHtmlLinkInfo GetLink();
 203
 204     /**
 205         Returns the colour of hypertext link text.
 206     */
 207     const wxColour GetLinkColor();
 208
 209     /**
 210         Returns output encoding, i.e. closest match to document's input encoding
 211         that is supported by operating system.
 212     */
 213     wxFontEncoding GetOutputEncoding();
 214
 215     /**
 216         Returns associated window (wxHtmlWindow). This may be @NULL! (You should always
 217         test if it is non-@NULL. For example @c TITLE handler sets window
 218         title only if some window is associated, otherwise it does nothing)
 219     */
 220     wxHtmlWindow* GetWindow();
 221
 222     /**
 223         Opens new container and returns pointer to it (see Overview).
 224     */
 225     wxHtmlContainerCell* OpenContainer();
 226
 227     /**
 228         Sets actual text colour. Note: this DOESN'T change the colour!
 229         You must create wxHtmlColourCell yourself.
 230     */
 231     void SetActualColor(const wxColour& clr);
 232
 233     /**
 234         Sets default horizontal alignment (see
 235         wxHtmlContainerCell::SetAlignHor.)
 236         Alignment of newly opened container is set to this value.
 237     */
 238     void SetAlign(int a);
 239
 240     /**
 241         Allows you to directly set opened container. This is not recommended - you
 242         should use OpenContainer
 243         wherever possible.
 244     */
 245     wxHtmlContainerCell* SetContainer(wxHtmlContainerCell * c);
 246
 247     /**
 248         Sets the DC. This must be called before wxHtmlParser::Parse!
 249         @e pixel_scale  can be used when rendering to high-resolution
 250         DCs (e.g. printer) to adjust size of pixel metrics. (Many dimensions in
 251         HTML are given in pixels -- e.g. image sizes. 300x300 image would be only one
 252         inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.)
 253     */
 254 #define virtual void SetDC(wxDC dc, double pixel_scale = 1.0)     /* implementation is private */
 255
 256     /**
 257         Sets bold flag of actualfont. @e x is either @true of @false.
 258     */
 259     void SetFontBold(int x);
 260
 261     /**
 262         Sets current font face to @e face. This affects either fixed size
 263         font or proportional, depending on context (whether the parser is
 264         inside @c TT tag or not).
 265     */
 266     void SetFontFace(const wxString& face);
 267
 268     /**
 269         Sets fixed face flag of actualfont. @e x is either @true of @false.
 270     */
 271     void SetFontFixed(int x);
 272
 273     /**
 274         Sets italic flag of actualfont. @e x is either @true of @false.
 275     */
 276     void SetFontItalic(int x);
 277
 278     /**
 279         Sets actual font size (HTML size varies from 1 to 7)
 280     */
 281     void SetFontSize(int s);
 282
 283     /**
 284         Sets underlined flag of actualfont. @e x is either @true of @false.
 285     */
 286     void SetFontUnderlined(int x);
 287
 288     /**
 289         Sets fonts. See wxHtmlWindow::SetFonts for
 290         detailed description.
 291     */
 292     void SetFonts(const wxString& normal_face,
 293                   const wxString& fixed_face,
 294                   const int sizes = @NULL);
 295
 296     /**
 297         Sets input encoding. The parser uses this information to build conversion
 298         tables from document's encoding to some encoding supported by operating
 299         system.
 300     */
 301     void SetInputEncoding(wxFontEncoding enc);
 302
 303     /**
 304         Sets actual hypertext link. Empty link is represented
 305         by wxHtmlLinkInfo with @e Href equal
 306         to wxEmptyString.
 307     */
 308     void SetLink(const wxHtmlLinkInfo& link);
 309
 310     /**
 311         Sets colour of hypertext link.
 312     */
 313     void SetLinkColor(const wxColour& clr);
 314 };