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     */
 218     wxHtmlWindow* GetWindow();
 219
 220     /**
 221         Opens new container and returns pointer to it (see @ref overview_html_cells).
 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 wxHtmlContainerCell::SetAlignHor).
 233         Alignment of newly opened container is set to this value.
 234     */
 235     void SetAlign(int a);
 236
 237     /**
 238         Allows you to directly set opened container.
 239         This is not recommended - you should use OpenContainer() wherever possible.
 240     */
 241     wxHtmlContainerCell* SetContainer(wxHtmlContainerCell* c);
 242
 243     /**
 244         Sets the DC. This must be called before wxHtmlParser::Parse!
 245
 246         @a pixel_scale  can be used when rendering to high-resolution
 247         DCs (e.g. printer) to adjust size of pixel metrics. (Many dimensions in
 248         HTML are given in pixels -- e.g. image sizes. 300x300 image would be only one
 249         inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.)
 250     */
 251     virtual void SetDC(wxDC* dc, double pixel_scale = 1.0e+0);
 252
 253     /**
 254         Sets bold flag of actualfont. @a x is either @true of @false.
 255     */
 256     void SetFontBold(int x);
 257
 258     /**
 259         Sets current font face to @a face. This affects either fixed size
 260         font or proportional, depending on context (whether the parser is
 261         inside @c \<TT\> tag or not).
 262     */
 263     void SetFontFace(const wxString& face);
 264
 265     /**
 266         Sets fixed face flag of actualfont. @a x is either @true of @false.
 267     */
 268     void SetFontFixed(int x);
 269
 270     /**
 271         Sets italic flag of actualfont. @a x is either @true of @false.
 272     */
 273     void SetFontItalic(int x);
 274
 275     /**
 276         Sets actual font size (HTML size varies from 1 to 7).
 277     */
 278     void SetFontSize(int s);
 279
 280     /**
 281         Sets underlined flag of actualfont. @a x is either @true of @false.
 282     */
 283     void SetFontUnderlined(int x);
 284
 285     /**
 286         Sets fonts. See wxHtmlWindow::SetFonts for detailed description.
 287     */
 288     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 289                   const int* sizes = 0);
 290
 291     /**
 292         Sets input encoding. The parser uses this information to build conversion
 293         tables from document's encoding to some encoding supported by operating system.
 294     */
 295     void SetInputEncoding(wxFontEncoding enc);
 296
 297     /**
 298         Sets actual hypertext link.
 299         Empty link is represented by wxHtmlLinkInfo with @e Href equal
 300         to wxEmptyString.
 301     */
 302     void SetLink(const wxHtmlLinkInfo& link);
 303
 304     /**
 305         Sets colour of hypertext link.
 306     */
 307     void SetLinkColor(const wxColour& clr);
 308 };
 309