1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  xhtmlparser  declaration

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef XHTMLPARSER_H

    21 #define XHTMLPARSER_H

    22 

    23 #include <e32base.h>

    24 #include <s32strm.h>

    25 #include <txtrich.h>

    26 #include <gmxmlparser.h>

    27 

    28 class CXhtmlStackManager;

    29 class CXhtmlEntityConverter;

    30 class CMDXMLNode;

    31 class CXhtmlFontSpecs;

    32 class CXhtmlHyperLink;

    33 

    34 

    35 /**

    36  *  Abstract observer interface for notification when XHTML parsing is complete.

    37  *  It should be implemented by users of CXhtmlParser. 

    38  *

    39  *  @code

    40  *   ?good_class_usage_example(s)

    41  *  @endcode

    42  *

    43  *  @lib ?library

    44  *  @since S60 v3.2

    45  */

    46 NONSHARABLE_CLASS( MXhtmlParserObserver )

    47 	{

    48 public:

    49 

    50     /**

    51      * Call back function used to inform a client of the Parser

    52      * when a parsing operation completes.

    53      *

    54      * @since S60 v3.2

    55      */

    56 	virtual void ParseCompleteL() = 0;

    57 	

    58 	/**

    59      * Call back function used to inform a client of the Parser

    60      * about error.

    61      *

    62      * @since S60 v3.2

    63      */

    64 	virtual void ParseError( TInt aError ) = 0;

    65 	};

    66 

    67 /**

    68  *	This class forms the basis for the parser.

    69  *  It has the call back methods that the parser uses to notify

    70  *  parser events. These methods then adds the apppropriate text &

    71  *  formatting to the richtext object.

    72  *  The xhtml renderer owns this richtext object.  

    73  *

    74  *  @code

    75  *   ?good_class_usage_example(s)

    76  *  @endcode

    77  *

    78  *  @lib ?library

    79  *  @since S60 v3.2

    80  */ 

    81 NONSHARABLE_CLASS( CXhtmlParser ) : public CBase, public MMDXMLParserObserver

    82 	{	

    83 public:

    84 

    85     /**

    86      * Parser phase one constructor

    87      *

    88      * @since S60 v3.2

    89      * @param aParserObserver Observer for notification when XHTML parsing is complete

    90      * @return Created CXhtmlParser instance

    91      */	

    92 	IMPORT_C static CXhtmlParser* NewL( MXhtmlParserObserver* aParserObserver );	

    93 

    94     /**

    95     * Destructor.

    96     */

    97     virtual ~CXhtmlParser();

    98 	

    99     /**

   100      * Creates a DOM structure from a given XHTML file.

   101      *

   102      * @since S60 v3.2

   103      * @param aRFs -

   104      * @param aFileToParse -

   105      */	

   106 	IMPORT_C void CreateDomL( RFs &aRFs, const TDesC& aFileToParse );

   107 				

   108     /**

   109      * Creates a DOM structure from a given XHTML file.

   110      *

   111      * @since S60 v3.2

   112      * @param aFileHandleToParse File handle to XHTML file to parse

   113      */	

   114 	IMPORT_C void CreateDomL( RFile& aFileHandleToParse );

   115 	

   116 	/**

   117      * Constructs the richtext object from DOM structure.

   118      *

   119      * @since S60 v3.2

   120      * @param aRichText Richtext object where text, style and format is added based on parsed result

   121      */	

   122 	IMPORT_C void ParseL( CRichText& aRichText );

   123 

   124 	/**

   125      * Cancels the operation.

   126      *

   127      * @since S60 v3.2

   128      */	

   129     IMPORT_C void Cancel();

   130 

   131 

   132     /**

   133      * Sets fonts used when constructing the richtext object.

   134      * 

   135      * @since S60 v3.2

   136      * @param aBigFont Big font

   137      * @param aDefaultFont Default font

   138      * @param aSmallFont Small font

   139      * @param aCourierFont Courier font

   140      */	

   141      

   142 	IMPORT_C void SetFonts( const CFont* aBigFont,

   143 	                        const CFont* aDefaultFont,

   144 	                        const CFont* aSmallFont,

   145 	                        const CFont* aCourierFont );

   146 

   147     /**

   148      * Sets text color of default font.

   149      *

   150      * @since S60 v3.2

   151      * @param aColor Color

   152      */	

   153 	IMPORT_C void SetDefaultTextColor( TRgb aColor );

   154 	

   155 	/**

   156      * Sets parsing mode.

   157      *

   158      * @since S60 v3.2

   159      * @param aPlainText If true, plain text mode is used (no style and format added) 

   160      * @param aShowUrls 

   161      */	

   162 	IMPORT_C void SetMode( TBool aPlainText, TBool aShowUrls );

   163 

   164     /**

   165      * Gets information (start position, end position and target URL)

   166      * of hyperlink by hyperlink index. Index starts from 0. 

   167      *

   168      * @since S60 v3.2

   169      * @param aIndex Index of requested hyperlink

   170      * @param aStartPos Start position of hyperlink text. Filled by this function

   171      * @param aEndPos End position of hyperlink text. Filled by this function

   172      * @param aAddress target URL of hyperlink. Filled by this function

   173      * @return KErrNone if completed successfully, KErrArgument if index is out of bounds.

   174      */	

   175 	IMPORT_C TInt HyperLink( TInt aIndex, TInt& aStartPos, TInt& aEndPos, TPtrC& aAddress );

   176      

   177     /**

   178      * Returns a number of found hyperlinks. 

   179      *

   180      * @since S60 v3.2

   181      * @return Number of found hyperlinks

   182      */	

   183 	IMPORT_C TInt HyperLinkCount();

   184 	

   185 	

   186 public: // inlines

   187 

   188     /**

   189      * Sets a new limit for nested lists. Default value is 5. 

   190      *

   191      * @param Limit value

   192      */

   193     inline void SetLimitForNestedLists( TInt aLimit );    

   194 

   195     /**

   196      * Sets a new width for indent. Default width is width of 4 space characters. 

   197      *

   198      * @param Number of space characters used to calculate width of indent

   199      */

   200     inline void SetIndentWidth( TInt aCharacters );    

   201 

   202 

   203     

   204 protected:

   205 

   206 // from base class MMDXMLParserObserver

   207 

   208 

   209     /**

   210      * From MMDXMLParserObserver.

   211      * XML parser calls this when parsing is completed (DOM is filled).

   212      * XHTML parser uses this DOM to perform its own parsing.

   213      *

   214      * @since S60 v3.2

   215      */

   216     void ParseFileCompleteL();

   217     

   218 				

   219 private:

   220 

   221 	CXhtmlParser( MXhtmlParserObserver* aParserObserver );

   222 	void ConstructL( );

   223 	

   224     /**

   225      * Performs XHTML parsing using XML document filled by XML parser.

   226      *

   227      * @since S60 v3.2

   228      * @param aXmlDocument Given XML document

   229      */	

   230 	void ParseDomL( CMDXMLDocument* aXmlDocument );

   231 

   232     /**

   233      * Handles a (begin) node in DOM document.

   234      * Calls corresponding handler based on node type (Element, Text, Comment etc.) 

   235      *

   236      * @since S60 v3.2

   237      * @param aNode Node to be handled.

   238      * @return True if completed successfully

   239      */	

   240 	void OpenNodeL( CMDXMLNode* aNode );

   241 

   242     /**

   243      * 

   244      * Handles a (end) node in DOM document.

   245      *

   246      * @since S60 v3.2

   247      * @param aNode Node to be handled.

   248      */	

   249 	void CloseNodeL( CMDXMLNode* aNode );

   250 

   251     /**

   252      * Performs some preparations before handling of begin tag.

   253      *

   254      * @since S60 v3.2

   255      */	

   256 	void PrepareForBeginElementL( const TDesC& aName );

   257 

   258     /**

   259      * Performs needed operations for each begin tag. (e.g. for <div>, <p> etc.).

   260      * Contains main funtionality of parsing logic. (possible attributes are not

   261      * handled here, but in AttributevalueL function)

   262      *

   263      * @since S60 v3.2

   264      * @param aName Name of the tag (without angle brackets)

   265      */	

   266 	void BeginElementL( const TDesC& aName );

   267 

   268     /**

   269      * Performs needed operations for each end tag. (e.g. for  </p>, </div> etc.).

   270      * Contains main funtionality of parsing logic.

   271      *

   272      * @since S60 v3.2

   273      * @param aName Name of the tag (without angle brackets)

   274      */	

   275 	void EndElementL( const TDesC& aName );

   276 

   277    /**

   278      * Begins a new style. 

   279      * 

   280      * Creates a new StyleInfo item and adds it to the stack. This info is used later when

   281      * a new style is applied to richtext and it contains e.g. the start position of text to

   282      * be changed by a new style.

   283      *

   284      * @since S60 v3.2

   285      */	

   286 	void BeginStyleL();

   287 

   288     /**

   289      * Ends a style

   290      *

   291      * Applies a new style to richtext object and removes the StyleInfo item from stack.

   292      * Note that a new style is applied only if style is changed by function ChangeCurrentStyleL.

   293      * In this case also current CharFormatLayer (created in ChangeCurrentStyleL) is removed by

   294      * calling CleanCharLayer.

   295      *

   296      * @since S60 v3.2

   297      */	

   298 	void EndStyleL();

   299 

   300     /**

   301      * Changes current style.

   302      *

   303      * Applies "old" style to the richtext object (from iStylePos to current position).

   304      * Creates a new CharFormatLayer with new style (based on old layer in iCurrentCharLayer)

   305      * and marks the previous StyleInfo item in stack to be changed.

   306      * So, because item is marked to be changed, this new style is recognized in EndStyleL and

   307      * applied to the richtext object.  

   308      *

   309      * @since S60 v3.2

   310      * @param charFormat ?description

   311      * @param charFormatMask ?description

   312      */	

   313 	void ChangeCurrentStyleL( TCharFormat charFormat, TCharFormatMask charFormatMask );

   314 

   315     /**

   316      * Applies current style to richtext object (from iStylePos to end of document)

   317      *

   318      * @since S60 v3.2

   319      */	

   320 	void ApplyStyleL();

   321 

   322     /**

   323      * Begins a new paragraph. 

   324      *

   325      * @since S60 v3.2

   326      * @param aAlignment Alignment

   327      */	

   328 	void BeginParagraphL( CParaFormat::TAlignment aAlignment );

   329 

   330     /**

   331      * Ends a paragraph.

   332      *

   333      * @since S60 v3.2

   334      */	

   335 	void EndParagraphL();

   336 

   337     /**

   338      * Applies a paragraph format to richtext object.

   339      *

   340      * @since S60 v3.2

   341      * @param aParaStart Start position of the paragraph

   342      * @param aAlignment Alignment

   343      */	

   344 	void ApplyParagraphL( TInt aParaStart, CParaFormat::TAlignment aAlignment );

   345 

   346     /**

   347      * Begins a new list (with <ol> or <ul> tag.)

   348      * Begins a new paragraphs and creates a new ListInfo item to stack to store list information.

   349      * 

   350      * @since S60 v3.2

   351      * @param aListContext Type of the current list, ordered or unordered

   352      */	

   353 	void BeginListL( TInt aListContext );

   354 

   355     /**

   356      * Ends a list.

   357      * Ends paragraphs and removes ListInfo item from stack.

   358      *

   359      * NOTE: TELL HERE MORE ABOUT FUNCTIONALITY!!!!!!!!!!!!!!

   360      *

   361      * @since S60 v3.2

   362      */	

   363 	void EndListL();

   364 

   365     /**

   366      * NOTE: TELL HERE MORE ABOUT FUNCTIONALITY!!!!!!!!!!!!!!

   367      *

   368      * @since S60 v3.2

   369      * @return ?description

   370      */	

   371 	void BeginListItemL();

   372 

   373     /**

   374      * Stores the start position of hyperlink to be used later.

   375      * This function is called when <a> tag is found.

   376      *

   377      * @since S60 v3.2

   378      * @param aBeginPosition Start position of the hyperlink

   379      */	

   380 	void BeginHyperLink( TInt aBeginPosition );

   381 

   382     /**

   383      * Creates a new hyperlink item and adds it to hyperlink array.

   384      * This item contains begin and end position of hyperlink text and

   385      * target URL of the link.

   386      * User is later able to get these hyperlinks by function HyperLink.

   387      *

   388      * This function is called when </a> tag is found.

   389      *

   390      * @since S60 v3.2

   391      * @param aEndPosition End position of the hyperlink

   392      */	

   393 	void EndHyperLinkL( TInt aEndPosition );

   394 

   395     /**

   396      * This function adds the actual text to richtext object.

   397      * Text can be added as such (if preformatting is in use) or

   398      * so that extra whitespaces are removed (preformatting not in use)

   399      *

   400      * @since S60 v3.2

   401      * @param aData Text to be added to richtext object

   402      */	

   403 	void ContentL( const TDesC& aData );

   404 

   405     /**

   406      * Removes extra whitespace characters from a text. 

   407      *

   408      * @since S60 v3.2

   409      * @param aData Text to be collapsed down 

   410      */	

   411 	void CollapseWhiteSpaces( TDes& aData );

   412 

   413     /**

   414      * Handles attributes in begin tags.

   415      * Only a few attributes are supported. 

   416      *

   417      * @since S60 v3.2

   418      * @param aName Name of the attribute

   419      * @param aValue Value of the attribute

   420      */	

   421 	void AttributeValueL( const TDesC& aName, const TDesC& aValue );

   422 

   423     /**

   424      * Sets target URL of current hyperlink.

   425      *

   426      * @since S60 v3.2

   427      * @param aUrl Target URL of hyperlink

   428      */	

   429 	void SetReferenceL( const TDesC& aUrl );

   430 

   431     /**

   432      * Removes all space characters from the string. 

   433      *

   434      * @since S60 v3.2

   435      * @param aString Text to be handled

   436      */	

   437 	void RemoveAllSpace( TDes& aString );

   438 

   439     /**

   440      * Splits passed attribute string to name and value.

   441      *

   442      * @since S60 v3.2

   443      * @param aString Attribute string

   444      * @param aAttributeName Attribute name

   445      * @param aAttributeValue Attribute value

   446      */	

   447 	void SplitAttribute( TPtrC& aString, TPtrC& aAttributeName, 

   448 		                    TPtrC& aAttributeValue );

   449       

   450     /**

   451      * Parses color value from given string and creates TRgb object based on it.

   452      * Supports both numberic format and name format (e.g. red or #ff0000) 

   453      *

   454      * @since S60 v3.2

   455      * @param aString String that contains the color value

   456      * @param aTransparent The function sets this true if color is transparent

   457      * @return TRgb object based on given color

   458      */	

   459 	TRgb ParseColor( const TDesC& aString, TBool& aTransparent );

   460 	

   461     /**

   462      * CDataL

   463      *

   464      * @since S60 v3.2

   465      * @param aData Data

   466      */	

   467 	void CdataL( const TDesC& aData );

   468 

   469     /**

   470      * Cleans current CharFormatLayer and sets previous layer to active.

   471      * This is used to return to old style at the end of current style handling.

   472      *

   473      * @since S60 v3.2

   474      * @return Previous CharFormatLayer

   475      */	

   476 	CCharFormatLayer* CleanCharLayer();

   477 

   478     /**

   479      * Converts between arabic-indic digits and european digits based on existing language setting.

   480      * So it'll convert any digit from the string

   481      * to use either european digits or arabic-indic digits based on current settings.

   482      *

   483      * @since S60 v3.2

   484      * @param aFieldString: Data buffer used in conversion.

   485      * @param @param aFieldData: Return converted data in this parameter.

   486      */	

   487 	void DoNumberConversion( HBufC* aFieldString, TPtrC& aFieldData ) const;

   488 

   489     /**

   490      * Sets all internal variables to initial state. 

   491      *

   492      * @since S60 v3.2

   493      */	

   494 	void ResetValues();

   495 	

   496 	/**

   497      * Inserts text to the RichText object. 

   498      *

   499      * @since S60 v3.2

   500      * @param aData Text to be written

   501      */	

   502 	void InsertTextL( const TDesC& aText );

   503 	

   504 	/**

   505      * Inserts character to the RichText object. 

   506      *

   507      * @since S60 v3.2

   508      * @param aData Character to be written

   509      */	

   510     void InsertCharacterL( const TChar aText );

   511     

   512     /**

   513      * Appends a new paragraph to the RichText object. 

   514      *

   515      * @since S60 v3.2

   516      * @param aPlainText tells if plain text is used or not

   517      */	

   518     void AppendParagraphL( TBool aPlainText );

   519     

   520     /**

   521      * Inserts line break to the RichText object. 

   522      *

   523      * @since S60 v3.2

   524      */	

   525     void InsertLineBreak();

   526     

   527     /**

   528      * Inserts "forced" line break to the RichText object. 

   529      * This is called when <br> tag is found.

   530      *

   531      * @since S60 v3.2

   532      */	

   533     void InsertForcedLineBreak();

   534   

   535 	                        

   536                            

   537 private: // data

   538 	

   539 	/**

   540      * Tells if parsing is allowed or not. If not, no text is applied to RichText.

   541      */

   542 	TBool iParsingAllowed;

   543 	

   544 	/**

   545      * If this is true, XHTML is parsed as plain text. 

   546      * In this case styles and paragraphs are not applied to rendered text.

   547      */

   548 	TBool iPlainText;

   549 	

   550 	/**

   551      * If this is true, URL addresses are shown after links.  

   552      */

   553 	TBool iShowUrls;

   554 	

   555 	/**

   556      * Tells if preformatted parsing is in use. (true between tags <pre> and </pre>).

   557      * When preformatted parsing is in use, text is added to RichText in same format

   558      * as it is written between tags <pre> and </pre>.

   559      * For example all whitespaces are added etc.

   560      * However, if there is another tags inside <pre> and </pre> tags, they are parsed

   561      * normally. (For example styles are changed normally: <p style="color:red">

   562      * changes the text color to red also in preformatted text.)

   563      *  

   564      */

   565 	TInt iPreformatted;

   566 	

   567 	/**

   568      * Current text alignment (left, center or right). Used in paragraphs.

   569      * Changed by tag with corresponding style atribute, for example:

   570      * <p style="text-align:right">

   571      *

   572      */

   573 	CParaFormat::TAlignment iAlignment;

   574 	

   575 	/**

   576      * Start position of the current style. Every time when a new style is added to

   577      * richtext object, it is applied from iStylePos to the end of document. After that,

   578      * iStylePos is set to point to the end of document. 

   579      */

   580 	TInt iStylePos;

   581 	

   582 	/**

   583      * Tells if a new paragraph has already been added to richtext object AND

   584      * no characters are added after that. Used to avoid adding of empty paragraphs

   585      * For example. if there are several end tags without text

   586      * between them and each end tag creates a new paragraph, this generates unnecessary

   587      * paragraphs (also shown as extra lines in text) without handling of the situations with this variable.

   588      * So, if a new paragraph has already added and no text after that (=this variable is true),

   589      * new paragraphs are not added.  

   590      */

   591 	TBool iNewParagraph;

   592 	

   593 	/**

   594      * iNewLines

   595      */

   596 	TInt iNewLines;

   597 	

   598 	/**

   599      * iForcedNewLines

   600      */

   601 	TInt iForcedNewLines;

   602 	

   603 	/**

   604      * iSkipWhiteSpaces 

   605      */

   606 	TBool iSkipWhiteSpaces;

   607 	

   608 	/**

   609      * Tells is current alignment has changed by style attribute. (e.g. <p style="text-align:right">) 

   610      */

   611 	TBool iAlignmentChanged;

   612 	

   613     /**

   614      * Tells if tag in question is <img>. Alt attributes are handled only in this case. 

   615      */

   616 	TBool iImageFound;

   617 	

   618 	/**

   619      * iFirstTextLineAdded 

   620      */

   621 	TBool iFirstTextLineAdded;

   622 

   623 	/**

   624      * Current list context, ordered or unordered list. Used to define how list items are rendered.

   625      * (in orderd list with item number and in unordered list with bullets)

   626      */

   627 	TInt iCurrentListContext;

   628 

   629 	/**

   630      * Index of current level of definition list, tells in which level we are now.

   631      * (There might be several nested definition lists, this is used to support for this). 

   632      * Used to define margins widths (with other same kind of variables) when a new

   633      * paragraph is created.

   634      */

   635 	TInt iDefListLevel;

   636 

   637 	/**

   638      * Index of current level of block quote, tells in which level we are now.

   639      * 

   640      * (In correct XHTML there may NOT be nested block quotes, but this is needed

   641      * also for one-level blocquote. Support also nested block-quotes although they are not allowed

   642      * in XHTML).

   643      * Used to define margins widths (with other same kind of variables) when a new

   644      * paragraph is created.

   645      */

   646 	TInt iBlockQuoteLevel;

   647 

   648 	/**

   649      * Stores target URL address of current hyperlink.

   650      */

   651 	TInt iHyperLinkPos;

   652 	

   653 	/**

   654      * Default text color. Set by user by calling SetTextColor.

   655      */

   656 	TRgb iTextColor;

   657 

   658 	/**

   659      * Default margin width of ordered and unordered lists.

   660      * Set by user by calling SetMargins.

   661      */

   662 	TInt iListMargin;

   663 

   664 	/**

   665      * Default margin width of definition lists.

   666      * Set by user by calling SetMargins.

   667      */

   668 	TInt iDefListMargin;

   669 

   670 	/**

   671      * Default margin width of block quote.

   672      * Set by user by calling SetMargins.

   673      */

   674 	TInt iBlockQuoteMargin;

   675 

   676 	/**

   677      * Observer instance for notification when XHTML parsing is complete. 

   678      * Not own.

   679      */

   680 	MXhtmlParserObserver* iObserver;

   681 	

   682 	/**

   683      * XML parser used to parse from XML file to DOM document.

   684      * Own.

   685      */

   686 	CMDXMLParser* iXmlParser;

   687 	

   688 	/**

   689      * RichText object that is modified by XHTML parser.

   690      * XHTML parser creates a formatted text based on parsed XHTML and adds

   691      * the text to RichText object (with styles and paragraphs).

   692      * RichText is passed to parser in both ParseL functions.

   693      * The xhtml renderer owns this richtext object. 

   694      * Not own.

   695      */

   696     CRichText* iRichText;

   697     

   698     

   699     

   700     CMDXMLDocument* iXmlDocument;

   701 	

   702 	/**

   703      * Stackmanager for handling of stacks.

   704      * Own.

   705      */

   706 	CXhtmlStackManager* iStackManager;	

   707 	

   708 	/**

   709      * Stores font-related information

   710      * Own.

   711      */

   712 	CXhtmlFontSpecs* iXhtmlFontSpecs;

   713 	

   714 	/**

   715      * current CharFormatLayer that is based on GlobalCharFormatLayer

   716      * of Richtext object. New layers are added in function ChangeCurrentStyle

   717      * and removed in function CleanCharlayer. This variable tells the "style" that

   718      * is applied to text (e.g. color, fontsize etc.) 

   719      * Own.

   720      */

   721 	CCharFormatLayer* iCurrentCharLayer;

   722 	

   723 	/**

   724      * Array of hyperlink information. Contains information of all found hyperlinks.

   725      * Own.

   726      */

   727 	CArrayPtrFlat<CXhtmlHyperLink>* iHyperLinkArray;

   728 	

   729 	/**

   730      * Stores the value of current "href" attribute of <a> tag.

   731      * In practice the value contains target URL of the link.

   732      * Not own.

   733      */

   734 	HBufC* iHyperLinkAddress;

   735 	

   736 	/**

   737      * The number of space characters used to calculate the width of indent.

   738      * Default value is 4 (space characters).

   739      */

   740 	TInt iIndentWidth;

   741 	

   742 	/**

   743      * Maximum number of nested list levels.

   744      * Default value is 5 

   745      */

   746 	TInt iMaxListLevels;

   747 	};

   748 	

   749 #include <xhtmlparser.inl>

   750 

   751 #endif