X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..058f225a44d83d42ba9d773efc705badbf0e5e3c:/interface/wx/html/winpars.h diff --git a/interface/wx/html/winpars.h b/interface/wx/html/winpars.h index ed5d5348b1..70227dc3a1 100644 --- a/interface/wx/html/winpars.h +++ b/interface/wx/html/winpars.h @@ -8,17 +8,15 @@ /** @class wxHtmlTagsModule - @headerfile winpars.h wx/html/winpars.h This class provides easy way of filling wxHtmlWinParser's table of tag handlers. It is used almost exclusively together with the set of - @ref overview_handlers "TAGS_MODULE_* macros" + @ref overview_html_handlers "TAGS_MODULE_* macros" @library{wxhtml} - @category{FIXME} + @category{html} - @see @ref overview_handlers "Tag Handlers", wxHtmlTagHandler, - wxHtmlWinTagHandler, + @see @ref overview_html_handlers, wxHtmlTagHandler, wxHtmlWinTagHandler */ class wxHtmlTagsModule : public wxModule { @@ -26,89 +24,85 @@ public: /** You must override this method. In most common case its body consists only of lines of the following type: - - I recommend using the @b TAGS_MODULE_* macros. - + @code + parser -> AddTagHandler(new MyHandler); + @endcode + + It's recommended to use the @b TAGS_MODULE_* macros. + @param parser Pointer to the parser that requested tables filling. */ - virtual void FillHandlersTable(wxHtmlWinParser parser); + virtual void FillHandlersTable(wxHtmlWinParser* parser); }; /** @class wxHtmlWinTagHandler - @headerfile winpars.h wx/html/winpars.h - This is basically wxHtmlTagHandler except that - it is extended with protected member m_WParser pointing to - the wxHtmlWinParser object (value of this member is identical - to wxHtmlParser's m_Parser). + This is basically wxHtmlTagHandler except that it is extended with protected + member m_WParser pointing to the wxHtmlWinParser object (value of this member + is identical to wxHtmlParser's m_Parser). @library{wxhtml} @category{html} */ class wxHtmlWinTagHandler : public wxHtmlTagHandler { -public: +protected: /** - @b wxHtmlWinParser* m_WParser - Value of this attribute is identical to value of m_Parser. The only different - is that m_WParser points to wxHtmlWinParser object while m_Parser - points to wxHtmlParser object. (The same object, but overcast.) + Value of this attribute is identical to value of m_Parser. + The only difference is that m_WParser points to wxHtmlWinParser object + while m_Parser points to wxHtmlParser object. (The same object, but overcast.) */ + wxHtmlWinParser* m_WParser; }; /** @class wxHtmlWinParser - @headerfile winpars.h wx/html/winpars.h - This class is derived from wxHtmlParser and - its main goal is to parse HTML input so that it can be displayed in - wxHtmlWindow. It uses a special - wxHtmlWinTagHandler. + This class is derived from wxHtmlParser and its main goal is to parse HTML + input so that it can be displayed in wxHtmlWindow. + It uses a special wxHtmlWinTagHandler. + + @note The product of parsing is a wxHtmlCell (resp. wxHtmlContainer) object. @library{wxhtml} @category{html} - @see @ref overview_handlers "Handlers overview" + @see @ref overview_html_handlers */ class wxHtmlWinParser : public wxHtmlParser { public: - //@{ /** - Constructor. Don't use the default one, use constructor with - @a wndIface parameter (@a wndIface is a pointer to interface object for - the associated wxHtmlWindow or other HTML rendering - window such as wxHtmlListBox). + Constructor. + + Don't use the default one, use the constructor with @a wndIface parameter + (@a wndIface is a pointer to interface object for the associated wxHtmlWindow + or other HTML rendering window such as wxHtmlListBox). */ - wxHtmlWinParser(); - wxHtmlWinParser(wxHtmlWindowInterface wndIface); - //@} + wxHtmlWinParser(wxHtmlWindowInterface* wndIface = NULL); /** Adds module() to the list of wxHtmlWinParser tag handler. */ - static void AddModule(wxHtmlTagsModule module); + static void AddModule(wxHtmlTagsModule* module); /** Closes the container, sets actual container to the parent one - and returns pointer to it (see Overview()). + and returns pointer to it (see @ref overview_html_cells). */ wxHtmlContainerCell* CloseContainer(); /** - Creates font based on current setting (see - SetFontSize(), - SetFontBold(), - SetFontItalic(), - SetFontFixed(), - wxHtmlWinParser::SetFontUnderlined) + Creates font based on current setting (see SetFontSize(), SetFontBold(), + SetFontItalic(), SetFontFixed(), wxHtmlWinParser::SetFontUnderlined) and returns pointer to it. + If the font was already created only a pointer is returned. */ virtual wxFont* CreateCurrentFont(); @@ -116,7 +110,7 @@ public: /** Returns actual text colour. */ - const wxColour GetActualColor() const; + const wxColour& GetActualColor() const; /** Returns default horizontal alignment. @@ -124,24 +118,29 @@ public: int GetAlign() const; /** - Returns (average) char height in standard font. It is used as DC-independent - metrics. + Returns (average) char height in standard font. + It is used as DC-independent metrics. + @note This function doesn't return the @e actual height. If you want to - know the height of the current font, call @c GetDC - GetCharHeight(). + know the height of the current font, call @c GetDC->GetCharHeight(). */ int GetCharHeight() const; /** - Returns average char width in standard font. It is used as DC-independent - metrics. + Returns average char width in standard font. + It is used as DC-independent metrics. + @note This function doesn't return the @e actual width. If you want to - know the height of the current font, call @c GetDC - GetCharWidth() + know the height of the current font, call @c GetDC->GetCharWidth(). */ int GetCharWidth() const; /** - Returns pointer to the currently opened container (see Overview()). + Returns pointer to the currently opened container (see @ref overview_html_cells). Common use: + @code + m_WParser -> GetContainer() -> InsertCell(new ...); + @endcode */ wxHtmlContainerCell* GetContainer() const; @@ -151,9 +150,9 @@ public: wxDC* GetDC(); /** - Returns wxEncodingConverter class used - to do conversion between @ref getinputencoding() "input encoding" - and @ref getoutputencoding() "output encoding". + Returns wxEncodingConverter class used to do conversion between the + @ref GetInputEncoding() "input encoding" and the + @ref GetOutputEncoding() "output encoding". */ wxEncodingConverter* GetEncodingConverter() const; @@ -193,17 +192,16 @@ public: wxFontEncoding GetInputEncoding() const; /** - Returns actual hypertext link. (This value has a non-empty - @ref wxHtmlLinkInfo::gethref Href string - if the parser is between @c A and @c /A tags, - wxEmptyString otherwise.) + Returns actual hypertext link. + (This value has a non-empty @ref wxHtmlLinkInfo::GetHref Href string + if the parser is between \ and \ tags, wxEmptyString otherwise.) */ - const wxHtmlLinkInfo GetLink() const; + const wxHtmlLinkInfo& GetLink() const; /** Returns the colour of hypertext link text. */ - const wxColour GetLinkColor() const; + const wxColour& GetLinkColor() const; /** Returns output encoding, i.e. closest match to document's input encoding @@ -212,14 +210,16 @@ public: wxFontEncoding GetOutputEncoding() const; /** - Returns associated window (wxHtmlWindow). This may be @NULL! (You should always - test if it is non-@NULL. For example @c TITLE handler sets window - title only if some window is associated, otherwise it does nothing) + Returns associated window (wxHtmlWindow). This may be @NULL! + (You should always test if it is non-@NULL. + For example @c TITLE handler sets window title only if some window is + associated, otherwise it does nothing. + @deprecated use GetWindowInterface()->GetHTMLWindow() instead */ wxHtmlWindow* GetWindow(); /** - Opens new container and returns pointer to it (see Overview()). + Opens new container and returns pointer to it (see @ref overview_html_cells). */ wxHtmlContainerCell* OpenContainer(); @@ -230,27 +230,26 @@ public: void SetActualColor(const wxColour& clr); /** - Sets default horizontal alignment (see - wxHtmlContainerCell::SetAlignHor.) + Sets default horizontal alignment (see wxHtmlContainerCell::SetAlignHor). Alignment of newly opened container is set to this value. */ void SetAlign(int a); /** - Allows you to directly set opened container. This is not recommended - you - should use OpenContainer - wherever possible. + Allows you to directly set opened container. + This is not recommended - you should use OpenContainer() wherever possible. */ wxHtmlContainerCell* SetContainer(wxHtmlContainerCell* c); /** Sets the DC. This must be called before wxHtmlParser::Parse! + @a pixel_scale can be used when rendering to high-resolution DCs (e.g. printer) to adjust size of pixel metrics. (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300 image would be only one inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.) */ - virtual void SetDC(wxDC dc, double pixel_scale = 1.0); + virtual void SetDC(wxDC* dc, double pixel_scale = 1.0e+0); /** Sets bold flag of actualfont. @a x is either @true of @false. @@ -258,9 +257,9 @@ public: void SetFontBold(int x); /** - Sets current font face to @e face. This affects either fixed size + Sets current font face to @a face. This affects either fixed size font or proportional, depending on context (whether the parser is - inside @c TT tag or not). + inside @c \ tag or not). */ void SetFontFace(const wxString& face); @@ -275,7 +274,7 @@ public: void SetFontItalic(int x); /** - Sets actual font size (HTML size varies from 1 to 7) + Sets actual font size (HTML size varies from 1 to 7). */ void SetFontSize(int s); @@ -285,23 +284,20 @@ public: void SetFontUnderlined(int x); /** - Sets fonts. See wxHtmlWindow::SetFonts for - detailed description. + Sets fonts. See wxHtmlWindow::SetFonts for detailed description. */ - void SetFonts(const wxString& normal_face, - const wxString& fixed_face, - const int sizes = NULL); + void SetFonts(const wxString& normal_face, const wxString& fixed_face, + const int* sizes = 0); /** Sets input encoding. The parser uses this information to build conversion - tables from document's encoding to some encoding supported by operating - system. + tables from document's encoding to some encoding supported by operating system. */ void SetInputEncoding(wxFontEncoding enc); /** - Sets actual hypertext link. Empty link is represented - by wxHtmlLinkInfo with @e Href equal + Sets actual hypertext link. + Empty link is represented by wxHtmlLinkInfo with @e Href equal to wxEmptyString. */ void SetLink(const wxHtmlLinkInfo& link);