interface/wx/html/htmltag.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/htmltag.h
   3 // Purpose:     interface of wxHtmlTag
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxHtmlTag
  10
  11     This class represents a single HTML tag.
  12     It is used by @ref overview_html_handlers "tag handlers".
  13
  14     @library{wxhtml}
  15     @category{html}
  16 */
  17 class wxHtmlTag
  18 {
  19 protected:
  20     /**
  21         Constructor. You will probably never have to construct a wxHtmlTag object
  22         yourself. Feel free to ignore the constructor parameters.
  23         Have a look at @c src/html/htmlpars.cpp if you're interested in creating it.
  24     */
  25     wxHtmlTag(wxHtmlTag* parent, const wxString* source,
  26               const const_iterator& pos, const const_iterator& end_pos,
  27               wxHtmlTagsCache* cache, wxHtmlEntitiesParser* entParser);
  28
  29 public:
  30     /**
  31         Returns a string containing all parameters.
  32         Example: tag contains \<FONT SIZE=+2 COLOR="#000000"\>.
  33         Call to tag.GetAllParams() would return @c 'SIZE=+2 COLOR="#000000"'.
  34     */
  35     wxString GetAllParams() const;
  36
  37     /**
  38         Returns beginning position of the text @e between this tag and paired
  39         ending tag. See explanation (returned position is marked with '|'):
  40         @code
  41         bla bla bla <MYTAG> bla bla internal text</MYTAG> bla bla
  42                            |
  43         @endcode
  44
  45         @deprecated @todo provide deprecation description
  46     */
  47     int GetBeginPos() const;
  48
  49     /**
  50         Returns ending position of the text @e between this tag and paired
  51         ending tag. See explanation (returned position is marked with '|'):
  52         @code
  53         bla bla bla <MYTAG> bla bla internal text</MYTAG> bla bla
  54                                                  |
  55         @endcode
  56
  57         @deprecated @todo provide deprecation description
  58     */
  59     int GetEndPos1() const;
  60
  61     /**
  62         Returns ending position 2 of the text @e between this tag and paired
  63         ending tag. See explanation (returned position is marked with '|'):
  64         @code
  65         bla bla bla <MYTAG> bla bla internal text</MYTAG> bla bla
  66                                                         |
  67         @endcode
  68
  69         @deprecated @todo provide deprecation description
  70     */
  71     int GetEndPos2() const;
  72
  73     /**
  74         Returns tag's name. The name is always in uppercase and it doesn't contain
  75         &quot; or '/' characters. (So the name of \<FONT SIZE=+2\> tag is "FONT"
  76         and name of \</table\> is "TABLE").
  77     */
  78     wxString GetName() const;
  79
  80     /**
  81         Returns the value of the parameter.
  82
  83         You should check whether the parameter exists or not (use
  84         wxHtmlTag::HasParam) first or use GetParamAsString() if you need to
  85         distinguish between non-specified and empty parameter values.
  86
  87         @param par
  88             The parameter's name.
  89         @param with_quotes
  90             @true if you want to get quotes as well. See example.
  91
  92         Example:
  93         @code
  94         ...
  95         // you have wxHtmlTag variable tag which is equal to the
  96         // HTML tag <FONT SIZE=+2 COLOR="#0000FF">
  97         dummy = tag.GetParam("SIZE");
  98         // dummy == "+2"
  99         dummy = tag.GetParam("COLOR");
 100         // dummy == "#0000FF"
 101         dummy = tag.GetParam("COLOR", true);
 102         // dummy == "\"#0000FF\"" -- see the difference!!
 103         @endcode
 104     */
 105     wxString GetParam(const wxString& par, bool with_quotes = false) const;
 106
 107     /**
 108         Interprets tag parameter @a par as colour specification and saves its value
 109         into wxColour variable pointed by @a clr.
 110
 111         Returns @true on success and @false if @a par is not colour specification or
 112         if the tag has no such parameter.
 113
 114         @see ParseAsColour()
 115     */
 116     bool GetParamAsColour(const wxString& par, wxColour* clr) const;
 117
 118     /**
 119         Interprets tag parameter @a par as an integer and saves its value
 120         into int variable pointed by @a value.
 121
 122         Returns @true on success and @false if @a par is not an integer or
 123         if the tag has no such parameter.
 124     */
 125     bool GetParamAsInt(const wxString& par, int* value) const;
 126
 127     /**
 128         Get the value of the parameter.
 129
 130         If the tag doesn't have such parameter at all, simply returns @false.
 131         Otherwise, fills @a value with the parameter value and returns @true.
 132
 133         @param par
 134             The parameter's name.
 135         @param value
 136             Pointer to the string to be filled with the parameter value, must
 137             be non-@NULL.
 138
 139         @since 3.0
 140      */
 141     bool GetParamAsString(const wxString& par, wxString* value) const;
 142
 143     /**
 144         Returns @true if this tag is paired with ending tag, @false otherwise.
 145         See the example of HTML document:
 146         @code
 147         <html><body>
 148         Hello<p>
 149         How are you?
 150         <p align=center>This is centered...</p>
 151         Oops<br>Oooops!
 152         </body></html>
 153         @endcode
 154
 155         In this example tags HTML and BODY have ending tags, first P and BR
 156         doesn't have ending tag while the second P has.
 157         The third P tag (which is ending itself) of course doesn't have ending tag.
 158     */
 159     bool HasEnding() const;
 160
 161     /**
 162         Returns @true if the tag has a parameter of the given name.
 163         Example: \<FONT SIZE=+2 COLOR="\#FF00FF"\> has two parameters named
 164         "SIZE" and "COLOR".
 165
 166         @param par
 167             the parameter you're looking for.
 168     */
 169     bool HasParam(const wxString& par) const;
 170
 171     /**
 172         Parses the given string as an HTML colour.
 173
 174         This function recognizes the standard named HTML 4 colours as well as
 175         the usual RGB syntax.
 176
 177         @since 2.9.1
 178
 179         @see wxColour::Set()
 180
 181         @return @true if the string was successfully parsed and @a clr was
 182             filled with the result or @false otherwise.
 183      */
 184     static bool ParseAsColour(const wxString& str, wxColour *clr);
 185
 186     //@{
 187     /**
 188         This method scans the given parameter. Usage is exactly the same as sscanf's
 189         usage except that you don't pass a string but a parameter name as the first
 190         argument and you can only retrieve one value (i.e. you can use only one "%"
 191         element in @a format).
 192
 193         @param par
 194             The name of the tag you want to query
 195         @param format
 196             scanf()-like format string.
 197         @param value
 198             pointer to a variable to store the value in
 199     */
 200     int ScanParam(const wxString& par, const wchar_t* format, void* value) const;
 201     int ScanParam(const wxString& par, const char* format, void* value) const;
 202     //@}
 203 };
 204