1 /*

     2 * Copyright (c) 2008-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:    Iterators for traversing lists

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef __C_GLXMEDIALISTITERATOR_H__

    22 #define __C_GLXMEDIALISTITERATOR_H__

    23 

    24 #include <e32std.h>

    25 #include <glxmediaid.h>

    26 

    27 class MGlxMediaList;

    28 class T_CGlxSelectionIterator; // For E-Unit

    29 class T_CGlxFromFocusOutwardIterator; // For E-Unit

    30 

    31 /**

    32  *  MGlxMediaListIterator

    33  *  

    34  *  Interface for going through items in the list in a 

    35  *  non-sequential order. 

    36  *

    37  *  This class is primarily intended for Fetch contexts for going 

    38  *  through the list's items in priority order. The intention is to abstract 

    39  *  the selection and  priorities of items from the attributes being requested.

    40  *  This allows reusing same fetch contexts with multiple item orders.

    41  *  Can hence have one attribute fethc context that requests first 

    42  *  and last item and another attribute that requests some items 

    43  *  starting from focus outwards, without duplicating the attribute fetch 

    44  *  context code. The order classes can then also be reused in different

    45  *  fetch contexts, e.g., in thumbnail fetch context.

    46  * 

    47  *  @lib glxmedialists.lib

    48  */	

    49 class MGlxMediaListIterator 

    50 	{

    51 public:

    52 	/**

    53 	 * Resets to the first item to be returned 

    54 	 * What the first item index actually is is entirely

    55 	 * up to the implementation. It could be the focus index,

    56 	 * or it could be the first, or even last item in the list

    57 	 *

    58 	 * @return the index of the first item or KErrNotFound if 

    59 	 *          first item does not exist

    60 	 */

    61 	virtual void SetToFirst(const MGlxMediaList* aList) = 0;

    62 

    63 	/**

    64 	 * Returns the index of the current item and moves to the next item

    65 	 * @return the item index or KErrNotFound if the item does not exist

    66 	 */

    67 	virtual TInt operator++(TInt) = 0;

    68 	

    69 	/**

    70 	 * @return ETrue if index is within range, EFalse otherwise

    71 	 */

    72 	virtual TBool InRange(TInt aIndex) const = 0;

    73 	};

    74 

    75 /**

    76  *  TGlxSpecificIdIterator

    77  * 

    78  *  Used to retrieve attributes relating to one specific media

    79  *  id in a media list.

    80  * 

    81  *  @lib glxmedialists.lib

    82  */ 

    83 class TGlxSpecificIdIterator : public MGlxMediaListIterator

    84 	{

    85 public:

    86     IMPORT_C TGlxSpecificIdIterator(const TGlxIdSpaceId& aIdSpaceId, TGlxMediaId aRequiredId);

    87 	

    88 public: // From MGlxMediaListIterator

    89 	void SetToFirst(const MGlxMediaList* aList);

    90 	TInt operator++(TInt);

    91 	TBool InRange(TInt aIndex) const;

    92 	

    93 private:

    94     /**

    95      *  Required id

    96      */

    97 	TGlxMediaId iMediaId;

    98 	

    99     /**

   100 	 * List being traversed

   101 	 */

   102 	const MGlxMediaList* iList; 

   103 	

   104 	const TGlxIdSpaceId iIdSpaceId;  

   105     

   106     TBool iFinished;

   107 	};

   108 

   109 /**

   110  *  TGlxSequentialIterator

   111  * 

   112  *  Iterates though all the items in the list sequentially.

   113  * 

   114  *  @lib glxmedialists.lib

   115  */ 

   116 class TGlxSequentialIterator : public MGlxMediaListIterator

   117     {

   118 public:   

   119     IMPORT_C TGlxSequentialIterator();

   120 

   121 public: // From MGlxMediaListIterator

   122     void SetToFirst(const MGlxMediaList* aList);

   123     TInt operator++(TInt);

   124     TBool InRange(TInt aIndex) const;

   125     

   126 public:

   127 	/**

   128 	 * Set the maximum number of items to iterate through

   129 	 * @param aRange Maximum number of items to iterate through. Set as KMaxTInt to remove limit

   130 	 */

   131     IMPORT_C void SetRange( TInt aRange );    

   132 

   133 private:

   134     TInt iCurrentItem;

   135     

   136     /**

   137      * The maximum number of items to retrieve 

   138      */

   139     TInt iRange;

   140     

   141     /**

   142      * List being traversed

   143      */

   144     const MGlxMediaList* iList;

   145     };

   146 

   147 /**

   148  * TGlxFirstThenLastIterator

   149  * 

   150  * Ordered that returns the index of first and then the 

   151  * last item in the list

   152  * 

   153  *  @lib glxmedialists.lib

   154  */	

   155 class TGlxFirstThenLastIterator : public MGlxMediaListIterator

   156 	{

   157 public:

   158 	IMPORT_C TGlxFirstThenLastIterator();

   159 	IMPORT_C ~TGlxFirstThenLastIterator();

   160 

   161 // From MGlxMediaListIterator

   162 	virtual void SetToFirst(const MGlxMediaList* aList);

   163 	virtual TInt operator++(TInt);

   164 	virtual TBool InRange(TInt aIndex) const;

   165 

   166 private:

   167 	/**	

   168 	 * The count or ordinal of the item that is currently "selected"

   169 	 * This translates to how many times ++ has been called

   170 	 */

   171 	TInt iCurrentItem;

   172 

   173 	/**

   174 	 * List being traversed

   175 	 */

   176 	const MGlxMediaList* iList;

   177 	};

   178 

   179 /**

   180  * TGlxFromFocusOutwardIterator

   181  * 

   182  * Ordered that returns the index of the focused item first and 

   183  * then the surrounding items evenly from both sides

   184  * 

   185  *  @lib glxmedialists.lib

   186  */	

   187 class TGlxFromFocusOutwardIterator : public MGlxMediaListIterator

   188 	{

   189 public:

   190 	IMPORT_C TGlxFromFocusOutwardIterator();

   191 	IMPORT_C ~TGlxFromFocusOutwardIterator();

   192 	

   193 	/**

   194 	 * Set the range offsets

   195 	 */

   196     IMPORT_C void SetRangeOffsets(TInt aRearOffset, TInt aFrontOffset);

   197     

   198 // From MGlxMediaListIterator

   199 	virtual void SetToFirst(const MGlxMediaList* aList);

   200 	virtual TInt operator++(TInt);

   201 	virtual TBool InRange(TInt aIndex) const;

   202 

   203 private:

   204 	/**	

   205 	 * The count or ordinal of the item that is currently "selected"

   206 	 * This translates to how many times ++ has been called

   207 	 */

   208 	TInt iCurrentItem;

   209 

   210 	/**

   211 	 * Number of items within range after focus index

   212 	 */

   213 	TInt iFrontOffset;

   214 

   215 	/**

   216 	 * Number of items within range before focus index

   217 	 */

   218 	TInt iRearOffset;

   219 	

   220 	/**

   221 	 * List being traversed

   222 	 */

   223 	const MGlxMediaList* iList;

   224 	

   225 	// For E-Unit

   226 	friend class T_CGlxFromFocusOutwardIterator;

   227 	

   228     /**

   229      * Number of items within range as configured by clients

   230      * This shall be used to restore back 

   231      * while coming out of low memory conditions

   232      */

   233     TInt iOriginalFrontOffset;

   234     TInt iOriginalRearOffset;

   235 	};

   236 

   237 /**

   238  * TGlxFromIndexOutwardBlockyIterator

   239  * 

   240  * Ordered that returns the index of the focused item first and 

   241  * then the surrounding items evenly from both sides

   242  */	

   243 class TGlxFromIndexOutwardBlockyIterator : public MGlxMediaListIterator

   244 	{

   245 	

   246 public:

   247     class MGlxIndex 

   248     	{

   249     public:

   250     	virtual TInt Index() const = 0;

   251     	};

   252     	

   253 public:

   254 	 IMPORT_C ~TGlxFromIndexOutwardBlockyIterator( );

   255 	 IMPORT_C TGlxFromIndexOutwardBlockyIterator(const MGlxIndex& aIndexFunctor);

   256 	

   257 	/**

   258 	 * Set the range offsets

   259 	 */

   260      IMPORT_C void SetRangeOffsets(TInt aRearOffset, TInt aFrontOffset);

   261     

   262 // From MGlxMediaListIterator

   263 	virtual void SetToFirst(const MGlxMediaList* aList);

   264 	virtual TInt operator++(TInt);

   265 	virtual TBool InRange(TInt aIndex) const;

   266     

   267 //protected: 

   268     /**

   269      * Functor to return index in media list based on unknown rule

   270      * Rule is defined by a deriving class

   271      */		

   272  /*   class MGlxIndex 

   273         {

   274     public:

   275         virtual TInt Index() const = 0;

   276         };*/

   277         

   278 private:

   279 	/**	

   280 	 * The count or ordinal of the item that is currently "selected"

   281 	 * This translates to how many times ++ has been called

   282 	 */

   283 	TInt iCurrentItem;

   284 

   285 	/**

   286 	 * Number of items within range after focus index

   287 	 */

   288 	TInt iFrontOffset;

   289 

   290 	/**

   291 	 * Number of items within range before focus index

   292 	 */

   293 	TInt iRearOffset;

   294     

   295     /**

   296      * Functor from which to get the index around which iteration centers (e.g., focus)

   297      */

   298     const MGlxIndex& iIndexFunctor;

   299 

   300 protected:	

   301 	/**

   302 	 * List being traversed

   303 	 */

   304 	const MGlxMediaList* iList;

   305 	};

   306     

   307 /**

   308  * TGlxFromFocusOutwardBlockyIterator

   309  * 

   310  * Ordered that returns the index of the focused item first and 

   311  * then the surrounding items evenly from both sides

   312  */		

   313 class TGlxFromFocusOutwardBlockyIterator : public TGlxFromIndexOutwardBlockyIterator,  

   314         public TGlxFromIndexOutwardBlockyIterator::MGlxIndex

   315 	{

   316 public:

   317     IMPORT_C TGlxFromFocusOutwardBlockyIterator();

   318 	IMPORT_C ~TGlxFromFocusOutwardBlockyIterator();

   319    

   320 // From MGlxIndex    

   321     TInt Index() const;

   322     };

   323 

   324 /**

   325  * TGlxFromManualIndexOutwardBlockyIterator

   326  */		

   327 class TGlxFromManualIndexOutwardBlockyIterator : public TGlxFromIndexOutwardBlockyIterator, 

   328         public TGlxFromIndexOutwardBlockyIterator::MGlxIndex

   329 	{

   330 public:

   331     IMPORT_C TGlxFromManualIndexOutwardBlockyIterator();

   332 	IMPORT_C ~TGlxFromManualIndexOutwardBlockyIterator();

   333    

   334     IMPORT_C void SetIndex( TInt aIndex );

   335     

   336 // From MGlxIndex    

   337     TInt Index() const;

   338     

   339 private:

   340     TInt iIndex;

   341     };

   342     

   343 /**

   344  * TGlxSelectionIterator

   345  * 

   346  * Iterates through the selected items of a media list

   347  * 

   348  *  @lib glxmedialists.lib

   349  */	

   350 class TGlxSelectionIterator : public MGlxMediaListIterator

   351 	{

   352 public:

   353 	IMPORT_C TGlxSelectionIterator();

   354 	IMPORT_C ~TGlxSelectionIterator();

   355 

   356 public:

   357     /**

   358     * Set the maximum number of selected items to iterate through

   359     @param aMaxItems Maximum number of selected items to iterate through. Set as KMaxTInt to remove limit

   360     */

   361     IMPORT_C void SetRange(TInt aMaxItems);

   362    

   363    /**

   364     * Disables the iterator if the number of selected items is greater than

   365     * the range. (specified using SetRange() above).

   366     * @param aDisabledIfMoreThanRangeSelected If ETrue, the iterator is 

   367     * disabled if the number of selected items is greater than the range. 

   368     * If EFalse, the iterator is enabled if the number of selected items 

   369     * is greater than the range.

   370     */

   371     IMPORT_C void SetDisabledIfMoreThanRangeSelected(TBool aDisabledIfMoreThanRangeSelected);

   372     

   373     // From MGlxMediaListIterator

   374     IMPORT_C virtual void SetToFirst(const MGlxMediaList* aList);

   375     IMPORT_C virtual TInt operator++(TInt);

   376     IMPORT_C virtual TBool InRange(TInt aIndex) const;

   377 

   378 private:

   379     /**	

   380     * The count or ordinal of the item that is currently "selected"

   381     * This translates to how many times ++ has been called

   382     */

   383     TInt iCurrentItem;

   384 

   385     /**

   386     * List being traversed

   387     */

   388     const MGlxMediaList* iList;

   389 

   390     /**

   391     * If ETrue, the iterator is  disabled if the number of selected 

   392     * items is greater than the range. If EFalse, the iterator is enabled 

   393     * if the number of selected items is greater than the range.

   394     */

   395     TInt iDisabledIfMoreThanRangeSelected;

   396     

   397     /**

   398     * The maximum number of selected items to iterate through.

   399     */

   400     TInt iRange;

   401 

   402     // For E-Unit

   403     friend class T_CGlxSelectionIterator;

   404     };

   405 

   406 /**

   407  *  ExclusionIterator

   408  * 

   409  *  Iterates through the non visible items  

   410  *  

   411  * 

   412  *  @lib glxmedialists.lib

   413  */ 

   414 class TGlxExclusionIterator : public MGlxMediaListIterator

   415 	{

   416 	

   417 public:

   418     IMPORT_C TGlxExclusionIterator( MGlxMediaListIterator   &aIncludedItemsIterator, MGlxMediaListIterator &aExcludedItemsIterator );

   419     IMPORT_C ~TGlxExclusionIterator();

   420     

   421     // From MGlxMediaListIterator    

   422     IMPORT_C void SetToFirst(const MGlxMediaList* aList);

   423     

   424     TInt operator++(TInt);

   425     

   426     TBool InRange(TInt aIndex) const;

   427 	

   428 private:   

   429  

   430     /**

   431     * The iterator whixh specifies ,which items to be included.

   432     */ 

   433     MGlxMediaListIterator& iIncludedItemsIterator;

   434     

   435     /**

   436     * The iterator which specifies ,which items should be excluded.,

   437     */

   438     MGlxMediaListIterator& iExcludedItemsIterator; 

   439     

   440 	};

   441 

   442 /**

   443  * TGlxFromManualIndexBlockyIterator

   444  * 

   445  * Ordered that returns the index of the visible window item first and 

   446  * then the surrounding items evenly from both sides

   447  */	

   448 class TGlxFromManualIndexBlockyIterator : public MGlxMediaListIterator

   449 	{

   450 	

   451 public:

   452 	 IMPORT_C ~TGlxFromManualIndexBlockyIterator( );

   453 	 IMPORT_C TGlxFromManualIndexBlockyIterator( );

   454 	

   455 	/**

   456 	 * Set the range offsets

   457 	 */

   458      IMPORT_C void SetRangeOffsets(TInt aRearOffset, TInt aFrontOffset);

   459     

   460     // From MGlxMediaListIterator

   461 	virtual void SetToFirst(const MGlxMediaList* aList);

   462 	virtual TInt operator++(TInt);

   463 	virtual TBool InRange(TInt aIndex) const;

   464 

   465 private:

   466 	/**	

   467 	 * The count or ordinal of the item that is currently "selected"

   468 	 * This translates to how many times ++ has been called

   469 	 */

   470 	TInt iCurrentItem;

   471 

   472 	/**

   473 	 * Number of items within range after visible index

   474 	 */

   475 	TInt iFrontOffset;

   476 

   477 	/**

   478 	 * Number of items within range before visible index

   479 	 */

   480 	TInt iRearOffset;

   481     

   482     /**

   483      * Number of items within range as configured by clients

   484      * This shall be used to restore back 

   485      * while coming out of low memory conditions

   486      */

   487 	TInt iOriginalFrontOffset;

   488 	TInt iOriginalRearOffset;

   489 	TInt iDefaultVisItems;

   490 protected:	

   491 	/**

   492 	 * List being traversed

   493 	 */

   494 	const MGlxMediaList* iList;

   495 	};

   496 	

   497 #endif // __C_GLXMEDIALISTITERATOR_H__

   498