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     /**
  82         Constructor.
  83
  84         Don't use the default one, use the constructor with @a wndIface parameter
  85         (@a wndIface is a pointer to interface object for the associated wxHtmlWindow
  86         or other HTML rendering window such as wxHtmlListBox).
  87     */
  88     wxHtmlWinParser(wxHtmlWindowInterface* wndIface = NULL);
  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 @ref overview_html_cells).
  98     */
  99     wxHtmlContainerCell* CloseContainer();
 100
 101     /**
 102         Creates font based on current setting (see SetFontSize(), SetFontBold(),
 103         SetFontItalic(), SetFontFixed(), wxHtmlWinParser::SetFontUnderlined)
 104         and returns pointer to it.
 105
 106         If the font was already created only a pointer is returned.
 107     */
 108     virtual wxFont* CreateCurrentFont();
 109
 110     /**
 111         Returns actual text colour.
 112     */
 113     const wxColour& GetActualColor() const;
 114
 115     /**
 116         Returns default horizontal alignment.
 117     */
 118     int GetAlign() const;
 119
 120     /**
 121         Returns (average) char height in standard font.
 122         It is used as DC-independent metrics.
 123
 124         @note This function doesn't return the @e actual height. If you want to
 125               know the height of the current font, call @c GetDC->GetCharHeight().
 126     */
 127     int GetCharHeight() const;
 128
 129     /**
 130         Returns average char width in standard font.
 131         It is used as DC-independent metrics.
 132
 133         @note This function doesn't return the @e actual width. If you want to
 134               know the height of the current font, call @c GetDC->GetCharWidth().
 135     */
 136     int GetCharWidth() const;
 137
 138     /**
 139         Returns pointer to the currently opened container (see @ref overview_html_cells).
 140         Common use:
 141         @code
 142         m_WParser -> GetContainer() -> InsertCell(new ...);
 143         @endcode
 144     */
 145     wxHtmlContainerCell* GetContainer() const;
 146
 147     /**
 148         Returns pointer to the DC used during parsing.
 149     */
 150     wxDC* GetDC();
 151
 152     /**
 153         Returns wxEncodingConverter class used to do conversion between the
 154         @ref GetInputEncoding() "input encoding" and the
 155         @ref GetOutputEncoding() "output encoding".
 156     */
 157     wxEncodingConverter* GetEncodingConverter() const;
 158
 159     /**
 160         Returns @true if actual font is bold, @false otherwise.
 161     */
 162     int GetFontBold() const;
 163
 164     /**
 165         Returns actual font face name.
 166     */
 167     wxString GetFontFace() const;
 168
 169     /**
 170         Returns @true if actual font is fixed face, @false otherwise.
 171     */
 172     int GetFontFixed() const;
 173
 174     /**
 175         Returns @true if actual font is italic, @false otherwise.
 176     */
 177     int GetFontItalic() const;
 178
 179     /**
 180         Returns actual font size (HTML size varies from -2 to +4)
 181     */
 182     int GetFontSize() const;
 183
 184     /**
 185         Returns @true if actual font is underlined, @false otherwise.
 186     */
 187     int GetFontUnderlined() const;
 188
 189     /**
 190         Returns input encoding.
 191     */
 192     wxFontEncoding GetInputEncoding() const;
 193
 194     /**
 195         Returns actual hypertext link.
 196         (This value has a non-empty @ref wxHtmlLinkInfo::GetHref Href string
 197         if the parser is between \<A\> and \</A\> tags, wxEmptyString otherwise.)
 198     */
 199     const wxHtmlLinkInfo& GetLink() const;
 200
 201     /**
 202         Returns the colour of hypertext link text.
 203     */
 204     const wxColour& GetLinkColor() const;
 205
 206     /**
 207         Returns output encoding, i.e. closest match to document's input encoding
 208         that is supported by operating system.
 209     */
 210     wxFontEncoding GetOutputEncoding() const;
 211
 212     /**
 213         Returns associated window (wxHtmlWindow). This may be @NULL!
 214         (You should always test if it is non-@NULL.
 215         For example @c TITLE handler sets window title only if some window is
 216         associated, otherwise it does nothing.
 217         @deprecated use GetWindowInterface()->GetHTMLWindow() instead
 218     */
 219     wxHtmlWindow* GetWindow();
 220
 221     /**
 222         Opens new container and returns pointer to it (see @ref overview_html_cells).
 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 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.
 240         This is not recommended - you should use OpenContainer() wherever possible.
 241     */
 242     wxHtmlContainerCell* SetContainer(wxHtmlContainerCell* c);
 243
 244     /**
 245         Sets the DC. This must be called before wxHtmlParser::Parse!
 246
 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.0e+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 @a 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 detailed description.
 288     */
 289     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 290                   const int* sizes = 0);
 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 system.
 295     */
 296     void SetInputEncoding(wxFontEncoding enc);
 297
 298     /**
 299         Sets actual hypertext link.
 300         Empty link is represented by wxHtmlLinkInfo with @e Href equal
 301         to wxEmptyString.
 302     */
 303     void SetLink(const wxHtmlLinkInfo& link);
 304
 305     /**
 306         Sets colour of hypertext link.
 307     */
 308     void SetLinkColor(const wxColour& clr);
 309 };
 310