interface/wx/html/winpars.h

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