Version: 3.1.1
wxHtmlParser Class Referenceabstract

#include <wx/html/htmlpars.h>

+ Inheritance diagram for wxHtmlParser:

Detailed Description

Classes derived from this handle the 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).

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 wxHtmlParser instance. The reason is that the handler may contain document-specific temporary data used during parsing (e.g. complicated structures like tables).

Typically the user calls only the wxHtmlParser::Parse method.

Library:  wxHTML
Category:  HTML
See also
Cells and Containers, Tag Handlers, wxHtmlTag

Public Member Functions

 wxHtmlParser ()
 Constructor. More...
 
virtual void AddTagHandler (wxHtmlTagHandler *handler)
 Adds handler to the internal list ( hash table) of handlers. More...
 
virtual void AddWord (const wxString &txt)
 Must be overwritten in derived class. More...
 
void DoParsing (const const_iterator &begin_pos, const const_iterator &end_pos)
 Parses the m_Source from begin_pos to end_pos - 1. More...
 
void DoParsing ()
 Parses the whole m_Source. More...
 
virtual void DoneParser ()
 This must be called after DoParsing(). More...
 
wxFileSystemGetFS () const
 Returns pointer to the file system. More...
 
virtual wxObjectGetProduct ()=0
 Returns product of parsing. More...
 
const wxStringGetSource ()
 Returns pointer to the source being parsed. More...
 
virtual void InitParser (const wxString &source)
 Setups the parser for parsing the source string. More...
 
virtual wxFSFileOpenURL (wxHtmlURLType type, const wxString &url) const
 Opens given URL and returns wxFSFile object that can be used to read data from it. More...
 
wxObjectParse (const wxString &source)
 Proceeds parsing of the document. More...
 
void PopTagHandler ()
 Restores parser's state before last call to PushTagHandler(). More...
 
void PushTagHandler (wxHtmlTagHandler *handler, const wxString &tags)
 Forces the handler to handle additional tags (not returned by wxHtmlTagHandler::GetSupportedTags). More...
 
void SetFS (wxFileSystem *fs)
 Sets the virtual file system that will be used to request additional files. More...
 
virtual void StopParsing ()
 Call this function to interrupt parsing from a tag handler. More...
 

Protected Member Functions

virtual void AddTag (const wxHtmlTag &tag)
 This may (and may not) be overwritten in derived class. More...
 

Constructor & Destructor Documentation

wxHtmlParser::wxHtmlParser ( )

Constructor.

Member Function Documentation

virtual void wxHtmlParser::AddTag ( const wxHtmlTag tag)
protectedvirtual

This may (and may not) be overwritten in derived class.

This method is called each time new tag is about to be added. 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 wxHtmlParser::AddTagHandler ( wxHtmlTagHandler handler)
virtual

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 instance of wxHtmlParser, not to all objects of this class! (Static front-end to AddTagHandler is provided by wxHtmlWinParser).

All handlers are deleted on object deletion.

virtual void wxHtmlParser::AddWord ( const wxString txt)
virtual

Must be overwritten in derived class.

This method is called by DoParsing() each time a part of text is parsed. txt is NOT only one word, it is substring of input. It is not formatted or preprocessed (so white spaces are unmodified).

virtual void wxHtmlParser::DoneParser ( )
virtual

This must be called after DoParsing().

void wxHtmlParser::DoParsing ( const const_iterator &  begin_pos,
const const_iterator &  end_pos 
)

Parses the m_Source from begin_pos to end_pos - 1.

void wxHtmlParser::DoParsing ( )

Parses the whole m_Source.

wxFileSystem* wxHtmlParser::GetFS ( ) const

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:

wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg");
virtual wxObject* wxHtmlParser::GetProduct ( )
pure virtual

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.

const wxString* wxHtmlParser::GetSource ( )

Returns pointer to the source being parsed.

virtual void wxHtmlParser::InitParser ( const wxString source)
virtual

Setups the parser for parsing the source string.

(Should be overridden in derived class)

virtual wxFSFile* wxHtmlParser::OpenURL ( wxHtmlURLType  type,
const wxString url 
) const
virtual

Opens given URL and returns wxFSFile object that can be used to read data 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 OpenURL in derived class.

Parameters
typeIndicates 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.
urlURL 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!
wxObject* wxHtmlParser::Parse ( const wxString source)

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).

The method does these things:

  1. calls InitParser(source)
  2. calls DoParsing()
  3. calls GetProduct()
  4. calls DoneParser()
  5. returns value returned by GetProduct()

You shouldn't use InitParser(), DoParsing(), GetProduct() or DoneParser() directly.

void wxHtmlParser::PopTagHandler ( )

Restores parser's state before last call to PushTagHandler().

void wxHtmlParser::PushTagHandler ( wxHtmlTagHandler handler,
const wxString tags 
)

Forces the handler to handle additional tags (not returned by wxHtmlTagHandler::GetSupportedTags).

The handler should already be added to this parser.

Parameters
handlerthe handler
tagsList 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:

<myitems>
<param name="one" value="1">
<param name="two" value="2">
</myitems>
<execute>
<param program="text.exe">
</execute>

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:

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)
void wxHtmlParser::SetFS ( wxFileSystem fs)

Sets the virtual file system that will be used to request additional files.

(For example IMG tag handler requests wxFSFile with the image data.)

virtual void wxHtmlParser::StopParsing ( )
virtual

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).