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