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_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 protected:
  54     /**
  55         Value of this attribute is identical to value of m_Parser.
  56         The only difference is that m_WParser points to wxHtmlWinParser object
  57         while m_Parser points to wxHtmlParser object. (The same object, but overcast.)
  58     */
  59     wxHtmlWinParser* m_WParser;
  60 };
  61
  62
  63
  64 /**
  65     @class wxHtmlWinParser
  66
  67     This class is derived from wxHtmlParser and its main goal is to parse HTML
  68     input so that it can be displayed in wxHtmlWindow.
  69     It uses a special wxHtmlWinTagHandler.
  70
  71     @note The product of parsing is a wxHtmlCell (resp. wxHtmlContainer) object.
  72
  73     @library{wxhtml}
  74     @category{html}
  75
  76     @see @ref overview_html_handlers
  77 */
  78 class wxHtmlWinParser : public wxHtmlParser
  79 {
  80 public:
  81     wxHtmlWinParser();
  82
  83     /**
  84         Constructor.
  85
  86         Don't use the default one, use constructor with @a wndIface parameter
  87         (@a wndIface is a pointer to interface object for the associated wxHtmlWindow
  88         or other HTML rendering window such as wxHtmlListBox).
  89     */
  90     wxHtmlWinParser(wxHtmlWindowInterface wndIface);
  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 @ref overview_html_cells).
 100     */
 101     wxHtmlContainerCell* CloseContainer();
 102
 103     /**
 104         Creates font based on current setting (see SetFontSize(), SetFontBold(),
 105         SetFontItalic(), SetFontFixed(), wxHtmlWinParser::SetFontUnderlined)
 106         and returns pointer to it.
 107
 108         If the font was already created only a pointer is returned.
 109     */
 110     virtual wxFont* CreateCurrentFont();
 111
 112     /**
 113         Returns actual text colour.
 114     */
 115     const wxColour& GetActualColor() const;
 116
 117     /**
 118         Returns default horizontal alignment.
 119     */
 120     int GetAlign() const;
 121
 122     /**
 123         Returns (average) char height in standard font.
 124         It is used as DC-independent metrics.
 125
 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.
 133         It is used as DC-independent metrics.
 134
 135         @note This function doesn't return the @e actual width. If you want to
 136               know the height of the current font, call @c GetDC->GetCharWidth().
 137     */
 138     int GetCharWidth() const;
 139
 140     /**
 141         Returns pointer to the currently opened container (see @ref overview_html_cells).
 142         Common use:
 143         @code
 144         m_WParser -> GetContainer() -> InsertCell(new ...);
 145         @endcode
 146     */
 147     wxHtmlContainerCell* GetContainer() const;
 148
 149     /**
 150         Returns pointer to the DC used during parsing.
 151     */
 152     wxDC* GetDC();
 153
 154     /**
 155         Returns wxEncodingConverter class used to do conversion between the
 156         @ref GetInputEncoding() "input encoding" and the
 157         @ref GetOutputEncoding() "output encoding".
 158     */
 159     wxEncodingConverter* GetEncodingConverter() const;
 160
 161     /**
 162         Returns @true if actual font is bold, @false otherwise.
 163     */
 164     int GetFontBold() const;
 165
 166     /**
 167         Returns actual font face name.
 168     */
 169     wxString GetFontFace() const;
 170
 171     /**
 172         Returns @true if actual font is fixed face, @false otherwise.
 173     */
 174     int GetFontFixed() const;
 175
 176     /**
 177         Returns @true if actual font is italic, @false otherwise.
 178     */
 179     int GetFontItalic() const;
 180
 181     /**
 182         Returns actual font size (HTML size varies from -2 to +4)
 183     */
 184     int GetFontSize() const;
 185
 186     /**
 187         Returns @true if actual font is underlined, @false otherwise.
 188     */
 189     int GetFontUnderlined() const;
 190
 191     /**
 192         Returns input encoding.
 193     */
 194     wxFontEncoding GetInputEncoding() const;
 195
 196     /**
 197         Returns actual hypertext link.
 198         (This value has a non-empty @ref wxHtmlLinkInfo::GetHref Href string
 199         if the parser is between \<A\> and \</A\> tags, 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!
 216         (You should always test if it is non-@NULL.
 217         For example @c TITLE handler sets window title only if some window is
 218         associated, otherwise it does nothing.
 219     */
 220     wxHtmlWindow* GetWindow();
 221
 222     /**
 223         Opens new container and returns pointer to it (see @ref overview_html_cells).
 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 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.
 241         This is not recommended - you should use OpenContainer() wherever possible.
 242     */
 243     wxHtmlContainerCell* SetContainer(wxHtmlContainerCell* c);
 244
 245     /**
 246         Sets the DC. This must be called before wxHtmlParser::Parse!
 247
 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.0e+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 @a 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 detailed description.
 289     */
 290     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 291                   const int* sizes = 0);
 292
 293     /**
 294         Sets input encoding. The parser uses this information to build conversion
 295         tables from document's encoding to some encoding supported by operating system.
 296     */
 297     void SetInputEncoding(wxFontEncoding enc);
 298
 299     /**
 300         Sets actual hypertext link.
 301         Empty link is represented 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