| 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 | " 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. You should check whether the |
| 82 | parameter exists or not (use wxHtmlTag::HasParam) first. |
| 83 | |
| 84 | @param par |
| 85 | The parameter's name. |
| 86 | @param with_quotes |
| 87 | @true if you want to get quotes as well. See example. |
| 88 | |
| 89 | Example: |
| 90 | @code |
| 91 | ... |
| 92 | // you have wxHtmlTag variable tag which is equal to the |
| 93 | // HTML tag <FONT SIZE=+2 COLOR="#0000FF"> |
| 94 | dummy = tag.GetParam("SIZE"); |
| 95 | // dummy == "+2" |
| 96 | dummy = tag.GetParam("COLOR"); |
| 97 | // dummy == "#0000FF" |
| 98 | dummy = tag.GetParam("COLOR", true); |
| 99 | // dummy == "\"#0000FF\"" -- see the difference!! |
| 100 | @endcode |
| 101 | */ |
| 102 | wxString GetParam(const wxString& par, bool with_quotes = false) const; |
| 103 | |
| 104 | /** |
| 105 | Interprets tag parameter @a par as colour specification and saves its value |
| 106 | into wxColour variable pointed by @a clr. |
| 107 | |
| 108 | Returns @true on success and @false if @a par is not colour specification or |
| 109 | if the tag has no such parameter. |
| 110 | |
| 111 | @see ParseAsColour() |
| 112 | */ |
| 113 | bool GetParamAsColour(const wxString& par, wxColour* clr) const; |
| 114 | |
| 115 | /** |
| 116 | Interprets tag parameter @a par as an integer and saves its value |
| 117 | into int variable pointed by @a value. |
| 118 | |
| 119 | Returns @true on success and @false if @a par is not an integer or |
| 120 | if the tag has no such parameter. |
| 121 | */ |
| 122 | bool GetParamAsInt(const wxString& par, int* value) const; |
| 123 | |
| 124 | /** |
| 125 | Returns @true if this tag is paired with ending tag, @false otherwise. |
| 126 | See the example of HTML document: |
| 127 | @code |
| 128 | <html><body> |
| 129 | Hello<p> |
| 130 | How are you? |
| 131 | <p align=center>This is centered...</p> |
| 132 | Oops<br>Oooops! |
| 133 | </body></html> |
| 134 | @endcode |
| 135 | |
| 136 | In this example tags HTML and BODY have ending tags, first P and BR |
| 137 | doesn't have ending tag while the second P has. |
| 138 | The third P tag (which is ending itself) of course doesn't have ending tag. |
| 139 | */ |
| 140 | bool HasEnding() const; |
| 141 | |
| 142 | /** |
| 143 | Returns @true if the tag has a parameter of the given name. |
| 144 | Example: \<FONT SIZE=+2 COLOR="\#FF00FF"\> has two parameters named |
| 145 | "SIZE" and "COLOR". |
| 146 | |
| 147 | @param par |
| 148 | the parameter you're looking for. |
| 149 | */ |
| 150 | bool HasParam(const wxString& par) const; |
| 151 | |
| 152 | /** |
| 153 | Parses the given string as an HTML colour. |
| 154 | |
| 155 | This function recognizes the standard named HTML 4 colours as well as |
| 156 | the usual RGB syntax. |
| 157 | |
| 158 | @since 2.9.1 |
| 159 | |
| 160 | @see wxColour::Set() |
| 161 | |
| 162 | @return @true if the string was successfully parsed and @a clr was |
| 163 | filled with the result or @false otherwise. |
| 164 | */ |
| 165 | static bool ParseAsColour(const wxString& str, wxColour *clr); |
| 166 | |
| 167 | //@{ |
| 168 | /** |
| 169 | This method scans the given parameter. Usage is exactly the same as sscanf's |
| 170 | usage except that you don't pass a string but a parameter name as the first |
| 171 | argument and you can only retrieve one value (i.e. you can use only one "%" |
| 172 | element in @a format). |
| 173 | |
| 174 | @param par |
| 175 | The name of the tag you want to query |
| 176 | @param format |
| 177 | scanf()-like format string. |
| 178 | @param value |
| 179 | pointer to a variable to store the value in |
| 180 | */ |
| 181 | int ScanParam(const wxString& par, const wchar_t* format, void* value) const; |
| 182 | int ScanParam(const wxString& par, const char* format, void* value) const; |
| 183 | //@} |
| 184 | }; |
| 185 | |