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. @a 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
  47         In this example, a call to ParseInner (with @a tag pointing to A tag)
  48         will parse 'Hello, world!'.
  49     */
  50     void ParseInner(const wxHtmlTag& tag);
  51
  52     /**
  53         Assigns @a parser to this handler. Each @b instance of handler
  54         is guaranteed to be called only from the parser.
  55     */
  56     virtual void SetParser(wxHtmlParser parser);
  57
  58     /**
  59         @b wxHtmlParser* m_Parser
  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         This method is called each time new tag is about to be added.
 106         @a tag contains information about the tag. (See wxHtmlTag
 107         for details.)
 108         Default (wxHtmlParser) behaviour is this:
 109         First it finds a handler capable of handling this tag and then it calls
 110         handler's HandleTag method.
 111     */
 112     void AddTag(const wxHtmlTag& tag);
 113
 114     /**
 115         Adds handler to the internal list ( hash table) of handlers. This
 116         method should not be called directly by user but rather by derived class'
 117         constructor.
 118         This adds the handler to this @b instance of wxHtmlParser, not to
 119         all objects of this class! (Static front-end to AddTagHandler is provided
 120         by wxHtmlWinParser).
 121         All handlers are deleted on object deletion.
 122     */
 123     virtual void AddTagHandler(wxHtmlTagHandler handler);
 124
 125     /**
 126         Must be overwritten in derived class.
 127         This method is called by DoParsing()
 128         each time a part of text is parsed. @a txt is NOT only one word, it is
 129         substring of input. It is not formatted or preprocessed (so white spaces are
 130         unmodified).
 131     */
 132     virtual void AddWord(const wxString& txt);
 133
 134     //@{
 135     /**
 136         Parses the m_Source from begin_pos to end_pos-1.
 137         (in noparams version it parses whole m_Source)
 138     */
 139     void DoParsing(int begin_pos, int end_pos);
 140     void DoParsing();
 141     //@}
 142
 143     /**
 144         This must be called after DoParsing().
 145     */
 146     virtual void DoneParser();
 147
 148     /**
 149         Returns pointer to the file system. Because each tag handler has
 150         reference to it is parent parser it can easily request the file by
 151         calling
 152     */
 153     wxFileSystem* GetFS();
 154
 155     /**
 156         Returns product of parsing. Returned value is result of parsing
 157         of the document. The type of this result depends on internal
 158         representation in derived parser (but it must be derived from wxObject!).
 159         See wxHtmlWinParser for details.
 160     */
 161     virtual wxObject* GetProduct();
 162
 163     /**
 164         Returns pointer to the source being parsed.
 165     */
 166     wxString* GetSource();
 167
 168     /**
 169         Setups the parser for parsing the @a source string. (Should be overridden
 170         in derived class)
 171     */
 172     virtual void InitParser(const wxString& source);
 173
 174     /**
 175         Opens given URL and returns @c wxFSFile object that can be used to read data
 176         from it. This method may return @NULL in one of two cases: either the URL doesn't
 177         point to any valid resource or the URL is blocked by overridden implementation
 178         of @e OpenURL in derived class.
 179
 180         @param type
 181             Indicates type of the resource. Is one of:
 182
 183
 184
 185
 186
 187
 188             wxHTML_URL_PAGE
 189
 190
 191
 192
 193             Opening a HTML page.
 194
 195
 196
 197
 198
 199             wxHTML_URL_IMAGE
 200
 201
 202
 203
 204             Opening an image.
 205
 206
 207
 208
 209
 210             wxHTML_URL_OTHER
 211
 212
 213
 214
 215             Opening a resource that doesn't fall into
 216             any other category.
 217         @param url
 218             URL being opened.
 219     */
 220     virtual wxFSFile* OpenURL(wxHtmlURLType type,
 221                               const wxString& url);
 222
 223     /**
 224         Proceeds parsing of the document. This is end-user method. You can simply
 225         call it when you need to obtain parsed output (which is parser-specific)
 226         The method does these things:
 227          calls @ref initparser() InitParser(source)
 228          calls DoParsing()
 229          calls GetProduct()
 230          calls DoneParser()
 231          returns value returned by GetProduct
 232         You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly.
 233     */
 234     wxObject* Parse(const wxString& source);
 235
 236     /**
 237         Restores parser's state before last call to
 238         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). The parser
 251             will redirect these tags to handler (until call to PopTagHandler).
 252     */
 253     void PushTagHandler(wxHtmlTagHandler* handler,
 254                         const wxString& tags);
 255
 256     /**
 257         Sets the virtual file system that will be used to request additional
 258         files. (For example @c IMG tag handler requests wxFSFile with the
 259         image data.)
 260     */
 261     void SetFS(wxFileSystem fs);
 262
 263     /**
 264         Call this function to interrupt parsing from a tag handler. No more tags
 265         will be parsed afterward. This function may only be called from
 266         Parse() or any function called
 267         by it (i.e. from tag handlers).
 268     */
 269     void StopParsing();
 270 };