home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / wxos2240.zip / wxWindows-2.4.0 / include / wx / html / htmlpars.h < prev    next >
C/C++ Source or Header  |  2002-11-10  |  10KB  |  273 lines
  1. /////////////////////////////////////////////////////////////////////////////
  2. // Name:        htmlpars.h
  3. // Purpose:     wxHtmlParser class (generic parser)
  4. // Author:      Vaclav Slavik
  5. // RCS-ID:      $Id: htmlpars.h,v 1.14.2.2 2002/11/09 19:29:43 VS Exp $
  6. // Copyright:   (c) 1999 Vaclav Slavik
  7. // Licence:     wxWindows Licence
  8. /////////////////////////////////////////////////////////////////////////////
  9.  
  10.  
  11. #ifndef _WX_HTMLPARS_H_
  12. #define _WX_HTMLPARS_H_
  13.  
  14. #if defined(__GNUG__) && !defined(__APPLE__)
  15. #pragma interface "htmlpars.h"
  16. #endif
  17.  
  18. #include "wx/defs.h"
  19. #if wxUSE_HTML
  20.  
  21. #include "wx/html/htmltag.h"
  22. #include "wx/filesys.h"
  23. #include "wx/hash.h"
  24. #include "wx/fontenc.h"
  25.  
  26. class WXDLLEXPORT wxMBConv;
  27. class WXDLLEXPORT wxHtmlParser;
  28. class WXDLLEXPORT wxHtmlTagHandler;
  29. class WXDLLEXPORT wxHtmlEntitiesParser;
  30.  
  31. class wxHtmlTextPieces;
  32. class wxHtmlParserState;
  33.  
  34.  
  35. enum wxHtmlURLType
  36. {
  37.     wxHTML_URL_PAGE,
  38.     wxHTML_URL_IMAGE,
  39.     wxHTML_URL_OTHER
  40. };
  41.  
  42. // This class handles generic parsing of HTML document : it scans
  43. // the document and divide it into blocks of tags (where one block
  44. // consists of starting and ending tag and of text between these
  45. // 2 tags.
  46. class WXDLLEXPORT wxHtmlParser : public wxObject
  47. {
  48.     DECLARE_ABSTRACT_CLASS(wxHtmlParser)
  49.  
  50. public:
  51.     wxHtmlParser();
  52.     virtual ~wxHtmlParser();
  53.  
  54.     // Sets the class which will be used for opening files
  55.     void SetFS(wxFileSystem *fs) { m_FS = fs; }
  56.  
  57.     wxFileSystem* GetFS() const { return m_FS; }
  58.  
  59.     // Opens file if the parser is allowed to open given URL (may be forbidden
  60.     // for security reasons)    
  61.     virtual wxFSFile *OpenURL(wxHtmlURLType type, const wxString& url) const;
  62.  
  63.     // You can simply call this method when you need parsed output.
  64.     // This method does these things:
  65.     // 1. call InitParser(source);
  66.     // 2. call DoParsing();
  67.     // 3. call GetProduct(); (it's return value is then returned)
  68.     // 4. call DoneParser();
  69.     wxObject* Parse(const wxString& source);
  70.  
  71.     // Sets the source. This must be called before running Parse() method.
  72.     virtual void InitParser(const wxString& source);
  73.     // This must be called after Parse().
  74.     virtual void DoneParser();
  75.     
  76.     // May be called during parsing to immediately return from Parse().
  77.     virtual void StopParsing() { m_stopParsing = TRUE; }
  78.  
  79.     // Parses the m_Source from begin_pos to end_pos-1.
  80.     // (in noparams version it parses whole m_Source)
  81.     void DoParsing(int begin_pos, int end_pos);
  82.     void DoParsing();
  83.  
  84.     // Returns pointer to the tag at parser's current position
  85.     wxHtmlTag *GetCurrentTag() const { return m_CurTag; }
  86.  
  87.     // Returns product of parsing
  88.     // Returned value is result of parsing of the part. The type of this result
  89.     // depends on internal representation in derived parser
  90.     // (see wxHtmlWinParser for details).
  91.     virtual wxObject* GetProduct() = 0;
  92.  
  93.     // adds handler to the list & hash table of handlers.
  94.     virtual void AddTagHandler(wxHtmlTagHandler *handler);
  95.  
  96.     // Forces the handler to handle additional tags (not returned by GetSupportedTags). 
  97.     // The handler should already be in use by this parser.
  98.     // Example: you want to parse following pseudo-html structure:
  99.     //   <myitems>
  100.     //     <it name="one" value="1">
  101.     //     <it name="two" value="2">
  102.     //   </myitems>
  103.     //   <it> This last it has different meaning, we don't want it to be parsed by myitems handler!
  104.     // handler can handle only 'myitems' (e.g. it's GetSupportedTags returns "MYITEMS")
  105.     // you can call PushTagHandler(handler, "IT") when you find <myitems>
  106.     // and call PopTagHandler() when you find </myitems>
  107.     void PushTagHandler(wxHtmlTagHandler *handler, wxString tags);
  108.  
  109.     // Restores state before last call to PushTagHandler
  110.     void PopTagHandler();
  111.  
  112.     wxString* GetSource() {return &m_Source;}
  113.     void SetSource(const wxString& src);
  114.     
  115.     // Sets HTML source and remebers current parser's state so that it can
  116.     // later be restored. This is useful for on-line modifications of 
  117.     // HTML source (for example, <pre> handler replaces spaces with  
  118.     // and newlines with <br>)
  119.     virtual void SetSourceAndSaveState(const wxString& src);
  120.     // Restores parser's state from stack or returns FALSE if the stack is
  121.     // empty
  122.     virtual bool RestoreState();
  123.     
  124.     // Parses HTML string 'markup' and extracts charset info from <meta> tag
  125.     // if present. Returns empty string if the tag is missing.
  126.     // For wxHTML's internal use.
  127.     static wxString ExtractCharsetInformation(const wxString& markup);
  128.  
  129. protected:
  130.     // DOM structure
  131.     void CreateDOMTree();
  132.     void DestroyDOMTree();
  133.     void CreateDOMSubTree(wxHtmlTag *cur,
  134.                           int begin_pos, int end_pos, 
  135.                           wxHtmlTagsCache *cache);
  136.  
  137.     // Adds text to the output.
  138.     // This is called from Parse() and must be overriden in derived classes.
  139.     // txt is not guaranteed to be only one word. It is largest continuous part of text
  140.     // (= not broken by tags)
  141.     // NOTE : using char* because of speed improvements
  142.     virtual void AddText(const wxChar* txt) = 0;
  143.  
  144.     // Adds tag and proceeds it. Parse() may (and usually is) called from this method.
  145.     // This is called from Parse() and may be overriden.
  146.     // Default behavior is that it looks for proper handler in m_Handlers. The tag is
  147.     // ignored if no hander is found.
  148.     // Derived class is *responsible* for filling in m_Handlers table.
  149.     virtual void AddTag(const wxHtmlTag& tag);
  150.     
  151.     // Returns entity parser object, used to substitute HTML &entities;
  152.     wxHtmlEntitiesParser *GetEntitiesParser() const { return m_entitiesParser; }
  153.  
  154. protected:
  155.     // DOM tree:
  156.     wxHtmlTag *m_CurTag;
  157.     wxHtmlTag *m_Tags;
  158.     wxHtmlTextPieces *m_TextPieces;
  159.     size_t m_CurTextPiece;
  160.  
  161.     wxString m_Source;
  162.     
  163.     wxHtmlParserState *m_SavedStates;
  164.     
  165.     // handlers that handle particular tags. The table is accessed by
  166.     // key = tag's name.
  167.     // This attribute MUST be filled by derived class otherwise it would
  168.     // be empty and no tags would be recognized
  169.     // (see wxHtmlWinParser for details about filling it)
  170.     // m_HandlersHash is for random access based on knowledge of tag name (BR, P, etc.)
  171.     //      it may (and often does) contain more references to one object
  172.     // m_HandlersList is list of all handlers and it is guaranteed to contain
  173.     //      only one reference to each handler instance.
  174.     wxList m_HandlersList;
  175.     wxHashTable m_HandlersHash;
  176.  
  177.     // class for opening files (file system)
  178.     wxFileSystem *m_FS;
  179.     // handlers stack used by PushTagHandler and PopTagHandler
  180.     wxList *m_HandlersStack;
  181.     
  182.     // entity parse
  183.     wxHtmlEntitiesParser *m_entitiesParser;
  184.     
  185.     // flag indicating that the parser should stop
  186.     bool m_stopParsing;
  187. };
  188.  
  189.  
  190.  
  191. // This class (and derived classes) cooperates with wxHtmlParser.
  192. // Each recognized tag is passed to handler which is capable
  193. // of handling it. Each tag is handled in 3 steps:
  194. // 1. Handler will modifies state of parser
  195. //    (using it's public methods)
  196. // 2. Parser parses source between starting and ending tag
  197. // 3. Handler restores original state of the parser
  198. class WXDLLEXPORT wxHtmlTagHandler : public wxObject
  199. {
  200.     DECLARE_ABSTRACT_CLASS(wxHtmlTagHandler)
  201.  
  202. public:
  203.     wxHtmlTagHandler() : wxObject () { m_Parser = NULL; }
  204.  
  205.     // Sets the parser.
  206.     // NOTE : each _instance_ of handler is guaranteed to be called
  207.     // only by one parser. This means you don't have to care about
  208.     // reentrancy.
  209.     virtual void SetParser(wxHtmlParser *parser) 
  210.         { m_Parser = parser; }
  211.  
  212.     // Returns list of supported tags. The list is in uppercase and
  213.     // tags are delimited by ','.
  214.     // Example : "I,B,FONT,P"
  215.     //   is capable of handling italic, bold, font and paragraph tags
  216.     virtual wxString GetSupportedTags() = 0;
  217.  
  218.     // This is hadling core method. It does all the Steps 1-3.
  219.     // To process step 2, you can call ParseInner()
  220.     // returned value : TRUE if it called ParseInner(),
  221.     //                  FALSE etherwise
  222.     virtual bool HandleTag(const wxHtmlTag& tag) = 0;
  223.  
  224. protected:
  225.     // parses input between beginning and ending tag.
  226.     // m_Parser must be set.
  227.     void ParseInner(const wxHtmlTag& tag) 
  228.         { m_Parser->DoParsing(tag.GetBeginPos(), tag.GetEndPos1()); }
  229.  
  230.     wxHtmlParser *m_Parser;
  231. };
  232.  
  233.  
  234. // This class is used to parse HTML entities in strings. It can handle
  235. // both named entities and &#xxxx entries where xxxx is Unicode code.
  236. class WXDLLEXPORT wxHtmlEntitiesParser : public wxObject
  237. {
  238.     DECLARE_DYNAMIC_CLASS(wxHtmlEntitiesParser)
  239.  
  240. public:
  241.     wxHtmlEntitiesParser();
  242.     virtual ~wxHtmlEntitiesParser();
  243.     
  244.     // Sets encoding of output string.
  245.     // Has no effect if wxUSE_WCHAR_T==0 or wxUSE_UNICODE==1
  246.     void SetEncoding(wxFontEncoding encoding);
  247.     
  248.     // Parses entities in input and replaces them with respective characters
  249.     // (with respect to output encoding)
  250.     wxString Parse(const wxString& input);
  251.  
  252.     // Returns character for given entity or 0 if the enity is unknown
  253.     wxChar GetEntityChar(const wxString& entity);
  254.  
  255.     // Returns character that represents given Unicode code
  256. #if wxUSE_UNICODE
  257.     wxChar GetCharForCode(unsigned code) { return (wxChar)code; }
  258. #else
  259.     wxChar GetCharForCode(unsigned code);
  260. #endif
  261.  
  262. protected:
  263. #if wxUSE_WCHAR_T && !wxUSE_UNICODE
  264.     wxMBConv *m_conv;
  265.     wxFontEncoding m_encoding;
  266. #endif
  267. };
  268.  
  269.  
  270. #endif
  271.  
  272. #endif // _WX_HTMLPARS_H_
  273.