From: Francesco Montorsi Date: Sat, 25 Oct 2008 20:44:52 +0000 (+0000) Subject: other interface revisions of html headers X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/5bddd46dde044ccb04952e027b4ec27bb1251bba?ds=inline other interface revisions of html headers git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56518 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/interface/wx/html/htmlcell.h b/interface/wx/html/htmlcell.h index fc228e89df..34b3c9c3a7 100644 --- a/interface/wx/html/htmlcell.h +++ b/interface/wx/html/htmlcell.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: html/htmlcell.h -// Purpose: interface of wxHtmlColourCell +// Purpose: interface of wxHtml*Cell // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -24,29 +24,8 @@ public: The color @param flags Can be one of following: - - - - - - - wxHTML_CLR_FOREGROUND - - - - - change color of text - - - - - - wxHTML_CLR_BACKGROUND - - - - - change background color + - wxHTML_CLR_FOREGROUND: change color of text + - wxHTML_CLR_BACKGROUND: change background color */ wxHtmlColourCell(const wxColour& clr, int flags = wxHTML_CLR_FOREGROUND); }; @@ -57,14 +36,13 @@ public: @class wxHtmlWidgetCell wxHtmlWidgetCell is a class that provides a connection between HTML cells and - widgets (an object derived - from wxWindow). You can use it to display things like forms, input boxes etc. - in an HTML window. + widgets (an object derived from wxWindow). + You can use it to display things like forms, input boxes etc. in an HTML window. wxHtmlWidgetCell takes care of resizing and moving window. @library{wxhtml} - @category{FIXME} + @category{html} */ class wxHtmlWidgetCell : public wxHtmlCell { @@ -73,13 +51,12 @@ public: Constructor. @param wnd - Connected window. It is parent window must be the wxHtmlWindow object within - which it is displayed! + Connected window. It is parent window @b must be the wxHtmlWindow object + within which it is displayed! @param w Floating width. If non-zero width of wnd window is adjusted so that it is always w percents of parent container's width. (For example w = 100 means - that the window - will always have same width as parent container) + that the window will always have same width as parent container). */ wxHtmlWidgetCell(wxWindow* wnd, int w = 0); }; @@ -89,19 +66,18 @@ public: /** @class wxHtmlCell - Internal data structure. It represents fragments of parsed HTML - page, the so-called @b cell - a word, picture, table, horizontal line and so on. - It is used by wxHtmlWindow and - wxHtmlWinParser to represent HTML page in memory. + Internal data structure. It represents fragments of parsed HTML page, the + so-called @b cell - a word, picture, table, horizontal line and so on. + It is used by wxHtmlWindow and wxHtmlWinParser to represent HTML page in memory. You can divide cells into two groups : @e visible cells with non-zero width and - height and @e helper cells (usually with zero width and height) that - perform special actions such as color or font change. + height and @e helper cells (usually with zero width and height) that perform + special actions such as color or font change. @library{wxhtml} - @category{FIXME} + @category{html} - @see @ref overview_cells "Cells Overview", wxHtmlContainerCell + @see @ref overview_html_cells, wxHtmlContainerCell */ class wxHtmlCell : public wxObject { @@ -112,13 +88,17 @@ public: wxHtmlCell(); /** - This method is used to adjust pagebreak position. The parameter is - variable that contains y-coordinate of page break (= horizontal line that - should not be crossed by words, images etc.). If this cell cannot be divided - into two pieces (each one on another page) then it moves the pagebreak - few pixels up. - Returns @true if pagebreak was modified, @false otherwise + This method is used to adjust pagebreak position. + The parameter is variable that contains y-coordinate of page break + (= horizontal line that should not be crossed by words, images etc.). + If this cell cannot be divided into two pieces (each one on another page) + then it moves the pagebreak few pixels up. + Returns @true if pagebreak was modified, @false otherwise. + Usage: + @code + while (container->AdjustPagebreak(&p)) {} + @endcode */ virtual bool AdjustPagebreak(int* pagebreak); @@ -130,40 +110,45 @@ public: @param x,y Coordinates of parent's upper left corner (origin). You must add this to m_PosX,m_PosY when passing coordinates to dc's methods - Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) + Example: + @code + dc->DrawText("hello", x + m_PosX, y + m_PosY) + @endcode @param view_y1 - y-coord of the first line visible in window. This is - used to optimize rendering speed + y-coord of the first line visible in window. + This is used to optimize rendering speed @param view_y2 - y-coord of the last line visible in window. This is - used to optimize rendering speed + y-coord of the last line visible in window. + This is used to optimize rendering speed */ - virtual void Draw(wxDC& dc, int x, int y, int view_y1, - int view_y2); + virtual void Draw(wxDC& dc, int x, int y, int view_y1, int view_y2); /** - This method is called instead of Draw() when the - cell is certainly out of the screen (and thus invisible). This is not - nonsense - some tags (like wxHtmlColourCell - or font setter) must be drawn even if they are invisible! + This method is called instead of Draw() when the cell is certainly out of + the screen (and thus invisible). This is not nonsense - some tags (like + wxHtmlColourCell or font setter) must be drawn even if they are invisible! @param dc - Device context to which the cell is to be drawn + Device context to which the cell is to be drawn. @param x,y Coordinates of parent's upper left corner. You must add this to m_PosX,m_PosY when passing coordinates to dc's methods - Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) + Example: + @code + dc->DrawText("hello", x + m_PosX, y + m_PosY) + @endcode */ virtual void DrawInvisible(wxDC& dc, int x, int y); /** - Returns pointer to itself if this cell matches condition (or if any of the cells - following in the list matches), @NULL otherwise. - (In other words if you call top-level container's Find it will + Returns pointer to itself if this cell matches condition (or if any of the + cells following in the list matches), @NULL otherwise. + (In other words if you call top-level container's Find() it will return pointer to the first cell that matches the condition) + It is recommended way how to obtain pointer to particular cell or - to cell of some type (e.g. wxHtmlAnchorCell reacts on - wxHTML_COND_ISANCHOR condition) + to cell of some type (e.g. wxHtmlAnchorCell reacts on wxHTML_COND_ISANCHOR + condition). @param condition Unique integer identifier of condition @@ -175,16 +160,17 @@ public: /** Returns descent value of the cell (m_Descent member). See explanation: + @image html descent.png */ int GetDescent() const; /** Returns pointer to the first cell in the list. - You can then use child's GetNext() - method to obtain pointer to the next cell in list. + You can then use child's GetNext() method to obtain pointer to the next + cell in list. + @note This shouldn't be used by the end user. If you need some way of - finding particular cell in the list, try Find() method - instead. + finding particular cell in the list, try Find() method instead. */ virtual wxHtmlCell* GetFirstChild() const; @@ -194,14 +180,13 @@ public: int GetHeight() const; /** - Returns unique cell identifier if there is any, empty string otherwise. + Returns unique cell identifier if there is any, the empty string otherwise. */ virtual wxString GetId() const; /** Returns hypertext link if associated with this cell or @NULL otherwise. - See wxHtmlLinkInfo. - (Note: this makes sense only for visible tags). + See wxHtmlLinkInfo. (Note: this makes sense only for visible tags). @param x,y Coordinates of position where the user pressed mouse button. @@ -250,22 +235,21 @@ public: /** This method performs two actions: - adjusts the cell's width according to the fact that maximal possible width is - @e w. - (this has sense when working with horizontal lines, tables etc.) - prepares layout (=fill-in m_PosX, m_PosY (and sometimes m_Height) members) - based on actual width @e w - It must be called before displaying cells structure because - m_PosX and m_PosY are undefined (or invalid) - before calling Layout. + -# adjusts the cell's width according to the fact that maximal possible + width is @e w. (this has sense when working with horizontal lines, tables etc.) + -# prepares layout (=fill-in m_PosX, m_PosY (and sometimes m_Height) members) + based on actual width @e w + + It must be called before displaying cells structure because m_PosX and + m_PosY are undefined (or invalid) before calling Layout(). */ virtual void Layout(int w); /** - This function is simple event handler. Each time the user clicks mouse button - over a cell within wxHtmlWindow this method of that - cell is called. Default behavior is to call - wxHtmlWindow::LoadPage. + This function is simple event handler. + Each time the user clicks mouse button over a cell within wxHtmlWindow + this method of that cell is called. + Default behavior is to call wxHtmlWindow::LoadPage. @param window interface to the parent HTML window @@ -275,6 +259,11 @@ public: mouse event that triggered the call @return @true if a link was clicked, @false otherwise. + + @since 2.7.0 (before OnMouseClick() method served a similar purpose). + + @note + If you need more "advanced" event handling you should use wxHtmlBinderCell instead. */ virtual bool ProcessMouseClick(wxHtmlWindowInterface* window, const wxPoint& pos, @@ -286,8 +275,8 @@ public: void SetId(const wxString& id); /** - Sets the hypertext link associated with this cell. (Default value - is wxHtmlLinkInfo("", "") (no link)) + Sets the hypertext link associated with this cell. + (Default value is wxHtmlLinkInfo("", "") (no link)) */ void SetLink(const wxHtmlLinkInfo& link); @@ -298,8 +287,8 @@ public: void SetNext(wxHtmlCell cell); /** - Sets parent container of this cell. This is called from - wxHtmlContainerCell::InsertCell. + Sets parent container of this cell. + This is called from wxHtmlContainerCell::InsertCell. */ void SetParent(wxHtmlContainerCell p); @@ -318,9 +307,9 @@ public: contain more cells in it. It is heavily used in the wxHTML layout algorithm. @library{wxhtml} - @category{FIXME} + @category{html} - @see @ref overview_cells "Cells Overview" + @see @ref overview_html_cells */ class wxHtmlContainerCell : public wxHtmlCell { @@ -342,17 +331,16 @@ public: /** Returns the background colour of the container or @c wxNullColour if no - background - colour is set. + background colour is set. */ wxColour GetBackgroundColour(); /** Returns the indentation. @a ind is one of the @b wxHTML_INDENT_* constants. - @note You must call GetIndentUnits() - with same @a ind parameter in order to correctly interpret the returned integer - value. - It is NOT always in pixels! + + @note You must call GetIndentUnits() with same @a ind parameter in order + to correctly interpret the returned integer value. + It is NOT always in pixels! */ int GetIndent(int ind) const; @@ -363,69 +351,27 @@ public: int GetIndentUnits(int ind) const; /** - Inserts new cell into the container. + Inserts a new cell into the container. */ void InsertCell(wxHtmlCell cell); /** Sets the container's alignment (both horizontal and vertical) according to - the values stored in @e tag. (Tags @c ALIGN parameter is extracted.) In fact - it is only a front-end to SetAlignHor() - and SetAlignVer(). + the values stored in @e tag. (Tags @c ALIGN parameter is extracted.) + In fact it is only a front-end to SetAlignHor() and SetAlignVer(). */ void SetAlign(const wxHtmlTag& tag); /** - Sets the container's @e horizontal alignment. During wxHtmlCell::Layout - each line is aligned according to @a al value. + Sets the container's @e horizontal alignment. + During wxHtmlCell::Layout each line is aligned according to @a al value. @param al new horizontal alignment. May be one of these values: - - - - - - - wxHTML_ALIGN_LEFT - - - - - lines are left-aligned (default) - - - - - - wxHTML_ALIGN_JUSTIFY - - - - - lines are justified - - - - - - wxHTML_ALIGN_CENTER - - - - - lines are centered - - - - - - wxHTML_ALIGN_RIGHT - - - - - lines are right-aligned + - wxHTML_ALIGN_LEFT: lines are left-aligned (default) + - wxHTML_ALIGN_JUSTIFY: lines are justified + - wxHTML_ALIGN_CENTER: lines are centered + - wxHTML_ALIGN_RIGHT: lines are right-aligned */ void SetAlignHor(int al); @@ -434,40 +380,11 @@ public: @param al new vertical alignment. May be one of these values: + - wxHTML_ALIGN_BOTTOM: cells are over the line (default) + - wxHTML_ALIGN_CENTER: cells are centered on line + - wxHTML_ALIGN_TOP: cells are under the line - - - - - - wxHTML_ALIGN_BOTTOM - - - - - cells are over the line (default) - - - - - - wxHTML_ALIGN_CENTER - - - - - cells are centered on line - - - - - - wxHTML_ALIGN_TOP - - - - - cells are under the line + @image html alignv.png */ void SetAlignVer(int al); @@ -489,187 +406,82 @@ public: /** Sets the indentation (free space between borders of container and subcells). + @image html indent.png + @param i Indentation value. @param what Determines which of the four borders we're setting. It is OR combination of following constants: - - - - - - - wxHTML_INDENT_TOP - - - - - top border - - - - - - wxHTML_INDENT_BOTTOM - - - - - bottom - - - - - - wxHTML_INDENT_LEFT - - - - - left - - - - - - wxHTML_INDENT_RIGHT - - - - - right - - - - - - wxHTML_INDENT_HORIZONTAL - - - - - left and right - - - - - - wxHTML_INDENT_VERTICAL - - - - - top and bottom - - - - - - wxHTML_INDENT_ALL - - - - - all 4 borders + - wxHTML_INDENT_TOP: top border + - wxHTML_INDENT_BOTTOM: bottom + - wxHTML_INDENT_LEFT: left + - wxHTML_INDENT_RIGHT: right + - wxHTML_INDENT_HORIZONTAL: left and right + - wxHTML_INDENT_VERTICAL: top and bottom + - wxHTML_INDENT_ALL: all 4 borders @param units - Units of i. This parameter affects interpretation of value. - - - - - - - wxHTML_UNITS_PIXELS - - - - - i is number of pixels - - - - - - wxHTML_UNITS_PERCENT - - - - - i is interpreted as percents of width - of parent container + Units of i. This parameter affects interpretation of value. + - wxHTML_UNITS_PIXELS: @a i is number of pixels + - wxHTML_UNITS_PERCENT: @a i is interpreted as percents of width + of parent container */ void SetIndent(int i, int what, int units = wxHTML_UNITS_PIXELS); /** Sets minimal height of the container. - When container's wxHtmlCell::Layout is called, m_Height - is set depending on layout of subcells to the height of area covered - by layed-out subcells. Calling this method guarantees you that the height - of container is never smaller than @a h - even if the subcells cover - much smaller area. + When container's wxHtmlCell::Layout is called, m_Height is set depending + on layout of subcells to the height of area covered by layed-out subcells. + Calling this method guarantees you that the height of container is never + smaller than @a h - even if the subcells cover much smaller area. @param h The minimal height. @param align If height of the container is lower than the minimum height, empty space - must be inserted - somewhere in order to ensure minimal height. This parameter is one of - wxHTML_ALIGN_TOP, - wxHTML_ALIGN_BOTTOM, wxHTML_ALIGN_CENTER. It refers to the contents, not to - the + must be inserted somewhere in order to ensure minimal height. + This parameter is one of @c wxHTML_ALIGN_TOP, @c wxHTML_ALIGN_BOTTOM, + @c wxHTML_ALIGN_CENTER. It refers to the contents, not to the empty place. */ void SetMinHeight(int h, int align = wxHTML_ALIGN_TOP); - //@{ /** Sets floating width adjustment. + The normal behaviour of container is that its width is the same as the width of parent container (and thus you can have only one sub-container per line). - You can change this by setting FWA. - @a pixel_scale is number of real pixels that equals to 1 HTML pixel. + You can change this by setting the floating width adjustment. @param w Width of the container. If the value is negative it means - complement to full width of parent container (e.g. - SetWidthFloat(-50, wxHTML_UNITS_PIXELS) sets the width - of container to parent's width minus 50 pixels. This is useful when - creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50)) + complement to full width of parent container. + E.g. @code SetWidthFloat(-50, wxHTML_UNITS_PIXELS) @endcode sets the + width of container to parent's width minus 50 pixels. This is useful when + creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50). @param units Units of w This parameter affects the interpretation of value. + - wxHTML_UNITS_PIXELS: @a w is number of pixels + - wxHTML_UNITS_PERCENT: @a w is interpreted as percents of width + of parent container + */ + void SetWidthFloat(int w, int units); + /** + Sets floating width adjustment. + The normal behaviour of container is that its width is the same as the width of + parent container (and thus you can have only one sub-container per line). + You can change this by setting the floating width adjustment. - - - - wxHTML_UNITS_PIXELS - - - - - w is number of pixels - - - - - - wxHTML_UNITS_PERCENT - - - - - w is interpreted as percents of width - of parent container @param tag - In the second version of method, w and units - info is extracted from tag's WIDTH parameter. + In the second version of method, @a w and @a units info is extracted + from tag's WIDTH parameter. + @param pixel_scale + This is number of real pixels that equals to 1 HTML pixel. */ - void SetWidthFloat(int w, int units); void SetWidthFloat(const wxHtmlTag& tag, double pixel_scale = 1.0); - //@} }; @@ -677,50 +489,49 @@ public: /** @class wxHtmlLinkInfo - This class stores all necessary information about hypertext - links (as represented by @c A tag in HTML documents). In - current implementation it stores URL and target frame name. - @e Note that frames are not currently supported by wxHTML! + This class stores all necessary information about hypertext links + (as represented by \ tag in HTML documents). + In current implementation it stores URL and target frame name. + + @note Frames are not currently supported by wxHTML! @library{wxhtml} - @category{FIXME} + @category{html} */ class wxHtmlLinkInfo : public wxObject { public: - //@{ /** - Construct hypertext link from HREF (aka URL) and TARGET (name of target - frame). + Default ctor. */ wxHtmlLinkInfo(); + + /** + Construct hypertext link from HREF (aka URL) and TARGET (name of target frame). + */ wxHtmlLinkInfo(const wxString& href, const wxString& target = wxEmptyString); - //@} /** - Return pointer to event that generated OnLinkClicked event. Valid - only within wxHtmlWindow::OnLinkClicked, - @NULL otherwise. + Return pointer to event that generated OnLinkClicked() event. + Valid only within wxHtmlWindow::OnLinkClicked, @NULL otherwise. */ const wxMouseEvent* GetEvent() const; /** - Return @e HREF value of the @c A tag. + Return @e HREF value of the \ tag. */ wxString GetHref() const; /** - Return pointer to the cell that was clicked. Valid - only within wxHtmlWindow::OnLinkClicked, - @NULL otherwise. + Return pointer to the cell that was clicked. + Valid only within wxHtmlWindow::OnLinkClicked, @NULL otherwise. */ const wxHtmlCell* GetHtmlCell() const; /** - Return @e TARGET value of the @c A tag (this value - is used to specify in which frame should be the page pointed - by @ref gethref() Href opened). + Return @e TARGET value of the \ tag (this value is used to specify + in which frame should be the page pointed by @ref GetHref() Href opened). */ wxString GetTarget() const; }; diff --git a/interface/wx/html/htmlfilt.h b/interface/wx/html/htmlfilt.h index 695ab88d7c..e5ef78c179 100644 --- a/interface/wx/html/htmlfilt.h +++ b/interface/wx/html/htmlfilt.h @@ -13,9 +13,9 @@ It allows you to read and display files of different file formats. @library{wxhtml} - @category{FIXME} + @category{html} - @see Overview() + @see @ref overview_html_filters */ class wxHtmlFilter : public wxObject { @@ -28,12 +28,25 @@ public: /** Returns @true if this filter is capable of reading file @e file. Example: + @code + bool MyFilter::CanRead(const wxFSFile& file) + { + return (file.GetMimeType() == "application/x-ugh"); + } + @endcode */ virtual bool CanRead(const wxFSFile& file) const = 0; /** Reads the file and returns string with HTML document. Example: + @code + wxString MyImgFilter::ReadFile(const wxFSFile& file) + { + return ""; + } + @endcode */ virtual wxString ReadFile(const wxFSFile& file) const = 0; }; diff --git a/interface/wx/html/htmlpars.h b/interface/wx/html/htmlpars.h index a5d783a74a..dc97e2f6bf 100644 --- a/interface/wx/html/htmlpars.h +++ b/interface/wx/html/htmlpars.h @@ -9,11 +9,12 @@ /** @class wxHtmlTagHandler + @todo describe me @library{wxhtml} @category{html} - @see Overview(), wxHtmlTag + @see @ref overview_html_handlers, wxHtmlTag */ class wxHtmlTagHandler : public wxObject { @@ -24,8 +25,9 @@ public: wxHtmlTagHandler(); /** - Returns list of supported tags. The list is in uppercase and tags - are delimited by ','. Example : @c "I,B,FONT,P" + Returns list of supported tags. + The list is in uppercase and tags are delimited by ','. + Example: @c "I,B,FONT,P" */ virtual wxString GetSupportedTags() = 0; @@ -33,16 +35,34 @@ public: This is the core method of each handler. It is called each time one of supported tags is detected. @a tag contains all necessary info (see wxHtmlTag for details). - - @return @true if ParseInner was called, @false otherwise. + + Example: + + @code + bool MyHandler::HandleTag(const wxHtmlTag& tag) + { + ... + // change state of parser (e.g. set bold face) + ParseInner(tag); + ... + // restore original state of parser + } + @endcode + + You shouldn't call ParseInner() if the tag is not paired with an ending one. + + @return @true if ParseInner() was called, @false otherwise. */ virtual bool HandleTag(const wxHtmlTag& tag) = 0; /** This method calls parser's wxHtmlParser::DoParsing method for the string between this tag and the paired ending tag: - - In this example, a call to ParseInner (with @a tag pointing to A tag) + @code + ...Hello, world!... + @endcode + + In this example, a call to ParseInner() (with @a tag pointing to A tag) will parse 'Hello, world!'. */ void ParseInner(const wxHtmlTag& tag); @@ -53,11 +73,12 @@ public: */ virtual void SetParser(wxHtmlParser parser); +protected: /** - @b wxHtmlParser* m_Parser This attribute is used to access parent parser. It is protected so that it can't be accessed by user but can be accessed from derived classes. */ + wxHtmlParser* m_Parser; }; @@ -66,14 +87,10 @@ public: @class wxHtmlParser Classes derived from this handle the @b generic parsing of HTML documents: it - scans - the document and divide it into blocks of tags (where one block - consists of beginning and ending tag and of text between these - two tags). + scans the document and divide it into blocks of tags (where one block consists + of beginning and ending tag and of text between these two tags). - It is independent from wxHtmlWindow and can be used as stand-alone parser - (Julian Smart's idea of speech-only HTML viewer or wget-like utility - - see InetGet sample for example). + It is independent from wxHtmlWindow and can be used as stand-alone parser. It uses system of tag handlers to parse the HTML document. Tag handlers are not statically shared by all instances but are created for each @@ -86,8 +103,7 @@ public: @library{wxhtml} @category{html} - @see @ref overview_cells "Cells Overview", @ref overview_handlers "Tag Handlers - Overview", wxHtmlTag + @see @ref overview_html_cells, @ref overview_html_handlers, wxHtmlTag */ class wxHtmlParser { @@ -99,43 +115,46 @@ public: /** This may (and may not) be overwritten in derived class. + This method is called each time new tag is about to be added. - @a tag contains information about the tag. (See wxHtmlTag - for details.) - Default (wxHtmlParser) behaviour is this: - First it finds a handler capable of handling this tag and then it calls - handler's HandleTag method. + @a tag contains information about the tag. (See wxHtmlTag for details.) + + Default (wxHtmlParser) behaviour is this: first it finds a handler capable + of handling this tag and then it calls handler's HandleTag() method. */ virtual void AddTag(const wxHtmlTag& tag); /** - Adds handler to the internal list ( hash table) of handlers. This - method should not be called directly by user but rather by derived class' + Adds handler to the internal list ( hash table) of handlers. + This method should not be called directly by user but rather by derived class' constructor. + This adds the handler to this @b instance of wxHtmlParser, not to - all objects of this class! (Static front-end to AddTagHandler is provided - by wxHtmlWinParser). + all objects of this class! + (Static front-end to AddTagHandler is provided by wxHtmlWinParser). + All handlers are deleted on object deletion. */ virtual void AddTagHandler(wxHtmlTagHandler handler); /** Must be overwritten in derived class. - This method is called by DoParsing() - each time a part of text is parsed. @a txt is NOT only one word, it is - substring of input. It is not formatted or preprocessed (so white spaces are - unmodified). + + This method is called by DoParsing() each time a part of text is parsed. + @a txt is NOT only one word, it is substring of input. + It is not formatted or preprocessed (so white spaces are unmodified). */ virtual void AddWord(const wxString& txt); - //@{ /** - Parses the m_Source from begin_pos to end_pos-1. - (in noparams version it parses whole m_Source) + Parses the m_Source from @a begin_pos to @a end_pos - 1. */ void DoParsing(int begin_pos, int end_pos); + + /** + Parses the whole m_Source. + */ void DoParsing(); - //@} /** This must be called after DoParsing(). @@ -145,14 +164,19 @@ public: /** Returns pointer to the file system. Because each tag handler has reference to it is parent parser it can easily request the file by - calling + calling: + @code + wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg"); + @endcode */ wxFileSystem* GetFS() const; /** - Returns product of parsing. Returned value is result of parsing - of the document. The type of this result depends on internal - representation in derived parser (but it must be derived from wxObject!). + Returns product of parsing. + Returned value is result of parsing of the document. + + The type of this result depends on internal representation in derived + parser (but it must be derived from wxObject!). See wxHtmlWinParser for details. */ virtual wxObject* GetProduct() = 0; @@ -163,8 +187,8 @@ public: wxString* GetSource(); /** - Setups the parser for parsing the @a source string. (Should be overridden - in derived class) + Setups the parser for parsing the @a source string. + (Should be overridden in derived class) */ virtual void InitParser(const wxString& source); @@ -173,66 +197,46 @@ public: from it. This method may return @NULL in one of two cases: either the URL doesn't point to any valid resource or the URL is blocked by overridden implementation of @e OpenURL in derived class. - + @param type Indicates type of the resource. Is one of: - - - - - - - wxHTML_URL_PAGE - - - - - Opening a HTML page. - - - - - - wxHTML_URL_IMAGE - - - - - Opening an image. - - - - - - wxHTML_URL_OTHER - - - - - Opening a resource that doesn't fall into - any other category. + - wxHTML_URL_PAGE: Opening a HTML page. + - wxHTML_URL_IMAGE: Opening an image. + - wxHTML_URL_OTHER: Opening a resource that doesn't fall into + any other category. @param url URL being opened. + + @note + Always use this method in tag handlers instead of GetFS()->OpenFile() + because it can block the URL and is thus more secure. + Default behaviour is to call wxHtmlWindow::OnOpeningURL of the associated + wxHtmlWindow object (which may decide to block the URL or redirect it to + another one),if there's any, and always open the URL if the parser is not + used with wxHtmlWindow. + Returned wxFSFile object is not guaranteed to point to url, it might have + been redirected! */ virtual wxFSFile* OpenURL(wxHtmlURLType type, const wxString& url); /** Proceeds parsing of the document. This is end-user method. You can simply - call it when you need to obtain parsed output (which is parser-specific) + call it when you need to obtain parsed output (which is parser-specific). + The method does these things: - calls @ref initparser() InitParser(source) - calls DoParsing() - calls GetProduct() - calls DoneParser() - returns value returned by GetProduct - You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly. + -# calls InitParser(source) + -# calls DoParsing() + -# calls GetProduct() + -# calls DoneParser() + -# returns value returned by GetProduct() + + You shouldn't use InitParser(), DoParsing(), GetProduct() or DoneParser() directly. */ wxObject* Parse(const wxString& source); /** - Restores parser's state before last call to - PushTagHandler(). + Restores parser's state before last call to PushTagHandler(). */ void PopTagHandler(); @@ -240,28 +244,60 @@ public: Forces the handler to handle additional tags (not returned by wxHtmlTagHandler::GetSupportedTags). The handler should already be added to this parser. - + @param handler the handler @param tags - List of tags (in same format as GetSupportedTags's return value). The parser - will redirect these tags to handler (until call to PopTagHandler). + List of tags (in same format as GetSupportedTags()'s return value). + The parser will redirect these tags to handler (until call to PopTagHandler()). + + Example: + + Imagine you want to parse following pseudo-html structure: + @code + + + + + + + + + @endcode + + It is obvious that you cannot use only one tag handler for \ tag. + Instead you must use context-sensitive handlers for \ inside \ + and \ inside \. + This is the preferred solution: + + @code + TAG_HANDLER_BEGIN(MYITEM, "MYITEMS") + TAG_HANDLER_PROC(tag) + { + // ...something... + + m_Parser -> PushTagHandler(this, "PARAM"); + ParseInner(tag); + m_Parser -> PopTagHandler(); + + // ...something... + } + TAG_HANDLER_END(MYITEM) + @endcode */ void PushTagHandler(wxHtmlTagHandler* handler, const wxString& tags); /** - Sets the virtual file system that will be used to request additional - files. (For example @c IMG tag handler requests wxFSFile with the - image data.) + Sets the virtual file system that will be used to request additional files. + (For example @c IMG tag handler requests wxFSFile with the image data.) */ void SetFS(wxFileSystem fs); /** - Call this function to interrupt parsing from a tag handler. No more tags - will be parsed afterward. This function may only be called from - Parse() or any function called - by it (i.e. from tag handlers). + Call this function to interrupt parsing from a tag handler. + No more tags will be parsed afterward. This function may only be called + from Parse() or any function called by it (i.e. from tag handlers). */ virtual void StopParsing(); }; diff --git a/interface/wx/html/htmltag.h b/interface/wx/html/htmltag.h index 0f2c67a4a3..e5ef38cb44 100644 --- a/interface/wx/html/htmltag.h +++ b/interface/wx/html/htmltag.h @@ -10,7 +10,7 @@ @class wxHtmlTag This class represents a single HTML tag. - It is used by @ref overview_handlers "tag handlers". + It is used by @ref overview_html_handlers "tag handlers". @library{wxhtml} @category{html} @@ -21,7 +21,7 @@ protected: /** Constructor. You will probably never have to construct a wxHtmlTag object yourself. Feel free to ignore the constructor parameters. - Have a look at src/html/htmlpars.cpp if you're interested in creating it. + Have a look at @c src/html/htmlpars.cpp if you're interested in creating it. */ wxHtmlTag(wxHtmlTag* parent, const wxString* source, const const_iterator& pos, const const_iterator& end_pos, @@ -30,39 +30,51 @@ protected: public: /** Returns a string containing all parameters. - Example : tag contains @c FONT SIZE=+2 COLOR="#000000". Call to - tag.GetAllParams() would return @c SIZE=+2 COLOR="#000000". + Example: tag contains \. + Call to tag.GetAllParams() would return @c 'SIZE=+2 COLOR="#000000"'. */ const wxString GetAllParams() const; /** Returns beginning position of the text @e between this tag and paired - ending tag. - See explanation (returned position is marked with '|'): + ending tag. See explanation (returned position is marked with '|'): + @code + bla bla bla bla bla internal text bla bla + | + @endcode + @deprecated @todo provide deprecation description */ int GetBeginPos() const; /** Returns ending position of the text @e between this tag and paired - ending tag. - See explanation (returned position is marked with '|'): + ending tag. See explanation (returned position is marked with '|'): + @code + bla bla bla bla bla internal text bla bla + | + @endcode + @deprecated @todo provide deprecation description */ int GetEndPos1() const; /** Returns ending position 2 of the text @e between this tag and paired - ending tag. - See explanation (returned position is marked with '|'): + ending tag. See explanation (returned position is marked with '|'): + @code + bla bla bla bla bla internal text bla bla + | + @endcode + @deprecated @todo provide deprecation description */ int GetEndPos2() const; /** Returns tag's name. The name is always in uppercase and it doesn't contain - " or '/' characters. (So the name of @c FONT SIZE=+2 tag is "FONT" - and name of @c /table is "TABLE") + " or '/' characters. (So the name of \ tag is "FONT" + and name of \ is "TABLE"). */ wxString GetName() const; @@ -74,12 +86,26 @@ public: The parameter's name. @param with_quotes @true if you want to get quotes as well. See example. + + Example: + @code + ... + // you have wxHtmlTag variable tag which is equal to the + // HTML tag + dummy = tag.GetParam("SIZE"); + // dummy == "+2" + dummy = tag.GetParam("COLOR"); + // dummy == "#0000FF" + dummy = tag.GetParam("COLOR", true); + // dummy == "\"#0000FF\"" -- see the difference!! + @endcode */ wxString GetParam(const wxString& par, bool with_quotes = false) const; /** Interprets tag parameter @a par as colour specification and saves its value - into wxColour variable pointed by @e clr. + into wxColour variable pointed by @a clr. + Returns @true on success and @false if @a par is not colour specification or if the tag has no such parameter. */ @@ -87,7 +113,8 @@ public: /** Interprets tag parameter @a par as an integer and saves its value - into int variable pointed by @e value. + into int variable pointed by @a value. + Returns @true on success and @false if @a par is not an integer or if the tag has no such parameter. */ @@ -96,16 +123,24 @@ public: /** Returns @true if this tag is paired with ending tag, @false otherwise. See the example of HTML document: + @code + + Hello

