X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/da1ed74c85f53a75a193c7dcbd2013aa266a222c..d3fa4bc22e84e3ca4d88cc1772f2d414140a1017:/interface/wx/html/htmlpars.h diff --git a/interface/wx/html/htmlpars.h b/interface/wx/html/htmlpars.h index a5d783a74a..361df93854 100644 --- a/interface/wx/html/htmlpars.h +++ b/interface/wx/html/htmlpars.h @@ -3,17 +3,27 @@ // Purpose: interface of wxHtmlTagHandler // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +enum wxHtmlURLType +{ + wxHTML_URL_PAGE, + wxHTML_URL_IMAGE, + wxHTML_URL_OTHER +}; + + + /** @class wxHtmlTagHandler + @todo describe me @library{wxhtml} @category{html} - @see Overview(), wxHtmlTag + @see @ref overview_html_handlers, wxHtmlTag */ class wxHtmlTagHandler : public wxObject { @@ -24,8 +34,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,31 +44,67 @@ 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; + /** + Assigns @a parser to this handler. Each @b instance of handler + is guaranteed to be called only from the one parser. + */ + virtual void SetParser(wxHtmlParser* parser); + + /** + Returns the parser associated with this tag handler. + + @since 2.9.5 + */ + wxHtmlParser* GetParser() const; + + +protected: + /** 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); /** - Assigns @a parser to this handler. Each @b instance of handler - is guaranteed to be called only from the parser. + Parses given source as if it was tag's inner code (see + wxHtmlParser::GetInnerSource). Unlike ParseInner(), this method lets + you specify the source code to parse. This is useful when you need to + modify the inner text before parsing. */ - virtual void SetParser(wxHtmlParser parser); + void ParseInnerSource(const wxString& source); /** - @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 +113,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 +129,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 { @@ -98,44 +140,36 @@ public: 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. - */ - 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); + 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(const const_iterator& begin_pos, const const_iterator& end_pos); + + /** + Parses the whole m_Source. */ - void DoParsing(int begin_pos, int end_pos); void DoParsing(); - //@} /** This must be called after DoParsing(). @@ -145,14 +179,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; @@ -160,11 +199,11 @@ public: /** Returns pointer to the source being parsed. */ - wxString* GetSource(); + const 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 +212,45 @@ 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); + virtual wxFSFile* OpenURL(wxHtmlURLType type, const wxString& url) const; /** 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,29 +258,74 @@ 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); + 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(); + +protected: + + /** + 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. + */ + virtual void AddTag(const wxHtmlTag& tag); };