interface/wx/html/htmltag.h

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