+ How are you? +

This is centered...

+ Oops
Oooops! + + @endcode In this example tags HTML and BODY have ending tags, first P and BR - doesn't have ending tag while the second P has. The third P tag (which - is ending itself) of course doesn't have ending tag. + doesn't have ending tag while the second P has. + The third P tag (which is ending itself) of course doesn't have ending tag. */ bool HasEnding() const; /** Returns @true if the tag has a parameter of the given name. - Example : @c FONT SIZE=+2 COLOR="\#FF00FF" has two parameters named + Example: \ has two parameters named "SIZE" and "COLOR". @param par @@ -116,9 +151,8 @@ public: /** This method scans the given parameter. Usage is exactly the same as sscanf's usage except that you don't pass a string but a parameter name as the first - argument - and you can only retrieve one value (i.e. you can use only one "%" element - in @e format). + argument and you can only retrieve one value (i.e. you can use only one "%" + element in @a format). @param par The name of the tag you want to query @@ -127,7 +161,6 @@ public: @param value pointer to a variable to store the value in */ - wxString ScanParam(const wxString& par, const wxChar* format, - void* value) const; + wxString ScanParam(const wxString& par, const wxChar* format, void* value) const; }; diff --git a/interface/wx/html/htmlwin.h b/interface/wx/html/htmlwin.h index b15356dda6..50efdf2166 100644 --- a/interface/wx/html/htmlwin.h +++ b/interface/wx/html/htmlwin.h @@ -9,18 +9,20 @@ /** @class wxHtmlWindow - wxHtmlWindow is probably the only class you will directly use - unless you want to do something special (like adding new tag - handlers or MIME filters). + wxHtmlWindow is probably the only class you will directly use unless you want + to do something special (like adding new tag handlers or MIME filters). - The purpose of this class is to display HTML pages (either local - file or downloaded via HTTP protocol) in a window. The width - of the window is constant - given in the constructor - and virtual height + The purpose of this class is to display HTML pages (either local file or + downloaded via HTTP protocol) in a window. + The width of the window is constant - given in the constructor - and virtual height is changed dynamically depending on page size. - Once the window is created you can set its content by calling - @ref wxHtmlWindow::setpage SetPage(text), - @ref wxHtmlWindow::loadpage LoadPage(filename) or - wxHtmlWindow::LoadFile. + Once the window is created you can set its content by calling SetPage(text), + LoadPage(filename) or wxHtmlWindow::LoadFile. + + @note + wxHtmlWindow uses the wxImage class for displaying images. + Don't forget to initialize all image formats you need before loading any page! + (See ::wxInitAllImageHandlers and wxImage::AddHandler.) @beginStyleTable @style{wxHW_SCROLLBAR_NEVER} @@ -32,6 +34,16 @@ Don't allow the user to select text. @endStyleTable + + @beginEventTable{wxHtmlCellEvent, wxHtmlLinkEvent} + @event{EVT_HTML_CELL_CLICKED(id, func)} + A wxHtmlCell was clicked. + @event{EVT_HTML_CELL_HOVER(id, func)} + The mouse passed over a wxHtmlCell. + @event{EVT_HTML_LINK_CLICKED(id, func)} + A wxHtmlCell which contains an hyperlink was clicked. + @endEventTable + @library{wxhtml} @category{html} @@ -40,15 +52,15 @@ class wxHtmlWindow : public wxScrolledWindow { public: - //@{ /** - Constructor. The parameters are the same as wxScrolled::wxScrolled() - constructor. - - @param style - Window style. See wxHtmlWindow. + Default ctor. */ wxHtmlWindow(); + + /** + Constructor. + The parameters are the same as wxScrolled::wxScrolled() constructor. + */ wxHtmlWindow(wxWindow parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -57,11 +69,11 @@ public: //@} /** - Adds @ref overview_filters "input filter" to the static list of available + Adds @ref overview_html_filters "input filter" to the static list of available filters. These filters are present by default: - @c text/html MIME type - @c image/* MIME types - Plain Text filter (this filter is used if no other filter matches) + - @c text/html MIME type + - @c image/* MIME types + - Plain Text filter (this filter is used if no other filter matches) */ static void AddFilter(wxHtmlFilter filter); @@ -77,29 +89,28 @@ public: /** Returns pointer to the top-level container. - See also: @ref overview_cells "Cells Overview", - @ref overview_printing + + @see @ref overview_html_cells, @ref overview_printing */ wxHtmlContainerCell* GetInternalRepresentation() const; /** - Returns anchor within currently opened page - (see wxHtmlWindow::GetOpenedPage). - If no page is opened or if the displayed page wasn't - produced by call to LoadPage, empty string is returned. + Returns anchor within currently opened page (see wxHtmlWindow::GetOpenedPage). + If no page is opened or if the displayed page wasn't produced by call to + LoadPage(), empty string is returned. */ wxString GetOpenedAnchor() const; /** - Returns full location of the opened page. If no page is opened or if the - displayed page wasn't - produced by call to LoadPage, empty string is returned. + Returns full location of the opened page. + If no page is opened or if the displayed page wasn't produced by call to + LoadPage(), empty string is returned. */ wxString GetOpenedPage() const; /** Returns title of the opened page or wxEmptyString if current page does not - contain @c TITLE tag. + contain \ tag. */ wxString GetOpenedPageTitle() const; @@ -109,20 +120,20 @@ public: wxFrame* GetRelatedFrame() const; /** - Moves back to the previous page. (each page displayed using - LoadPage() is stored in history list.) + Moves back to the previous page. + (each page displayed using LoadPage() is stored in history list.) */ bool HistoryBack(); /** - Returns @true if it is possible to go back in the history (i.e. HistoryBack() - won't fail). + Returns @true if it is possible to go back in the history + (i.e. HistoryBack() won't fail). */ bool HistoryCanBack(); /** - Returns @true if it is possible to go forward in the history (i.e. HistoryBack() - won't fail). + Returns @true if it is possible to go forward in the history + (i.e. HistoryBack() won't fail). */ bool HistoryCanForward(); @@ -146,12 +157,12 @@ public: bool LoadFile(const wxFileName& filename); /** - Unlike SetPage this function first loads HTML page from @a location + Unlike SetPage() this function first loads HTML page from @a location and then displays it. See example: @param location - The address of document. See wxFileSystem for details on address format and - behaviour of "opener". + The address of document. + See wxFileSystem for details on address format and behaviour of "opener". @return @false if an error occurred, @true otherwise @@ -160,80 +171,58 @@ public: virtual bool LoadPage(const wxString& location); /** - Called when user clicks on hypertext link. Default behaviour is to emit a - wxHtmlLinkEvent and, if the event was not processed - or skipped, call LoadPage() and do nothing else. + Called when user clicks on hypertext link. + Default behaviour is to emit a wxHtmlLinkEvent and, if the event was not + processed or skipped, call LoadPage() and do nothing else. + Overloading this method is deprecated; intercept the event instead. + Also see wxHtmlLinkInfo. */ virtual void OnLinkClicked(const wxHtmlLinkInfo& link); /** Called when an URL is being opened (either when the user clicks on a link or - an image is loaded). The URL will be opened only if OnOpeningURL returns - @c wxHTML_OPEN. This method is called by - wxHtmlParser::OpenURL. - You can override OnOpeningURL to selectively block some - URLs (e.g. for security reasons) or to redirect them elsewhere. Default - behaviour is to always return @c wxHTML_OPEN. + an image is loaded). The URL will be opened only if OnOpeningURL() returns + @c wxHTML_OPEN. This method is called by wxHtmlParser::OpenURL. + + You can override OnOpeningURL() to selectively block some URLs + (e.g. for security reasons) or to redirect them elsewhere. + Default behaviour is to always return @c wxHTML_OPEN. @param type Indicates type of the resource. Is one of - - - - - - - wxHTML_URL_PAGE - - - - - Opening a HTML page. - - - - - - wxHTML_URL_IMAGE - - - - - Opening an image. - - - - - - wxHTML_URL_OTHER - - - - - Opening a resource that doesn't fall into - any other category. + - wxHTML_URL_PAGE: Opening a HTML page. + - wxHTML_URL_IMAGE: Opening an image. + - wxHTML_URL_OTHER: Opening a resource that doesn't fall into + any other category. @param url URL being opened. @param redirect Pointer to wxString variable that must be filled with an - URL if OnOpeningURL returns wxHTML_REDIRECT. + URL if OnOpeningURL() returns @c wxHTML_REDIRECT. + + The return value is: + - wxHTML_OPEN: Open the URL. + - wxHTML_BLOCK: Deny access to the URL, wxHtmlParser::OpenURL will return @NULL. + - wxHTML_REDIRECT: Don't open url, redirect to another URL. + OnOpeningURL() must fill *redirect with the new URL. + OnOpeningURL() will be called again on returned URL. */ virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type, const wxString& url, wxString* redirect) const; /** - Called on parsing @c TITLE tag. + Called on parsing \ tag. */ virtual void OnSetTitle(const wxString& title); /** This reads custom settings from wxConfig. It uses the path 'path' if given, otherwise it saves info into currently selected path. - The values are stored in sub-path @c wxHtmlWindow - Read values: all things set by SetFonts, SetBorders. + The values are stored in sub-path @c wxHtmlWindow. + Read values: all things set by SetFonts(), SetBorders(). @param cfg wxConfig from which you want to read the configuration. @@ -261,24 +250,24 @@ public: void SelectLine(const wxPoint& pos); /** - Selects the word at position @e pos. Note that @e pos - is relative to the top of displayed page, not to window's origin, use - wxScrolled::CalcUnscrolledPosition() - to convert physical coordinate. + Selects the word at position @a pos. + Note that @a pos is relative to the top of displayed page, not to window's + origin, use wxScrolled::CalcUnscrolledPosition() to convert physical coordinate. @see SelectAll(), SelectLine() */ void SelectWord(const wxPoint& pos); /** - Returns current selection as plain text. Returns empty string if no text - is currently selected. + Returns current selection as plain text. + Returns empty string if no text is currently selected. */ wxString SelectionToText(); /** - This function sets the space between border of window and HTML contents. See - image: + This function sets the space between border of window and HTML contents. + See image: + @image html border.png @param b indentation from borders in pixels @@ -294,12 +283,16 @@ public: platform-specific face name. Examples are "helvetica" under Unix or "Times New Roman" under Windows. @param fixed_face - The same thing for fixed face ( TT../TT ) + The same thing for fixed face ( \..\ ) @param sizes This is an array of 7 items of int type. The values represent size of font with HTML size from -2 to +4 - ( FONT SIZE=-2 to FONT SIZE=+4 ). Default sizes are used if sizes - is @NULL. + ( \ to \ ). + Default sizes are used if sizes is @NULL. + + Default font sizes are defined by constants wxHTML_FONT_SIZE_1, + wxHTML_FONT_SIZE_2, ..., wxHTML_FONT_SIZE_7. + Note that they differ among platforms. Default face names are empty strings. */ void SetFonts(const wxString& normal_face, const wxString& fixed_face, @@ -308,9 +301,11 @@ public: /** Sets HTML page and display it. This won't @b load the page!! It will display the @e source. See example: + @code + htmlwin -> SetPage("Hello, world!"); + @endcode - If you want to load a document from some location use - LoadPage() instead. + If you want to load a document from some location use LoadPage() instead. @param source The HTML document source to be displayed. @@ -320,16 +315,16 @@ public: virtual bool SetPage(const wxString& source); /** - Sets the frame in which page title will be displayed. @a format is format of - frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s. This - %s is substituted with HTML page title. + Sets the frame in which page title will be displayed. + @a format is the format of the frame title, e.g. "HtmlHelp : %s". + It must contain exactly one %s. + This %s is substituted with HTML page title. */ void SetRelatedFrame(wxFrame* frame, const wxString& format); /** - @b After calling SetRelatedFrame(), - this sets statusbar slot where messages will be displayed. - (Default is -1 = no messages.) + @b After calling SetRelatedFrame(), this sets statusbar slot where messages + will be displayed. (Default is -1 = no messages.) @param index Statusbar slot number (0..n) @@ -356,11 +351,13 @@ public: wxString ToText(); /** - Saves custom settings into wxConfig. It uses the path 'path' - if given, otherwise it saves info into currently selected path. - Regardless of whether the path is given or not, the function creates sub-path - @c wxHtmlWindow. - Saved values: all things set by SetFonts, SetBorders. + Saves custom settings into wxConfig. + It uses the path 'path' if given, otherwise it saves info into currently + selected path. + Regardless of whether the path is given or not, the function creates + sub-path @c wxHtmlWindow. + + Saved values: all things set by SetFonts(), SetBorders(). @param cfg wxConfig to which you want to save the configuration. @@ -374,17 +371,19 @@ protected: /** This method is called when a mouse button is clicked inside wxHtmlWindow. - The default behaviour is to emit a wxHtmlCellEvent - and, if the event was not processed or skipped, call - OnLinkClicked() if the cell contains an + The default behaviour is to emit a wxHtmlCellEvent and, if the event was + not processed or skipped, call OnLinkClicked() if the cell contains an hypertext link. + Overloading this method is deprecated; intercept the event instead. @param cell The cell inside which the mouse was clicked, always a simple (i.e. non-container) cell - @param x, y - The logical coordinates of the click point + @param x + The logical x coordinate of the click point + @param y + The logical y coordinate of the click point @param event The mouse event containing other information about the click @@ -396,13 +395,16 @@ protected: /** This method is called when a mouse moves over an HTML cell. Default behaviour is to emit a wxHtmlCellEvent. + Overloading this method is deprecated; intercept the event instead. @param cell The cell inside which the mouse is currently, always a simple (i.e. non-container) cell - @param x, y - The logical coordinates of the click point + @param x + The logical x coordinate of the click point + @param y + The logical y coordinate of the click point */ virtual void OnCellMouseHover(wxHtmlCell cell, wxCoord x, wxCoord y); }; @@ -414,8 +416,13 @@ protected: This event class is used for the events generated by wxHtmlWindow. + @beginEventTable{wxHtmlLinkEvent} + @event{EVT_HTML_LINK_CLICKED(id, func)} + User clicked on an hyperlink. + @endEventTable + @library{wxhtml} - @category{FIXME} + @category{html} */ class wxHtmlLinkEvent : public wxCommandEvent { @@ -426,10 +433,10 @@ public: wxHyperlinkEvent(int id, const wxHtmlLinkInfo& linkinfo); /** - Returns the wxHtmlLinkInfo which contains info about the cell clicked and the - hyperlink it contains. + Returns the wxHtmlLinkInfo which contains info about the cell clicked + and the hyperlink it contains. */ - const wxHtmlLinkInfo GetLinkInfo() const; + const wxHtmlLinkInfo& GetLinkInfo() const; }; @@ -439,8 +446,16 @@ public: This event class is used for the events generated by wxHtmlWindow. + @beginEventTable{wxHtmlCellEvent} + @event{EVT_HTML_CELL_HOVER(id, func)} + User moved the mouse over a wxHtmlCell. + @event{EVT_HTML_CELL_CLICKED(id, func)} + User clicked on a wxHtmlCell. When handling this event, remember to use + wxHtmlCell::SetLinkClicked(true) if the cell contains a link. + @endEventTable + @library{wxhtml} - @category{FIXME} + @category{html} */ class wxHtmlCellEvent : public wxCommandEvent { @@ -458,8 +473,7 @@ public: wxHtmlCell* GetCell() const; /** - Returns @true if @ref setlinkclicked() SetLinkClicked(@true) has previously - been called; + Returns @true if SetLinkClicked(@true) has previously been called; @false otherwise. */ bool GetLinkClicked() const; @@ -470,11 +484,11 @@ public: wxPoint GetPoint() const; /** - Call this function with @c linkclicked set to @true if the cell which has - been clicked contained a link or - @false otherwise (which is the default). With this function the event handler - can return info to the - wxHtmlWindow which sent the event. + Call this function with @a linkclicked set to @true if the cell which has + been clicked contained a link or @false otherwise (which is the default). + + With this function the event handler can return info to the wxHtmlWindow + which sent the event. */ bool SetLinkClicked(bool linkclicked); }; diff --git a/interface/wx/html/htmprint.h b/interface/wx/html/htmprint.h index ca104ba51d..7748f3915e 100644 --- a/interface/wx/html/htmprint.h +++ b/interface/wx/html/htmprint.h @@ -9,13 +9,12 @@ /** @class wxHtmlDCRenderer - This class can render HTML document into a specified area of a DC. You can use - it - in your own printing code, although use of wxHtmlEasyPrinting + This class can render HTML document into a specified area of a DC. + You can use it in your own printing code, although use of wxHtmlEasyPrinting or wxHtmlPrintout is strongly recommended. @library{wxhtml} - @category{FIXME} + @category{html} */ class wxHtmlDCRenderer : public wxObject { @@ -26,58 +25,68 @@ public: wxHtmlDCRenderer(); /** - Returns the height of the HTML text. This is important if area height (see - wxHtmlDCRenderer::SetSize) - is smaller that total height and thus the page cannot fit into it. In that case - you're supposed to - call Render() as long as its return value is smaller than GetTotalHeight's. + Returns the height of the HTML text. This is important if area height + (see wxHtmlDCRenderer::SetSize) is smaller that total height and thus + the page cannot fit into it. In that case you're supposed to call + Render() as long as its return value is smaller than GetTotalHeight()'s. */ int GetTotalHeight(); /** Renders HTML text to the DC. - + @param x,y - position of upper-left corner of printing rectangle (see SetSize) + position of upper-left corner of printing rectangle (see SetSize()) @param from y-coordinate of the very first visible cell @param dont_render if @true then this method only returns y coordinate of the next page and does not output anything + + Returned value is y coordinate of first cell than didn't fit onto page. + Use this value as from in next call to Render() in order to print multipages document. + + @warning + The Following three methods @b must always be called before any call to + Render() (preferably in this order): + - SetDC() + - SetSize() + - SetHtmlText() + Render() changes the DC's user scale and does NOT restore it. */ int Render(int x, int y, int from = 0, int dont_render = false); /** Assign DC instance to the renderer. + @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.) + (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.) */ void SetDC(wxDC* dc, double pixel_scale = 1.0); /** - Sets fonts. See wxHtmlWindow::SetFonts for - detailed description. - See also SetSize(). + Sets fonts. See wxHtmlWindow::SetFonts for detailed description. + + @see SetSize() */ void SetFonts(const wxString& normal_face, const wxString& fixed_face, const int sizes = NULL); /** - Assign text to the renderer. Render() then draws - the text onto DC. - + Assign text to the renderer. Render() then draws the text onto DC. + @param html HTML text. This is not a filename. @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. + base directory (html string would be stored there if it was in file). + It is used to determine path for loading images, for example. @param isdir @false if basepath is filename, @true if it is directory name - (see wxFileSystem for detailed explanation) + (see wxFileSystem for detailed explanation). */ void SetHtmlText(const wxString& html, const wxString& basepath = wxEmptyString, @@ -96,31 +105,35 @@ public: /** @class wxHtmlEasyPrinting - This class provides very simple interface to printing - architecture. It allows you to print HTML documents using - only a few commands. + This class provides very simple interface to printing architecture. + It allows you to print HTML documents using only a few commands. + + @note + Do not create this class on the stack only. You should create an instance + on app startup and use this instance for all printing operations. + The reason is that this class stores various settings in it. @library{wxhtml} - @category{html} + @category{html,printing} */ class wxHtmlEasyPrinting : public wxObject { public: /** Constructor. - + @param name Name of the printing object. Used by preview frames and setup dialogs. @param parentWindow pointer to the window that will own the preview frame and setup dialogs. - May be @NULL. + May be @NULL. */ wxHtmlEasyPrinting(const wxString& name = "Printing", wxWindow* parentWindow = NULL); /** - Returns a pointer to wxPageSetupDialogData instance used by - this class. You can set its parameters (via SetXXXX methods). + Returns a pointer to wxPageSetupDialogData instance used by this class. + You can set its parameters (via SetXXXX methods). */ wxPageSetupDialogData* GetPageSetupData(); @@ -130,8 +143,8 @@ public: wxWindow* GetParentWindow() const; /** - Returns pointer to wxPrintData instance used by this class. You can - set its parameters (via SetXXXX methods). + Returns pointer to wxPrintData instance used by this class. + You can set its parameters (via SetXXXX methods). */ wxPrintData* GetPrintData(); @@ -142,53 +155,52 @@ public: /** Preview HTML file. - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed + + Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. */ bool PreviewFile(const wxString& htmlfile); /** Preview HTML text (not file!). - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed + + Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. - + @param htmltext HTML text. @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. + base directory (html string would be stored there if it was in file). + It is used to determine path for loading images, for example. */ bool PreviewText(const wxString& htmltext, const wxString& basepath = wxEmptyString); /** Print HTML file. - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed + + Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. */ bool PrintFile(const wxString& htmlfile); /** Print HTML text (not file!). - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed + + Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. - + @param htmltext HTML text. @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. + base directory (html string would be stored there if it was in file). + It is used to determine path for loading images, for example. */ bool PrintText(const wxString& htmltext, const wxString& basepath = wxEmptyString); /** - 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, @@ -201,7 +213,7 @@ public: @@PAGESCNT@ is replaced by total number of pages @@TIME@ is replaced by the current time in default format @@TITLE@ is replaced with the title of the document - + @param footer HTML text to be used as footer. @param pg @@ -211,12 +223,12 @@ public: /** Set page header. The following macros can be used inside it: - @@DATE@ is replaced by the current date in default format - @@PAGENUM@ is replaced by page number - @@PAGESCNT@ is replaced by total number of pages - @@TIME@ is replaced by the current time in default format - @@TITLE@ is replaced with the title of the document - + - @@DATE@ is replaced by the current date in default format + - @@PAGENUM@ is replaced by page number + - @@PAGESCNT@ is replaced by total number of pages + - @@TIME@ is replaced by the current time in default format + - @@TITLE@ is replaced with the title of the document + @param header HTML text to be used as header. @param pg @@ -238,7 +250,7 @@ public: This class serves as printout class for HTML documents. @library{wxhtml} - @category{html} + @category{html,printing} */ class wxHtmlPrintout : public wxPrintout { @@ -249,15 +261,13 @@ public: wxHtmlPrintout(const wxString& title = "Printout"); /** - Adds a filter to the static list of filters for wxHtmlPrintout. See - wxHtmlFilter for - further information. + Adds a filter to the static list of filters for wxHtmlPrintout. + See wxHtmlFilter for further information. */ static void AddFilter(wxHtmlFilter* filter); /** - 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, @@ -265,12 +275,12 @@ public: /** Set page footer. The following macros can be used inside it: - @@DATE@ is replaced by the current date in default format - @@PAGENUM@ is replaced by page number - @@PAGESCNT@ is replaced by total number of pages - @@TIME@ is replaced by the current time in default format - @@TITLE@ is replaced with the title of the document - + - @@DATE@ is replaced by the current date in default format + - @@PAGENUM@ is replaced by page number + - @@PAGESCNT@ is replaced by total number of pages + - @@TIME@ is replaced by the current time in default format + - @@TITLE@ is replaced with the title of the document + @param footer HTML text to be used as footer. @param pg @@ -280,12 +290,12 @@ public: /** Set page header. The following macros can be used inside it: - @@DATE@ is replaced by the current date in default format - @@PAGENUM@ is replaced by page number - @@PAGESCNT@ is replaced by total number of pages - @@TIME@ is replaced by the current time in default format - @@TITLE@ is replaced with the title of the document - + - @@DATE@ is replaced by the current date in default format + - @@PAGENUM@ is replaced by page number + - @@PAGESCNT@ is replaced by total number of pages + - @@TIME@ is replaced by the current time in default format + - @@TITLE@ is replaced with the title of the document + @param header HTML text to be used as header. @param pg @@ -294,30 +304,31 @@ public: void SetHeader(const wxString& header, int pg = wxPAGE_ALL); /** - Prepare the class for printing this HTML @b file. The file may be located on - any virtual file system or it may be normal file. + Prepare the class for printing this HTML @b file. + The file may be located on any virtual file system or it may be normal file. */ void SetHtmlFile(const wxString& htmlfile); /** Prepare the class for printing this HTML text. - + @param html HTML text. (NOT file!) @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. + base directory (html string would be stored there if it was in file). + It is used to determine path for loading images, for example. @param isdir @false if basepath is filename, @true if it is directory name - (see wxFileSystem for detailed explanation) + (see wxFileSystem for detailed explanation). */ void SetHtmlText(const wxString& html, const wxString& basepath = wxEmptyString, bool isdir = true); /** - Sets margins in millimeters. Defaults to 1 inch for margins and 0.5cm for space - between text and header and/or footer + Sets margins in millimeters. + Defaults to 1 inch for margins and 0.5cm for space between text and header + and/or footer. */ void SetMargins(float top = 25.2, float bottom = 25.2, float left = 25.2, diff --git a/interface/wx/html/winpars.h b/interface/wx/html/winpars.h index 232ba50760..4a2f2aed36 100644 --- a/interface/wx/html/winpars.h +++ b/interface/wx/html/winpars.h @@ -11,13 +11,12 @@ 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 { @@ -25,13 +24,16 @@ 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*); + virtual void FillHandlersTable(wxHtmlWinParser* parser); }; @@ -39,23 +41,22 @@ public: /** @class wxHtmlWinTagHandler - 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; }; @@ -63,29 +64,30 @@ public: /** @class wxHtmlWinParser - 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: - //@{ + wxHtmlWinParser(); + /** - 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 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); - //@} /** Adds module() to the list of wxHtmlWinParser tag handler. @@ -94,18 +96,15 @@ public: /** 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(); @@ -121,24 +120,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; @@ -148,9 +152,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; @@ -190,10 +194,9 @@ 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; @@ -209,14 +212,15 @@ 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. */ 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(); @@ -227,21 +231,20 @@ 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 @@ -255,9 +258,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); @@ -272,7 +275,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); @@ -282,22 +285,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 = 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);