interface/wx/html/htmlpars.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/htmlpars.h
   3 // Purpose:     interface of wxHtmlTagHandler
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 enum wxHtmlURLType
   9 {
  10     wxHTML_URL_PAGE,
  11     wxHTML_URL_IMAGE,
  12     wxHTML_URL_OTHER
  13 };
  14
  15
  16
  17 /**
  18     @class wxHtmlTagHandler
  19
  20     @todo describe me
  21
  22     @library{wxhtml}
  23     @category{html}
  24
  25     @see @ref overview_html_handlers, wxHtmlTag
  26 */
  27 class wxHtmlTagHandler : public wxObject
  28 {
  29 public:
  30     /**
  31         Constructor.
  32     */
  33     wxHtmlTagHandler();
  34
  35     /**
  36         Returns list of supported tags.
  37         The list is in uppercase and tags are delimited by ','.
  38         Example: @c "I,B,FONT,P"
  39     */
  40     virtual wxString GetSupportedTags() = 0;
  41
  42     /**
  43         This is the core method of each handler. It is called each time
  44         one of supported tags is detected. @a tag contains all necessary
  45         info (see wxHtmlTag for details).
  46
  47         Example:
  48
  49         @code
  50         bool MyHandler::HandleTag(const wxHtmlTag& tag)
  51         {
  52             ...
  53             // change state of parser (e.g. set bold face)
  54             ParseInner(tag);
  55             ...
  56             // restore original state of parser
  57         }
  58         @endcode
  59
  60         You shouldn't call ParseInner() if the tag is not paired with an ending one.
  61
  62         @return @true if ParseInner() was called, @false otherwise.
  63     */
  64     virtual bool HandleTag(const wxHtmlTag& tag) = 0;
  65
  66     /**
  67         Assigns @a parser to this handler. Each @b instance of handler
  68         is guaranteed to be called only from the one parser.
  69     */
  70     virtual void SetParser(wxHtmlParser* parser);
  71
  72     /**
  73        Returns the parser associated with this tag handler.
  74
  75        @since 2.9.5
  76     */
  77     wxHtmlParser* GetParser() const;
  78
  79
  80 protected:
  81
  82     /**
  83         This method calls parser's wxHtmlParser::DoParsing method
  84         for the string between this tag and the paired ending tag:
  85         @code
  86         ...<A HREF="x.htm">Hello, world!</A>...
  87         @endcode
  88
  89         In this example, a call to ParseInner() (with @a tag pointing to A tag)
  90         will parse 'Hello, world!'.
  91     */
  92     void ParseInner(const wxHtmlTag& tag);
  93
  94     /**
  95        Parses given source as if it was tag's inner code (see
  96        wxHtmlParser::GetInnerSource).  Unlike ParseInner(), this method lets
  97        you specify the source code to parse. This is useful when you need to
  98        modify the inner text before parsing.
  99     */
 100     void ParseInnerSource(const wxString& source);
 101
 102     /**
 103         This attribute is used to access parent parser. It is protected so that
 104         it can't be accessed by user but can be accessed from derived classes.
 105     */
 106     wxHtmlParser* m_Parser;
 107 };
 108
 109
 110
 111 /**
 112     @class wxHtmlParser
 113
 114     Classes derived from this handle the @b generic parsing of HTML documents: it
 115     scans the document and divide it into blocks of tags (where one block consists
 116     of beginning and ending tag and of text between these two tags).
 117
 118     It is independent from wxHtmlWindow and can be used as stand-alone parser.
 119
 120     It uses system of tag handlers to parse the HTML document. Tag handlers
 121     are not statically shared by all instances but are created for each
 122     wxHtmlParser instance. The reason is that the handler may contain
 123     document-specific temporary data used during parsing (e.g. complicated
 124     structures like tables).
 125
 126     Typically the user calls only the wxHtmlParser::Parse method.
 127
 128     @library{wxhtml}
 129     @category{html}
 130
 131     @see @ref overview_html_cells, @ref overview_html_handlers, wxHtmlTag
 132 */
 133 class wxHtmlParser
 134 {
 135 public:
 136     /**
 137         Constructor.
 138     */
 139     wxHtmlParser();
 140
 141     /**
 142         Adds handler to the internal list ( hash table) of handlers.
 143         This method should not be called directly by user but rather by derived class'
 144         constructor.
 145
 146         This adds the handler to this @b instance of wxHtmlParser, not to
 147         all objects of this class!
 148         (Static front-end to AddTagHandler is provided by wxHtmlWinParser).
 149
 150         All handlers are deleted on object deletion.
 151     */
 152     virtual void AddTagHandler(wxHtmlTagHandler* handler);
 153
 154     /**
 155         Must be overwritten in derived class.
 156
 157         This method is called by DoParsing() each time a part of text is parsed.
 158         @a txt is NOT only one word, it is substring of input.
 159         It is not formatted or preprocessed (so white spaces are unmodified).
 160     */
 161     virtual void AddWord(const wxString& txt);
 162
 163     /**
 164         Parses the m_Source from @a begin_pos to @a end_pos - 1.
 165     */
 166     void DoParsing(const const_iterator& begin_pos, const const_iterator& end_pos);
 167
 168     /**
 169         Parses the whole m_Source.
 170     */
 171     void DoParsing();
 172
 173     /**
 174         This must be called after DoParsing().
 175     */
 176     virtual void DoneParser();
 177
 178     /**
 179         Returns pointer to the file system. Because each tag handler has
 180         reference to it is parent parser it can easily request the file by
 181         calling:
 182         @code
 183         wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg");
 184         @endcode
 185     */
 186     wxFileSystem* GetFS() const;
 187
 188     /**
 189         Returns product of parsing.
 190         Returned value is result of parsing of the document.
 191
 192         The type of this result depends on internal representation in derived
 193         parser (but it must be derived from wxObject!).
 194         See wxHtmlWinParser for details.
 195     */
 196     virtual wxObject* GetProduct() = 0;
 197
 198     /**
 199         Returns pointer to the source being parsed.
 200     */
 201     const wxString* GetSource();
 202
 203     /**
 204         Setups the parser for parsing the @a source string.
 205         (Should be overridden in derived class)
 206     */
 207     virtual void InitParser(const wxString& source);
 208
 209     /**
 210         Opens given URL and returns @c wxFSFile object that can be used to read data
 211         from it. This method may return @NULL in one of two cases: either the URL doesn't
 212         point to any valid resource or the URL is blocked by overridden implementation
 213         of @e OpenURL in derived class.
 214
 215         @param type
 216             Indicates type of the resource. Is one of:
 217             - wxHTML_URL_PAGE: Opening a HTML page.
 218             - wxHTML_URL_IMAGE: Opening an image.
 219             - wxHTML_URL_OTHER: Opening a resource that doesn't fall into
 220                                 any other category.
 221         @param url
 222             URL being opened.
 223
 224         @note
 225         Always use this method in tag handlers instead of GetFS()->OpenFile()
 226         because it can block the URL and is thus more secure.
 227         Default behaviour is to call wxHtmlWindow::OnOpeningURL of the associated
 228         wxHtmlWindow object (which may decide to block the URL or redirect it to
 229         another one),if there's any, and always open the URL if the parser is not
 230         used with wxHtmlWindow.
 231         Returned wxFSFile object is not guaranteed to point to url, it might have
 232         been redirected!
 233     */
 234     virtual wxFSFile* OpenURL(wxHtmlURLType type, const wxString& url) const;
 235
 236     /**
 237         Proceeds parsing of the document. This is end-user method. You can simply
 238         call it when you need to obtain parsed output (which is parser-specific).
 239
 240         The method does these things:
 241         -# calls InitParser(source)
 242         -# calls DoParsing()
 243         -# calls GetProduct()
 244         -# calls DoneParser()
 245         -# returns value returned by GetProduct()
 246
 247         You shouldn't use InitParser(), DoParsing(), GetProduct() or DoneParser() directly.
 248     */
 249     wxObject* Parse(const wxString& source);
 250
 251     /**
 252         Restores parser's state before last call to PushTagHandler().
 253     */
 254     void PopTagHandler();
 255
 256     /**
 257         Forces the handler to handle additional tags
 258         (not returned by wxHtmlTagHandler::GetSupportedTags).
 259         The handler should already be added to this parser.
 260
 261         @param handler
 262             the handler
 263         @param tags
 264             List of tags (in same format as GetSupportedTags()'s return value).
 265             The parser will redirect these tags to handler (until call to PopTagHandler()).
 266
 267         Example:
 268
 269         Imagine you want to parse following pseudo-html structure:
 270         @code
 271         <myitems>
 272             <param name="one" value="1">
 273             <param name="two" value="2">
 274         </myitems>
 275
 276         <execute>
 277             <param program="text.exe">
 278         </execute>
 279         @endcode
 280
 281         It is obvious that you cannot use only one tag handler for \<param\> tag.
 282         Instead you must use context-sensitive handlers for \<param\> inside \<myitems\>
 283         and \<param\> inside \<execute\>.
 284         This is the preferred solution:
 285
 286         @code
 287         TAG_HANDLER_BEGIN(MYITEM, "MYITEMS")
 288             TAG_HANDLER_PROC(tag)
 289             {
 290                 // ...something...
 291
 292                 m_Parser -> PushTagHandler(this, "PARAM");
 293                 ParseInner(tag);
 294                 m_Parser -> PopTagHandler();
 295
 296                 // ...something...
 297             }
 298         TAG_HANDLER_END(MYITEM)
 299         @endcode
 300     */
 301     void PushTagHandler(wxHtmlTagHandler* handler,
 302                         const wxString& tags);
 303
 304     /**
 305         Sets the virtual file system that will be used to request additional files.
 306         (For example @c IMG tag handler requests wxFSFile with the image data.)
 307     */
 308     void SetFS(wxFileSystem* fs);
 309
 310     /**
 311         Call this function to interrupt parsing from a tag handler.
 312         No more tags will be parsed afterward. This function may only be called
 313         from Parse() or any function called by it (i.e. from tag handlers).
 314     */
 315     virtual void StopParsing();
 316
 317 protected:
 318
 319     /**
 320         This may (and may not) be overwritten in derived class.
 321
 322         This method is called each time new tag is about to be added.
 323         @a tag contains information about the tag. (See wxHtmlTag for details.)
 324
 325         Default (wxHtmlParser) behaviour is this: first it finds a handler capable
 326         of handling this tag and then it calls handler's HandleTag() method.
 327     */
 328     virtual void AddTag(const wxHtmlTag& tag);
 329 };
 330