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