interface/html/htmlpars.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/htmlpars.h
   3 // Purpose:     documentation for wxHtmlTagHandler class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHtmlTagHandler
  11     @headerfile htmlpars.h wx/html/htmlpars.h
  12
  13
  14     @library{wxhtml}
  15     @category{html}
  16
  17     @seealso
  18     Overview, wxHtmlTag
  19 */
  20 class wxHtmlTagHandler : public wxObject
  21 {
  22 public:
  23     /**
  24         Constructor.
  25     */
  26     wxHtmlTagHandler();
  27
  28     /**
  29         Returns list of supported tags. The list is in uppercase and tags
  30         are delimited by ','. Example : @c "I,B,FONT,P"
  31     */
  32     virtual wxString GetSupportedTags();
  33
  34     /**
  35         This is the core method of each handler. It is called each time
  36         one of supported tags is detected. @e tag contains all necessary
  37         info (see wxHtmlTag for details).
  38
  39         @returns @true if ParseInner was called, @false otherwise.
  40     */
  41     virtual bool HandleTag(const wxHtmlTag& tag);
  42
  43     /**
  44         This method calls parser's wxHtmlParser::DoParsing method
  45         for the string between this tag and the paired ending tag:
  46         In this example, a call to ParseInner (with @e tag pointing to A tag)
  47         will parse 'Hello, world!'.
  48     */
  49     void ParseInner(const wxHtmlTag& tag);
  50
  51     /**
  52         Assigns @e parser to this handler. Each @b instance of handler
  53         is guaranteed to be called only from the parser.
  54     */
  55     virtual void SetParser(wxHtmlParser parser);
  56
  57     /**
  58         @b wxHtmlParser* m_Parser
  59
  60         This attribute is used to access parent parser. It is protected so that
  61         it can't be accessed by user but can be accessed from derived classes.
  62     */
  63 };
  64
  65
  66 /**
  67     @class wxHtmlParser
  68     @headerfile htmlpars.h wx/html/htmlpars.h
  69
  70     Classes derived from this handle the @b generic parsing of HTML documents: it
  71     scans
  72     the document and divide it into blocks of tags (where one block
  73     consists of beginning and ending tag and of text between these
  74     two tags).
  75
  76     It is independent from wxHtmlWindow and can be used as stand-alone parser
  77     (Julian Smart's idea of speech-only HTML viewer or wget-like utility -
  78     see InetGet sample for example).
  79
  80     It uses system of tag handlers to parse the HTML document. Tag handlers
  81     are not statically shared by all instances but are created for each
  82     wxHtmlParser instance. The reason is that the handler may contain
  83     document-specific temporary data used during parsing (e.g. complicated
  84     structures like tables).
  85
  86     Typically the user calls only the wxHtmlParser::Parse method.
  87
  88     @library{wxhtml}
  89     @category{html}
  90
  91     @seealso
  92     @ref overview_cells "Cells Overview", @ref overview_handlers "Tag Handlers
  93     Overview", wxHtmlTag
  94 */
  95 class wxHtmlParser
  96 {
  97 public:
  98     /**
  99         Constructor.
 100     */
 101     wxHtmlParser();
 102
 103     /**
 104         This may (and may not) be overwritten in derived class.
 105
 106         This method is called each time new tag is about to be added.
 107         @e tag contains information about the tag. (See wxHtmlTag
 108         for details.)
 109
 110         Default (wxHtmlParser) behaviour is this:
 111         First it finds a handler capable of handling this tag and then it calls
 112         handler's HandleTag method.
 113     */
 114     void AddTag(const wxHtmlTag& tag);
 115
 116     /**
 117         Adds handler to the internal list ( hash table) of handlers. This
 118         method should not be called directly by user but rather by derived class'
 119         constructor.
 120
 121         This adds the handler to this @b instance of wxHtmlParser, not to
 122         all objects of this class! (Static front-end to AddTagHandler is provided
 123         by wxHtmlWinParser).
 124
 125         All handlers are deleted on object deletion.
 126     */
 127     virtual void AddTagHandler(wxHtmlTagHandler handler);
 128
 129     /**
 130         Must be overwritten in derived class.
 131
 132         This method is called by DoParsing()
 133         each time a part of text is parsed. @e txt is NOT only one word, it is
 134         substring of input. It is not formatted or preprocessed (so white spaces are
 135         unmodified).
 136     */
 137     virtual void AddWord(const wxString& txt);
 138
 139     //@{
 140     /**
 141         Parses the m_Source from begin_pos to end_pos-1.
 142         (in noparams version it parses whole m_Source)
 143     */
 144     void DoParsing(int begin_pos, int end_pos);
 145     void DoParsing();
 146     //@}
 147
 148     /**
 149         This must be called after DoParsing().
 150     */
 151     virtual void DoneParser();
 152
 153     /**
 154         Returns pointer to the file system. Because each tag handler has
 155         reference to it is parent parser it can easily request the file by
 156         calling
 157     */
 158 #define wxFileSystem* GetFS()     /* implementation is private */
 159
 160     /**
 161         Returns product of parsing. Returned value is result of parsing
 162         of the document. The type of this result depends on internal
 163         representation in derived parser (but it must be derived from wxObject!).
 164
 165         See wxHtmlWinParser for details.
 166     */
 167     virtual wxObject* GetProduct();
 168
 169     /**
 170         Returns pointer to the source being parsed.
 171     */
 172     wxString* GetSource();
 173
 174     /**
 175         Setups the parser for parsing the @e source string. (Should be overridden
 176         in derived class)
 177     */
 178     virtual void InitParser(const wxString& source);
 179
 180     /**
 181         Opens given URL and returns @c wxFSFile object that can be used to read data
 182         from it. This method may return @NULL in one of two cases: either the URL doesn't
 183         point to any valid resource or the URL is blocked by overridden implementation
 184         of @e OpenURL in derived class.
 185
 186         @param type
 187         Indicates type of the resource. Is one of:
 188
 189         wxHTML_URL_PAGE
 190
 191
 192         Opening a HTML page.
 193
 194         wxHTML_URL_IMAGE
 195
 196
 197         Opening an image.
 198
 199         wxHTML_URL_OTHER
 200
 201
 202         Opening a resource that doesn't fall into
 203         any other category.
 204
 205         @param url
 206         URL being opened.
 207     */
 208     virtual wxFSFile* OpenURL(wxHtmlURLType type,
 209                               const wxString& url);
 210
 211     /**
 212         Proceeds parsing of the document. This is end-user method. You can simply
 213         call it when you need to obtain parsed output (which is parser-specific)
 214
 215         The method does these things:
 216
 217          calls @ref initparser() 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
 229         PushTagHandler().
 230     */
 231     void PopTagHandler();
 232
 233     /**
 234         Forces the handler to handle additional tags
 235         (not returned by wxHtmlTagHandler::GetSupportedTags).
 236         The handler should already be added to this parser.
 237
 238         @param handler
 239         the handler
 240
 241         @param tags
 242         List of tags (in same format as GetSupportedTags's return value). The parser
 243         will redirect these tags to handler (until call to PopTagHandler).
 244     */
 245     void PushTagHandler(wxHtmlTagHandler* handler,
 246                         const wxString& tags);
 247
 248     /**
 249         Sets the virtual file system that will be used to request additional
 250         files. (For example @c IMG tag handler requests wxFSFile with the
 251         image data.)
 252     */
 253 #define void SetFS(wxFileSystem fs)     /* implementation is private */
 254
 255     /**
 256         Call this function to interrupt parsing from a tag handler. No more tags
 257         will be parsed afterward. This function may only be called from
 258         Parse() or any function called
 259         by it (i.e. from tag handlers).
 260     */
 261     void StopParsing();
 262 };