few other fixes for wxChar => wxString

[wxWidgets.git] / interface / wx / html / htmlpars.h

diff --git a/interface/wx/html/htmlpars.h b/interface/wx/html/htmlpars.h
index a5d783a74ab30c9e0f707173d1cadd50a274b53c..82dfb28c4933c51dfb698201ded474b8d7fedc61 100644 (file)
--- a/interface/wx/html/htmlpars.h
+++ b/interface/wx/html/htmlpars.h
@@ -9,11 +9,12 @@
 /**
     @class wxHtmlTagHandler
 
 /**
     @class wxHtmlTagHandler
 

+    @todo describe me

 
     @library{wxhtml}
     @category{html}
 
 
     @library{wxhtml}
     @category{html}
 

-    @see Overview(), wxHtmlTag
+    @see @ref overview_html_handlers, wxHtmlTag

 */
 class wxHtmlTagHandler : public wxObject
 {
 */
 class wxHtmlTagHandler : public wxObject
 {


@@ -24,8 +25,9 @@ public:
     wxHtmlTagHandler();
 
     /**
     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;
 
     */
     virtual wxString GetSupportedTags() = 0;
 


@@ -33,31 +35,51 @@ 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).
         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;
 
     */
     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 parser.
+    */
+    virtual void SetParser(wxHtmlParser* parser);
+
+protected:
+

     /**
         This method calls parser's wxHtmlParser::DoParsing method
         for the string between this tag and the paired ending tag:
     /**
         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);
 
     /**
         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.
-    */
-    virtual void SetParser(wxHtmlParser parser);
-
-    /**
-        @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.
     */
         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 +88,10 @@ public:
     @class wxHtmlParser
 
     Classes derived from this handle the @b generic parsing of HTML documents: it
     @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
 
     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 +104,7 @@ public:
     @library{wxhtml}
     @category{html}
 
     @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
 {
 */
 class wxHtmlParser
 {


@@ -98,44 +115,36 @@ public:
     wxHtmlParser();
 
     /**
     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.
         constructor.

+

         This adds the handler to this @b instance of wxHtmlParser, not to
         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.
     */
         All handlers are deleted on object deletion.
     */

-    virtual void AddTagHandler(wxHtmlTagHandler handler);
+    virtual void AddTagHandler(wxHtmlTagHandler* handler);

 
     /**
         Must be overwritten in derived class.
 
     /**
         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);
 
     */
     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();
     void DoParsing();

-    //@}

 
     /**
         This must be called after DoParsing().
 
     /**
         This must be called after DoParsing().


@@ -145,14 +154,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
     /**
         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;
 
     /**
     */
     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;
         See wxHtmlWinParser for details.
     */
     virtual wxObject* GetProduct() = 0;


@@ -160,11 +174,11 @@ public:
     /**
         Returns pointer to the source being parsed.
     */
     /**
         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);
 
     */
     virtual void InitParser(const wxString& source);
 


@@ -173,66 +187,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.
         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:
         @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 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
 
     /**
         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:
         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);
 
     /**
     */
     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();
 
     */
     void PopTagHandler();
 


@@ -240,29 +233,74 @@ public:
         Forces the handler to handle additional tags
         (not returned by wxHtmlTagHandler::GetSupportedTags).
         The handler should already be added to this parser.
         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
         @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);
 
     /**
     */
     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();
     */
     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);

 };
 
 };