X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/html/htmltag.h

diff --git a/interface/wx/html/htmltag.h b/interface/wx/html/htmltag.h
index 6e4cf6fb35..6f88e3b00b 100644
--- a/interface/wx/html/htmltag.h
+++ b/interface/wx/html/htmltag.h
@@ -2,88 +2,120 @@
 // Name:        html/htmltag.h
 // Purpose:     interface of wxHtmlTag
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @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{FIXME}
+    @category{html}
 */
 class wxHtmlTag
 {
-public:
+protected:
     /**
         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, int pos,
-              int end_pos, wxHtmlTagsCache* cache,
-              wxHtmlEntitiesParser* entParser);
+    wxHtmlTag(wxHtmlTag* parent, const wxString* source,
+              const const_iterator& pos, const const_iterator& end_pos,
+              wxHtmlTagsCache* cache, wxHtmlEntitiesParser* entParser);
 
+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;
+    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")
+        &quot; or '/' characters. (So the name of \<FONT SIZE=+2\> tag is "FONT"
+        and name of \</table\> is "TABLE").
     */
     wxString GetName() const;
 
     /**
         Returns the value of the parameter. You should check whether the
         parameter exists or not (use wxHtmlTag::HasParam) first.
-        
+
         @param par
             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.
+
+        @see ParseAsColour()
     */
     bool GetParamAsColour(const wxString& par, wxColour* clr) const;
 
     /**
         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.
     */
@@ -92,30 +124,53 @@ public:
     /**
         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
             the parameter you're looking for.
     */
     bool HasParam(const wxString& par) const;
 
+    /**
+        Parses the given string as an HTML colour.
+
+        This function recognizes the standard named HTML 4 colours as well as
+        the usual RGB syntax.
+
+        @since 2.9.1
+
+        @see wxColour::Set()
+
+        @return @true if the string was successfully parsed and @a clr was
+            filled with the result or @false otherwise.
+     */
+    static bool ParseAsColour(const wxString& str, wxColour *clr);
+
+    //@{
     /**
         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 format
@@ -123,7 +178,8 @@ public:
         @param value
             pointer to a variable to store the value in
     */
-    wxString ScanParam(const wxString& par, const wxChar* format,
-                       void* value) const;
+    int ScanParam(const wxString& par, const wchar_t* format, void* value) const;
+    int ScanParam(const wxString& par, const char* format, void* value) const;
+    //@}
 };