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:  Plugin utility used for automatic tags ( http, email, phone numbers )

    15 *                syntax highlighting in text viewers

    16 *

    17 *

    18 */

    19 

    20 

    21 

    22 #ifndef ITEMFINDER_H

    23 #define ITEMFINDER_H

    24 

    25 // INCLUDES

    26 #include <mparser.h>                       // for MParser

    27 

    28 // CONSTANTS

    29 

    30 // FORWARD DECLARATIONS

    31 class CEikRichTextEditor;

    32 class CFindItemEngine;

    33 class CItemFinderAsyncParser;

    34 class CSchemeResolver;

    35 class CFindItemEngine;

    36 

    37 // CLASS DECLARATION

    38 class MItemFinderObserver

    39     {

    40     public:

    41         virtual void HandleParsingComplete() = 0;

    42     };

    43 

    44 /**

    45 * Parser plugin

    46 */

    47 NONSHARABLE_CLASS(CItemFinder) :

    48     public CBase,

    49     public MParser

    50     {

    51     public:  // Constructors and destructor

    52 

    53         /**

    54         * Destructor.

    55         */

    56         ~CItemFinder();

    57 

    58     public: // definitions

    59     

    60         enum TItemType

    61             {

    62             ENoneSelected = 0,

    63             EUrlAddress = 1,

    64             EEmailAddress = 2,

    65             EPhoneNumber = 4,

    66             EUriScheme =8

    67             };

    68 

    69         enum TFindDirection

    70             {

    71             EInit = 0,

    72             ENextDown = 1,

    73             ENextUp = 2,

    74             EInitDown = 3,

    75             EInitUp = 4

    76             };

    77 

    78         /*class CFindItemDef: public CBase // @deprecated since 3.2

    79             {

    80             public:

    81                 ~CFindItemDef(){ if ( iItemDescriptor ) delete iItemDescriptor; }

    82                 TItemType iItemType;

    83                 HBufC* iItemDescriptor;

    84                 TInt iDisplayLength;

    85             };*/

    86 

    87         class CFindItemExt: public CBase // replaces CFindItemDef.

    88             {

    89             public:

    90                 IMPORT_C ~CFindItemExt();// { if ( iItemDescriptor ) delete iItemDescriptor; }

    91                 TItemType iItemType;

    92                 HBufC* iItemDescriptor;

    93                 TInt iStart;

    94                 TInt iEnd;

    95             };

    96 

    97     public: // New functions

    98         /**

    99         * @since Series 60 2.6

   100         * Creates instance of ItemFinder and adds it to editor parser list (TLS)

   101         * Must be called before editor creation in order to have effect

   102         *

   103         * @param    aFindFlags   Find mode ( defaults to all )

   104         * @return                New instance

   105         */

   106         IMPORT_C static CItemFinder* NewL( TInt aFindFlags = EUrlAddress|EEmailAddress|EPhoneNumber );

   107 

   108         /**

   109         * @since Series 60 2.6

   110         * Notify item finder to move focus to next item or scroll display

   111         *

   112         * @param    aDirection   Direction ( ENextDown or ENextUp )

   113         * @return                EFalse if command had no effect, ETrue otherwise

   114         */

   115         IMPORT_C TBool NextItemOrScrollL( TFindDirection aDirection );

   116 

   117         /**

   118         * @since Series 60 2.6

   119         * Sets the find mode, can be used for initialize parsers for current position after eg screen size change

   120         * Refreshes parser data if editor and text set.

   121         *

   122         * @param    aFindFlags      Any combination of (EUrlAddress|EEmailAddress|EPhoneNumber)

   123         */

   124         IMPORT_C void SetFindModeL( TInt aFindFlags );

   125 

   126         /**

   127         * @since Series 60 2.6

   128         * Set pointer to applications instance of CEikRichTextEditor.

   129         * If editor is not set, all methods return immediately

   130         * Editor should have texts installed when application sets the pointer

   131         * Refreshes parser data if text is set.

   132         *

   133         * @param    aEditor Pointer array pointing applications editor instance

   134         */

   135         IMPORT_C void SetEditor( CEikRichTextEditor** aEditor );

   136 

   137     public: // From MParser

   138 

   139         IMPORT_C TBool ParseThisText(

   140             const CRichText& aTextObj,

   141             TBool aAllowBack,

   142             TInt aStartScan,

   143             TInt aScanLength,

   144             TInt& aStartTag,

   145             TInt& aTagLength );

   146 

   147         IMPORT_C const TDesC& CreateDoItText(

   148             const CRichText& aTextObj,

   149             TInt aStartText,

   150             TInt aLength );

   151 

   152         IMPORT_C void ActivateThisTextL(

   153             const CRichText& aTextObj,

   154             TInt aStartText,

   155             TInt aLength );

   156 

   157         IMPORT_C TBool ReformatOnRecognise() const;

   158 

   159         IMPORT_C TBool ReformatOnRollover() const;

   160 

   161         IMPORT_C void GetRecogniseFormat( TCharFormat& aFormat );

   162 

   163         IMPORT_C void GetRolloverFormat( TCharFormat& aFormat );

   164 

   165         IMPORT_C TBool ConfirmCursorOverTag(

   166             const CRichText& aTextObj,

   167             TInt aTagStart,

   168             TInt aTagLen,

   169             TInt aCurPos );

   170 

   171         IMPORT_C void Release();

   172 

   173         IMPORT_C void MParser_Reserved_2();

   174 

   175     public: // new methods

   176         /**

   177         * @since Series 60 2.6

   178         * Returns document position of next item in given direction.

   179         * Needed if application wants to control the scrolling and

   180         * NextItemOrScrollL() is thus not suitable.

   181         *

   182         * @param    aDirection   Direction ( ENextDown or ENextUp )

   183         * @return                Start position of next tag, KErrNotFound if

   184         *                        no tag found from given direction

   185         */

   186         IMPORT_C TInt PositionOfNextItem( TFindDirection aDirection );

   187 

   188         /**

   189         * @since Series 60 2.6

   190         * Deletes current item descriptor and sets type to ENoneSelected

   191         */

   192         IMPORT_C void ResetCurrentItem();

   193 

   194         /**

   195         * @since Series 60 2.6

   196         *

   197         * Creates item descriptor starting from aStart and sets the item type

   198         * to CurrentItem().iItemType, if default value is not overridden

   199         * uses internal members to resolve type.

   200         * Method does NOT any formatting to editor.

   201         *

   202         * @param    aStart   Position from which tag to be recognized should start

   203         *                    Default value uses internal members

   204         */

   205         IMPORT_C void ResolveAndSetItemTypeL( TInt aStart = KErrNotFound );

   206 

   207         /**

   208         * @since Series 60 2.6

   209         *

   210         * Sets external observer (Must implement MItemFinderObserver) to which notify when parsing is completed.

   211         * There is no need to set an observer if ItemFinder implements scrolling in editor.

   212         * Must be called before SetEditor in order to have effect.

   213         *

   214         * @param    aObserver   Observer which will be notified about the praser state changes

   215         */

   216         IMPORT_C void AddObserver( MItemFinderObserver& aObserver );

   217 

   218         /**

   219         * @since Series 60 3.2

   220         *

   221         * Tells whether the point tapped inside the editor text body was hit some find item.

   222         * Also updates the current item selection and cursor position when necessary.

   223         *

   224         * @param    aTappedPoint Tapped point relative to the upper left point of the editor text body control.

   225         * @return   ETrue if some find item inside editor text body was tapped. Otherwise EFalse.

   226         */

   227         IMPORT_C TBool ItemWasTappedL( const TPoint aTappedPoint );

   228 

   229         /**

   230         * @since Series 60 3.2

   231         * Sets the given external links (hyperlinks) and refreshes the text buffer.

   232         * Validites the links by their type.

   233         *

   234         * @param    aLinks a pointer list of external link objects ordered by start position (lowest first).

   235         * @return   KErrNone if successfull operation, otherwise system-wide error code.

   236         */

   237         IMPORT_C TInt SetExternalLinks( CArrayPtrFlat<CFindItemExt>* aLinks );

   238 

   239         /**

   240         * @since Series 60 3.2

   241         * Returns reference to currently selected item, if none selected iItemType = ENoneSelected

   242         * Please note that method does not check whether the editor has focus or not, it will return

   243         * last selected item even the highlight is not visible as editor is not focused

   244         * Unlike CurrentItem() that contains the length, this method also contains position of the item.

   245         *

   246         * @return   currently selected item

   247         */

   248         IMPORT_C CFindItemExt& CurrentItemExt();

   249 

   250         /**

   251         * @since Series 60 3.2

   252         * Returns the current selection of the text buffer on the screen.

   253         *

   254         * @return   current selection of the text buffer on the screen.

   255         */

   256         IMPORT_C TPtrC CurrentSelection();

   257 

   258     private:

   259 

   260         /**

   261         * C++ default constructor.

   262         */

   263         CItemFinder( TInt aFindFlags );

   264 

   265         // utilities

   266         TInt EngineFlags();

   267         void InsertPrefixToUrl();

   268         TBool SchemeSupported( const TDesC& aScheme );

   269 

   270         TBool CallbackToExtObserver();

   271 

   272         /**

   273         * 2nd phase constructor.

   274         */

   275         void ConstructL();

   276 

   277         void DoResolveAndSetItemTypeL( const CFindItemExt* aItem );

   278 

   279         TInt MinLengthForItemType( TInt aItemType );

   280 

   281         TInt GetMinDigitsToFindL();

   282 

   283         TInt RefreshEditor();

   284 

   285     private:    // Data

   286 

   287         CEikRichTextEditor** iEditor; // Not owned

   288         TInt iFlags;

   289 

   290         CFindItemExt* iCurrentItemExt;

   291         CArrayPtrFlat<CFindItemExt>* iExternalLinks;

   292 

   293         TInt iCurrentStart;

   294         TInt iCurrentEnd;

   295 

   296         TFindDirection iPreviousDirection;

   297         TInt iFirstVisible;

   298 

   299         CItemFinderAsyncParser* iAsyncParser;

   300 

   301         CSchemeResolver* iSchemeResolver;

   302 

   303         TBool iMarkedArrayComplete;

   304 

   305         MItemFinderObserver* iExternalObserver; // not owned

   306 

   307         friend class CItemFinderAsyncParser;

   308 

   309         TInt iMinDigitsToFind;

   310     };

   311 

   312 #endif      // ITEMFINDER_H

   313 

   314 // End of File