/////////////////////////////////////////////////////////////////////////////
// Name: html/htmlcell.h
-// Purpose: interface of wxHtmlColourCell
+// Purpose: interface of wxHtml*Cell
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
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);
};
@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
{
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);
};
/**
@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
{
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);
@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
/**
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;
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.
/**
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
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,
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);
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);
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
{
/**
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;
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);
@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);
/**
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);
- //@}
};
/**
@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 \<A\> 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 \<A\> 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 \<A\> tag (this value is used to specify
+ in which frame should be the page pointed by @ref GetHref() Href opened).
*/
wxString GetTarget() const;
};
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
{
/**
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 "<html><body><img src=\"" + file.GetLocation() +
+ "\"></body></html>";
+ }
+ @endcode
*/
virtual wxString ReadFile(const wxFSFile& file) const = 0;
};
/**
@class wxHtmlTagHandler
+ @todo describe me
@library{wxhtml}
@category{html}
- @see Overview(), wxHtmlTag
+ @see @ref overview_html_handlers, wxHtmlTag
*/
class wxHtmlTagHandler : public wxObject
{
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;
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
+ ...<A HREF="x.htm">Hello, world!</A>...
+ @endcode
+
+ In this example, a call to ParseInner() (with @a tag pointing to A tag)
will parse 'Hello, world!'.
*/
void ParseInner(const wxHtmlTag& tag);
*/
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;
};
@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
@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
{
/**
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().
/**
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;
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);
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();
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
+ <myitems>
+ <param name="one" value="1">
+ <param name="two" value="2">
+ </myitems>
+
+ <execute>
+ <param program="text.exe">
+ </execute>
+ @endcode
+
+ It is obvious that you cannot use only one tag handler for \<param\> tag.
+ Instead you must use context-sensitive handlers for \<param\> inside \<myitems\>
+ and \<param\> inside \<execute\>.
+ 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();
};
@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}
/**
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,
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 \<FONT SIZE=+2 COLOR="#000000"\>.
+ 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 <MYTAG> bla bla internal text</MYTAG> 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 <MYTAG> bla bla internal text</MYTAG> 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 <MYTAG> bla bla internal text</MYTAG> 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 \<FONT SIZE=+2\> tag is "FONT"
+ and name of \</table\> is "TABLE").
*/
wxString GetName() const;
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 <FONT SIZE=+2 COLOR="#0000FF">
+ 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.
*/
/**
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.
*/
/**
Returns @true if this tag is paired with ending tag, @false otherwise.
See the example of HTML document:
+ @code
+ <html><body>
+ Hello<p>
+ How are you?
+ <p align=center>This is centered...</p>
+ Oops<br>Oooops!
+ </body></html>
+ @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: \<FONT SIZE=+2 COLOR="\#FF00FF"\> has two parameters named
"SIZE" and "COLOR".
@param par
/**
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
@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;
};
/**
@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}
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}
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,
//@}
/**
- 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);
/**
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 \<TITLE\> tag.
*/
wxString GetOpenedPageTitle() const;
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();
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
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 \<TITLE\> 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.
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
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 ( \<TT\>..\</TT\> )
@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.
+ ( \<FONT SIZE=-2\> to \<FONT SIZE=+4\> ).
+ 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,
/**
Sets HTML page and display it. This won't @b load the page!!
It will display the @e source. See example:
+ @code
+ htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
+ @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.
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)
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.
/**
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
/**
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);
};
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
{
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;
};
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
{
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;
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);
};
/**
@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
{
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()
+ <b>Render() changes the DC's user scale and does NOT restore it.</b>
*/
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,
/**
@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();
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();
/**
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,
@@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
/**
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
This class serves as printout class for HTML documents.
@library{wxhtml}
- @category{html}
+ @category{html,printing}
*/
class wxHtmlPrintout : public wxPrintout
{
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,
/**
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
/**
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
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,
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
{
/**
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);
};
/**
@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;
};
/**
@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.
/**
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();
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;
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;
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 \<A\> and \</A\> tags, wxEmptyString otherwise.)
*/
const wxHtmlLinkInfo& GetLink() const;
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();
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
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 \<TT\> tag or not).
*/
void SetFontFace(const wxString& face);
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);
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);
projects / wxWidgets.git / commitdiff
