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:  Decleares class for tree structure searching.

    15 *

    16 */

    17 

    18 

    19 #ifndef IPSSETUIITEMFINDER_H

    20 #define IPSSETUIITEMFINDER_H

    21 

    22 #include <e32base.h>

    23 

    24 #include "ipssetuiitembase.h"

    25 #include "ipssetuifinderinterface.h"

    26 

    27 class CIpsSetUiItem;

    28 

    29 

    30 /**

    31  *  Class to find item(s) from the setting tree

    32  *

    33  *  @lib IpsSosSettings.lib

    34  *  @since FS v1.0

    35  */

    36 class CIpsSetUiFinder : public CBase

    37     {

    38 public:

    39 

    40 // Constructors and destructor

    41 

    42     /**

    43      * Destructor

    44      */

    45     ~CIpsSetUiFinder();

    46 

    47     /**

    48      * @param aObserver Observer for search operation.

    49      * @return New finder object.

    50      */

    51     static CIpsSetUiFinder* NewL(

    52         MIpsSetUiFinder& aObserver );

    53 

    54     /**

    55      * @param aObserver Observer for search operation.

    56      * @return New finder object.

    57      */

    58     static CIpsSetUiFinder* NewLC(

    59         MIpsSetUiFinder& aObserver );

    60 

    61 // New functions

    62 

    63     /**

    64      * Set method to member iSearchFlags

    65      * @param aSearchFlags, Sets value of iSearchFlags

    66      */

    67     void SetSearchFlags( const TUint64& aSearchFlags );

    68 

    69     /**

    70      * Get function for member iSearchFlags

    71      * @return value of iSearchFlags

    72      */

    73     TUint64 SearchFlags() const;

    74 

    75     /**

    76      *

    77      * @param aItemArray Array to be searched.

    78      */

    79     void StartSearchL(

    80         CIpsSetUiBaseItemArray& aItemArray,

    81         const TUid& aId );

    82 

    83     /**

    84      *

    85      * @param aItemArray Array to be searched.

    86      *

    87      */

    88     void StartSearchL(

    89         CIpsSetUiBaseItemArray& aItemArray,

    90         const TInt aItem );

    91 

    92     /**

    93      * Get function for member iFinderArray

    94      * @return value of iFinderArray

    95      */

    96     CIpsSetUiFinderArray* FinderArray() const;

    97 

    98     /**

    99      * Gets the copy of finder array and saves it to stack

   100      * @return value of iFinderArray

   101      */

   102     CIpsSetUiFinderArray* FinderArrayLC() const;

   103 

   104 private:

   105 

   106 // Constructors

   107 

   108     /**

   109      * Constructor

   110      *

   111      * @param aObserver Observer for search operation.

   112      */

   113     CIpsSetUiFinder(

   114         MIpsSetUiFinder& aObserver );

   115 

   116     /**

   117      * 2nd phase constructor

   118      */

   119     void ConstructL();

   120 

   121 // New functions

   122 

   123     /**

   124      * Prepare for search.

   125      *

   126      * @param aNth Start from nth item in the array.

   127      */

   128     void InitializeSearchL( const TInt aNth );

   129 

   130     /**

   131      * Clear all internal data.

   132      */

   133     void FinalizeSearchL();

   134 

   135     /**

   136      * Check, if the search criterias have been met.

   137      *

   138      * @param aCurrentItem Index of the current item

   139      * @param aMaxItems Maximum number of items in the array.

   140      * @return ETrue, when the search should be continued.

   141      */

   142     TBool ContinueSearch(

   143         const TInt aCurrentItem,

   144         const TInt aMaxItems );

   145 

   146     /**

   147      * @return ETrue, when the item fills the search criterias.

   148      */

   149     TBool SearchingItem();

   150 

   151     /**

   152      * Adds new branch to search array.

   153      */

   154     void ItemToArrayL();

   155 

   156     /**

   157      * Item check for ID search algorithm.

   158      *

   159      * @param aId Id to be searched

   160      */

   161     void ItemCheckL( const TUid& aId );

   162 

   163     /**

   164      * Item check for index search algorithm.

   165      */

   166     void ItemCheckL();

   167 

   168     /**

   169      * @return ETrue, when item doesn't have container for other items.

   170      */

   171     TBool ItemSubArrayCheck();

   172 

   173     /**

   174      * @return ETrue, when search criterias are not met.

   175      */

   176     TBool ContinueSubSearch();

   177 

   178     /**

   179      * Intelligence to search the ID from the subarrays.

   180      *

   181      * @param aId Id to be searched

   182      */

   183     void DoIdSearchSubArraysL( const TUid& aId );

   184 

   185     /**

   186      * Intelligence to search index from the sub arrays.

   187      */

   188     void DoIndexSearchSubArraysL();

   189 

   190     /**

   191      * Stops the search opertion.

   192      */

   193     void DoEndSearch();

   194 

   195     /**

   196      * Main intelligence to search ID from the tree.

   197      *

   198      * @param aItemArray Array to be searched.

   199      * @param aId Id to be searched

   200      */

   201     void DoIdSearchL(

   202         CIpsSetUiBaseItemArray& aItemArray,

   203         const TUid& aId );

   204 

   205     /**

   206      * Main intelligence for index search.

   207      * @param aItemArray Array to be searched.

   208      */

   209     void DoIndexSearchL( CIpsSetUiBaseItemArray& aItemArray );

   210 

   211     /**

   212      * Searches for the item from the array based on the id.

   213      *

   214      * @param aItemArray Array, which may contain the item.

   215      * @param aId Id to be searched

   216      */

   217     void SearchIdFromTreeL(

   218         CIpsSetUiBaseItemArray& aItemArray,

   219         const TUid& aId );

   220 

   221     /**

   222      * Searches for the item's index from the given array.

   223      *

   224      * @param aItemArray Array to be searched.

   225      */

   226     void SearchIndexFromTreeL(

   227         CIpsSetUiBaseItemArray& aItemArray );

   228 

   229     /**

   230      * @return ETrue, when item is hidden. Otherwise EFalse.

   231      */

   232     TBool IsHidden();

   233 

   234     /**

   235      * Check wheter searching has met the conditions to finish itself.

   236      */

   237     void SearchShouldStop();

   238 

   239 public:

   240 

   241 // Data

   242 

   243     /** Flags to control finder's search routine. */

   244     enum TIpsSetUiFinderFlags

   245         {

   246         // Following flags are for set up the search

   247 

   248         // When enabled, user defined check is made

   249         EFinderCustomCheck          = 0x001,

   250         // Includes subfolders in search

   251         EFinderSearchSubFolders     = 0x002,

   252         // Overrides the item spesific tests for one round

   253         EFinderOverrideChecks       = 0x004,

   254         // Hidden items will not be included into the search

   255         EFinderDoHideCheck          = 0x008,

   256         // Searches for resources instead of item

   257         EFinderResourceSearch       = 0x010,

   258         // Goes through whole array regardless of hits

   259         EFinderSearchAll            = 0x020,

   260         // Keeps the last search result in memory

   261         EFinderKeepLastResult       = 0x040,

   262         // Searches items that doesn't match the set

   263         EFinderExlusiveSearch       = 0x080,

   264         // The result tree's ownership is moved to client

   265         EFinderMoveOwnership        = 0x100,

   266 

   267         // Following flags are mainly for internal use

   268         EFinderItemFound            = 0x200,

   269         EFinderItemFindError        = 0x400,

   270         EFinderExit                 = 0x800

   271         };

   272 

   273 private:

   274 

   275 // Data

   276 

   277 

   278     /**

   279      * Observer for search operation.

   280      */

   281     MIpsSetUiFinder&        iObserver;

   282 

   283     /**

   284      * Flags to control the finder

   285      */

   286     TUint64                 iSearchFlags;

   287 

   288     /**

   289      * Container for subarrays.

   290      * Owned.

   291      */

   292     CIpsSetUiBaseItemArray* iSubArrays;

   293 

   294     /**

   295      * Temporary item storage.

   296      * Not owned.

   297      */

   298     CIpsSetUiItem*          iTempItem;

   299 

   300     /**

   301      * Starting point as index for search.

   302      */

   303     TInt                    iSearchItem;

   304 

   305     /**

   306      * Current item index, used for passing forward

   307      */

   308     TInt                    iCurrentItem;

   309 

   310     /**

   311      * Container for search results.

   312      * Owned.

   313      */

   314     CIpsSetUiFinderArray*   iFinderArray;

   315     };

   316 

   317 #endif      // IPSSETUIITEMFINDER_H

   318 

   319 // End of File