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