interface/html/htmltag.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/htmltag.h
   3 // Purpose:     documentation for wxHtmlTag class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHtmlTag
  11     @headerfile htmltag.h wx/html/htmltag.h
  12
  13     This class represents a single HTML tag.
  14     It is used by @ref overview_handlers "tag handlers".
  15
  16     @library{wxhtml}
  17     @category{FIXME}
  18 */
  19 class wxHtmlTag
  20 {
  21 public:
  22     /**
  23         Constructor. You will probably never have to construct a wxHtmlTag object
  24         yourself. Feel free to ignore the constructor parameters.
  25         Have a look at src/html/htmlpars.cpp if you're interested in creating it.
  26     */
  27     wxHtmlTag(wxHtmlTag * parent, const wxString& source, int pos,
  28               int end_pos, wxHtmlTagsCache* cache,
  29               wxHtmlEntitiesParser * entParser);
  30
  31     /**
  32         Returns a string containing all parameters.
  33
  34         Example : tag contains @c FONT SIZE=+2 COLOR="#000000". Call to
  35         tag.GetAllParams() would return @c SIZE=+2 COLOR="#000000".
  36     */
  37     const wxString GetAllParams();
  38
  39     /**
  40         Returns beginning position of the text @e between this tag and paired
  41         ending tag.
  42         See explanation (returned position is marked with '|'):
  43     */
  44     int GetBeginPos();
  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     */
  51     int GetEndPos1();
  52
  53     /**
  54         Returns ending position 2 of the text @e between this tag and paired
  55         ending tag.
  56         See explanation (returned position is marked with '|'):
  57     */
  58     int GetEndPos2();
  59
  60     /**
  61         Returns tag's name. The name is always in uppercase and it doesn't contain
  62         '' or '/' characters. (So the name of @c FONT SIZE=+2 tag is "FONT"
  63         and name of @c /table is "TABLE")
  64     */
  65     wxString GetName();
  66
  67     /**
  68         Returns the value of the parameter. You should check whether the
  69         parameter exists or not (use wxHtmlTag::HasParam) first.
  70
  71         @param par
  72         The parameter's name.
  73
  74         @param with_quotes
  75         @true if you want to get quotes as well. See example.
  76     */
  77     wxString GetParam(const wxString& par, bool with_quotes = @false);
  78
  79     /**
  80         Interprets tag parameter @e par as colour specification and saves its value
  81         into wxColour variable pointed by @e clr.
  82
  83         Returns @true on success and @false if @e par is not colour specification or
  84         if the tag has no such parameter.
  85     */
  86     bool GetParamAsColour(const wxString& par, wxColour * clr);
  87
  88     /**
  89         Interprets tag parameter @e par as an integer and saves its value
  90         into int variable pointed by @e value.
  91
  92         Returns @true on success and @false if @e par is not an integer or
  93         if the tag has no such parameter.
  94     */
  95     bool GetParamAsInt(const wxString& par, int * value);
  96
  97     /**
  98         Returns @true if this tag is paired with ending tag, @false otherwise.
  99
 100         See the example of HTML document:
 101         In this example tags HTML and BODY have ending tags, first P and BR
 102         doesn't have ending tag while the second P has. The third P tag (which
 103         is ending itself) of course doesn't have ending tag.
 104     */
 105     bool HasEnding();
 106
 107     /**
 108         Returns @true if the tag has a parameter of the given name.
 109         Example : @c FONT SIZE=+2 COLOR="#FF00FF" has two parameters named
 110         "SIZE" and "COLOR".
 111
 112         @param par
 113         the parameter you're looking for.
 114     */
 115     bool HasParam(const wxString& par);
 116
 117     /**
 118         This method scans the given parameter. Usage is exactly the same as sscanf's
 119         usage except that you don't pass a string but a parameter name as the first
 120         argument
 121         and you can only retrieve one value (i.e. you can use only one "%" element
 122         in @e format).
 123
 124         @param par
 125         The name of the tag you want to query
 126
 127         @param format
 128         scanf()-like format string.
 129
 130         @param value
 131         pointer to a variable to store the value in
 132     */
 133     wxString ScanParam(const wxString& par, const wxChar * format,
 134                        void * value);
 135 };