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