interface/wx/html/htmlpars.h

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