Resolve ambiguity between GetClientXXX() methods in wxOSX wxComboBox.
[wxWidgets.git] / interface / wx / html / htmlpars.h
index 0b0b318751e9ce6ffbb269c4ccd1ff1344be7ea6..28e7bc690f4f740f6a302b738e9012553873d914 100644 (file)
@@ -3,17 +3,18 @@
 // Purpose:     interface of wxHtmlTagHandler
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxHtmlTagHandler
 
+    @todo describe me
 
     @library{wxhtml}
     @category{html}
 
-    @see Overview(), wxHtmlTag
+    @see @ref overview_html_handlers, wxHtmlTag
 */
 class wxHtmlTagHandler : public wxObject
 {
@@ -24,40 +25,61 @@ 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();
+    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);
+    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:
-        
-        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);
 
     /**
-        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.
     */
+    wxHtmlParser* m_Parser;
 };
 
 
@@ -66,14 +88,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 +104,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 +115,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.
-    */
-    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,26 +154,31 @@ 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();
+    virtual wxObject* GetProduct() = 0;
 
     /**
         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 +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.
-        
+
         @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 +233,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
+        <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).
     */
-    void SetFS(wxFileSystem fs);
+    virtual void StopParsing();
+
+protected:
 
     /**
-        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).
+        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.
     */
-    void StopParsing();
+    virtual void AddTag(const wxHtmlTag& tag);
 };