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 license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHtmlTag
  11
  12     This class represents a single HTML tag.
  13     It is used by @ref overview_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 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 @c FONT SIZE=+2 COLOR="#000000". Call to
  34         tag.GetAllParams() would return @c SIZE=+2 COLOR="#000000".
  35     */
  36     const wxString GetAllParams() const;
  37
  38     /**
  39         Returns beginning position of the text @e between this tag and paired
  40         ending tag.
  41         See explanation (returned position is marked with '|'):
  42         @deprecated @todo provide deprecation description
  43     */
  44     int GetBeginPos() const;
  45
  46     /**
  47         Returns ending position of the text @e between this tag and paired
  48         ending tag.
  49         See explanation (returned position is marked with '|'):
  50         @deprecated @todo provide deprecation description
  51     */
  52     int GetEndPos1() const;
  53
  54     /**
  55         Returns ending position 2 of the text @e between this tag and paired
  56         ending tag.
  57         See explanation (returned position is marked with '|'):
  58         @deprecated @todo provide deprecation description
  59     */
  60     int GetEndPos2() const;
  61
  62     /**
  63         Returns tag's name. The name is always in uppercase and it doesn't contain
  64         " or '/' characters. (So the name of @c FONT SIZE=+2 tag is "FONT"
  65         and name of @c /table is "TABLE")
  66     */
  67     wxString GetName() const;
  68
  69     /**
  70         Returns the value of the parameter. You should check whether the
  71         parameter exists or not (use wxHtmlTag::HasParam) first.
  72
  73         @param par
  74             The parameter's name.
  75         @param with_quotes
  76             @true if you want to get quotes as well. See example.
  77     */
  78     wxString GetParam(const wxString& par, bool with_quotes = false) const;
  79
  80     /**
  81         Interprets tag parameter @a par as colour specification and saves its value
  82         into wxColour variable pointed by @e clr.
  83         Returns @true on success and @false if @a par is not colour specification or
  84         if the tag has no such parameter.
  85     */
  86     bool GetParamAsColour(const wxString& par, wxColour* clr) const;
  87
  88     /**
  89         Interprets tag parameter @a par as an integer and saves its value
  90         into int variable pointed by @e value.
  91         Returns @true on success and @false if @a par is not an integer or
  92         if the tag has no such parameter.
  93     */
  94     bool GetParamAsInt(const wxString& par, int* value) const;
  95
  96     /**
  97         Returns @true if this tag is paired with ending tag, @false otherwise.
  98         See the example of HTML document:
  99
 100         In this example tags HTML and BODY have ending tags, first P and BR
 101         doesn't have ending tag while the second P has. The third P tag (which
 102         is ending itself) of course doesn't have ending tag.
 103     */
 104     bool HasEnding() const;
 105
 106     /**
 107         Returns @true if the tag has a parameter of the given name.
 108         Example : @c FONT SIZE=+2 COLOR="\#FF00FF" has two parameters named
 109         "SIZE" and "COLOR".
 110
 111         @param par
 112             the parameter you're looking for.
 113     */
 114     bool HasParam(const wxString& par) const;
 115
 116     /**
 117         This method scans the given parameter. Usage is exactly the same as sscanf's
 118         usage except that you don't pass a string but a parameter name as the first
 119         argument
 120         and you can only retrieve one value (i.e. you can use only one "%" element
 121         in @e format).
 122
 123         @param par
 124             The name of the tag you want to query
 125         @param format
 126             scanf()-like format string.
 127         @param value
 128             pointer to a variable to store the value in
 129     */
 130     wxString ScanParam(const wxString& par, const wxChar* format,
 131                        void* value) const;
 132 };
 133