1 /*

     2 * Copyright (c) 2009 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:  

    15 *  Version     : 2 << Don't touch! Updated by Synergy at check-out.

    16 *

    17 */

    18 

    19 #ifndef MMCACHEFORITEM_H

    20 #define MMCACHEFORITEM_H

    21 

    22 #include <e32base.h>

    23 #include <e32cmn.h>

    24 #include "mmsubcellssetupcode.h"

    25 

    26 class CGulIcon;

    27 class CHnIconHolder;

    28 class CMmItemsDataCache;

    29 

    30 /**

    31  * Stores cached information needed to draw a single item.

    32  */

    33 NONSHARABLE_CLASS( CMmCacheForItem ): public CBase

    34     {

    35 public:

    36     /**

    37      * Creates a new instance of CMmCacheForItem object.

    38      * The newly created object will be left on the cleanup stack.

    39      * 

    40      * @param aParent The owner of the newly created object.

    41      */

    42     static CMmCacheForItem* NewLC( CMmItemsDataCache& aParent );

    43     

    44     /**

    45      * Creates a new instance of CMmCacheForItem object.

    46      * The newly created object will be left on the cleanup stack.

    47      * 

    48      * @param aParent The owner of the newly created object. 

    49      */

    50     static CMmCacheForItem* NewL( CMmItemsDataCache& aParent );

    51     

    52     /**

    53      * Standard C++ virtual destructor.

    54      */

    55     ~CMmCacheForItem();

    56     

    57     /**

    58      * Sets the subcell setup code that denoted valid subcell setup for this

    59      * item.

    60      * 

    61      * @param aSubcellsSetupCode Subcells setup code for this item. 

    62      */

    63     inline void SetSubcellsSetupCode( TMmSubcellsSetupCode aSubcellsSetupCode );

    64     

    65     /**

    66      * Returns the code of the subcells setup required by this item to be

    67      * properly drawn using cached data.

    68      */

    69     inline TMmSubcellsSetupCode GetSubcellsSetupCode() const;

    70     

    71     /**

    72      * Returns information whether the data in this cache is valid.

    73      * Invalid cache should never be used.

    74      * 

    75      * @return ETrue if valid, EFalse otherwise.

    76      */

    77     inline TBool IsValid() const;

    78     

    79     /**

    80      * Marks this cache as valid or invalid.

    81      * 

    82      * @param aValid (Self-explanatory).

    83      */

    84     inline void SetValid( TBool aValid );

    85     

    86     /**

    87      * Returns information whether at the moment of updating this cache object

    88      * the item was current (highlighted).

    89      * 

    90      * @return ETrue if current, EFalse otherwise.

    91      */

    92     inline TBool IsCurrent();

    93     

    94     /**

    95      * Sets the information whether the item was current (highlighted). 

    96      */

    97     inline void SetCurrent( TBool aCurrent );

    98     

    99     /**

   100      * Retrieves the cached item text.

   101      * This is the complete string needed by AVKON methods to draw the item

   102      * including tab characters and icon indices.

   103      * 

   104      * @return Cached item text.

   105      */

   106     inline const TDesC& GetItemText() const;

   107     

   108     /**

   109      * Returns reference to the text buffer owned by this cache.

   110      * This methods allows for updating the cached text.

   111      * 

   112      * @return Reference to the text buffer owned by this cache.

   113      */

   114     inline RBuf& GetItemTextForModifications();

   115     

   116     /**

   117      * Retrives cached template name.

   118      * 

   119      * @return Cached template name. 

   120      */

   121     const TDesC8& GetTemplate() const;

   122     

   123     /**

   124      * Sets template name for the item.

   125      * 

   126      * @param aItemTemplate Template name.

   127      */

   128     void SetTemplateL( const TDesC8& aItemTemplate );

   129     

   130     /**

   131      * Returns cached item size.

   132      *

   133      * @return Cached item size. 

   134      */

   135     inline TSize GetSize() const;

   136     

   137     /**

   138      * Updates item size stored in the cache.

   139      * 

   140      * @param aItemSize Item size.

   141      */

   142     inline void SetSize( TSize aItemSize );

   143 

   144     /**

   145      * Produces icon list, which can be then passed as parameter to

   146      * CEikFormattedCellListBoxData::SetIconArray.

   147      * It is up to the caller to delete the returned array. However,

   148      * the icons stored in the array must not be deleted.

   149      */

   150     CArrayPtr<CGulIcon>* GetIconListL();

   151 

   152     /**

   153      * Appends an icon (specifically an icon holder) to the cached array of icon holders.

   154      * The icon holder is then co-owned by this CMmCacheForItem object so that the

   155      * icon contained in the icon holder can be safely stored.

   156      * 

   157      * @param aIconHolder An icon holder (NULL value not allowed).

   158      * @return Index of the just appended icon holder.

   159      */

   160     TInt AppendIconL( CHnIconHolder* aIconHolder );

   161 

   162     /**

   163      * Clears the array of icon holders stored in this item cache.

   164      * It ceases co-owning the icon holders and resets the array

   165      * that stores them.

   166      */

   167     void ClearIconArray();

   168     

   169     /**

   170      * Based on the information about how the item must be drawn (with

   171      * hightlight or not) and what currect subcells setup it, this methods

   172      * invalidates the cache for this item to prevent problems such as:

   173      * * cache information for highlighted item being used for to draw

   174      *   the item without highlight or vice versa.

   175      * * relying on cache and not performing the full subcells setup while

   176      *   the current subcells setup does not fit this particular item.

   177      */

   178     void InvalidateIfCacheMayNotBeUsed( TBool aIsItemCurrent,

   179             TMmSubcellsSetupCode aSubcellsSetupCode );

   180     

   181 protected:

   182     /**

   183      * Stardard C++ constructor.

   184      * 

   185      * @param aParent CMmItemsDataCache object owning this object.

   186      */

   187     CMmCacheForItem( CMmItemsDataCache& aParent );

   188     

   189     /**

   190      * 2nd phase constructor.

   191      */

   192     void ConstructL();

   193 

   194 protected:

   195     /**

   196      * Stores information whether this cache object is valid.

   197      */

   198     TBool iIsValid;

   199     

   200     /**

   201      * Stores information the item was highlighted at the moment

   202      * of last cache update.

   203      */

   204     TBool iIsCurrent;

   205     

   206     /**

   207      * Stores subcells setup code that denotes the subcells setup

   208      * needed to draw the item using the cached data.

   209      */

   210     TMmSubcellsSetupCode iSubcellsSetupCode;

   211     

   212     /**

   213      * Own.

   214      * Stores the item text in the format that

   215      * CFormattedCellListBoxData::Draw accepts.

   216      * This text includes icon indices separated with tab characters.

   217      */

   218     RBuf iItemText;

   219     

   220     /**

   221      * Stores the item size.

   222      */

   223     TSize iItemSize;

   224     

   225     /**

   226      * Template identifier obtained from @c aParent using

   227      * @c CMmItemsDataCache::GetTemplateIdentifierL.

   228      */

   229     TInt iTemplateIdentifier;

   230     

   231     /**

   232      * Own. 

   233      * The icon holders in the array are co-owned.

   234      */

   235     RArray<CHnIconHolder*> iIconHolderList;

   236     

   237     /**

   238      * Object that represents the whole data cache as opposed

   239      * to single item cache represented by this object.

   240      */

   241     CMmItemsDataCache& iParent;

   242 

   243     };

   244 

   245 #include "mmcacheforitem.inl"

   246 

   247 #endif // MMCACHEFORITEM_H