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 settings array class.

    15 *

    16 */

    17 

    18 

    19 #ifndef IPSSETUIARRAY_H

    20 #define IPSSETUIARRAY_H

    21 

    22 

    23 #include <barsread.h>       // TResourceReader

    24 #include <bamdesca.h>                // MDesCArray

    25 #include <eikenv.h>

    26 #include "ipssetuifinderinterface.h"

    27 

    28 

    29 /**

    30  * Stack states.

    31  */

    32 enum TIpsSetUiStackResult

    33     {

    34     EIpsSetUiStackResultOk,

    35     EIpsSetUiStackResultSubMenuOpen,

    36     EIpsSetUiStackResultInvalid

    37     };

    38 

    39 typedef RArray<TInt> RResourceStack;

    40 

    41 class CIpsSetUiItem;

    42 class CIpsSetUiFinder;

    43 class CIpsSetUiItemLink;

    44 class CIpsSetUiItemLinkExt;

    45 

    46 /**

    47  * Defines settings array behavior.

    48  *

    49  * @lib IpsSosSettings.lib

    50  * @since FS v1.0

    51  */

    52 class CIpsSetUiBaseArray :

    53     public CBase,

    54     public MDesCArray,

    55     public MIpsSetUiFinder

    56     {

    57 public: // Constructors and destructor

    58 

    59     /**

    60      * Destructor.

    61      */

    62     virtual ~CIpsSetUiBaseArray();

    63 

    64 public: // New functions

    65 

    66     /**

    67      * Forces the redraw

    68      */

    69     void Refresh();

    70 

    71     /**

    72      * Sets the setting text inside the item.

    73      *

    74      * @param aBaseItem Item for modification.

    75      * @param aText Text to be stored.

    76      * @param Force update of the view.

    77      */

    78     void SetItemText(

    79         CIpsSetUiItem& aBaseItem,

    80         const TDesC& aText,

    81         const TBool aUpdate = EFalse );

    82 

    83     /**

    84      * Retrieves the setting text inside the item.

    85      *

    86      * @param aBaseItem Item which contains the text.

    87      */

    88     const TDesC& ItemText(

    89         CIpsSetUiItem& aBaseItem );

    90 

    91     /**

    92      * Goes forward in resoruce stack.

    93      *

    94      * @param aBase Item which has been opened.

    95      * @return Status of the operation.

    96      */

    97     TIpsSetUiStackResult HandleStackForwardL( const CIpsSetUiItem& aBase );

    98 

    99     /**

   100      * Goes backward in resource stack.

   101      *

   102      * @param aCount Number of submenus to be moved.

   103      * @return Status of the operation.

   104      */

   105     TIpsSetUiStackResult HandleStackBackwardL( TInt aCount = 1 );

   106 

   107     /**

   108      * Event invoked by stack change.

   109      *

   110      * @param aForward Submenu item has opened.

   111      * @param aResourceId Resource ID of the item that caused the action.

   112      * @return Status of the operation.

   113      */

   114     TIpsSetUiStackResult HandleStackChangeL(

   115         const TInt aForward,

   116         const TInt aResourceId = KErrNotFound );

   117 

   118     /**

   119      * Checks if item is hidden

   120      *

   121      * @param aIndex index of the item

   122      * @return KErrNone, if item is visible

   123      * @return KErrNotFound, if item is hidden

   124      * @return KErrNotSupported, if item is permanently hidden

   125      */

   126     TInt IsHidden( const TInt aIndex ) const;

   127 

   128     /**

   129      * Checks if item is hidden

   130      *

   131      * @param aId id of the item

   132      * @return KErrNone, if item is visible

   133      * @return KErrNotFound, if item is hidden

   134      * @return KErrNotSupported, if item is permanently hidden

   135      */

   136     TInt IsHidden( const TUid& iId ) const;

   137 

   138     /**

   139      * Checks if item is hidden

   140      *

   141      * @param aItem the item

   142      * @return KErrNone, if item is visible

   143      * @return KErrNotFound, if item is hidden

   144      * @return KErrNotSupported, if item is permanently hidden

   145      */

   146     virtual TInt IsHidden( const CIpsSetUiItem& aItem ) const;

   147 

   148     /**

   149      * Hides the provided item.

   150      *

   151      * @param aHide Hide/Unhide.

   152      * @param aId Id of the item to be modified.

   153      * @param aUpdate Refresh the UI.

   154      */

   155     void SetHideItem(

   156         const TBool aHide,

   157         const TUid& aId,

   158         const TBool aUpdate = EFalse );

   159 

   160     /**

   161      * Hides the provided item.

   162      *

   163      * @param aHide Hide/Unhide.

   164      * @param aItem Item to be modified.

   165      * @param aUpdate Refresh the UI.

   166      */

   167     void SetHideItem(

   168         const TBool aHide,

   169         CIpsSetUiItem& aItem,

   170         const TBool aUpdate = EFalse );

   171 

   172     /**

   173      * Find the item from the tree structure.

   174      *

   175      * @param aId Unique ID of the item.

   176      * @param aExcludeHidden Skip all hidden item.

   177      */

   178     CIpsSetUiItem* GetItem(

   179         const TUid& aId,

   180         const TBool aExcludeHidden = ETrue ) const;

   181 

   182     /**

   183      * Find the item from the tree structure.

   184      *

   185      * @param Index of the item in resource.

   186      * @param aExcludeHidden Skip all hidden item.

   187      */

   188     CIpsSetUiItem* GetItem(

   189         const TInt aIndex,

   190         const TBool aExcludeHidden = ETrue ) const;

   191 

   192 protected:  // Constructors

   193 

   194     /**

   195      *  Constructor.

   196      */

   197     CIpsSetUiBaseArray();

   198 

   199     /**

   200      * 2nd phase of construction.

   201      */

   202     void BaseConstructL();

   203 

   204     /**

   205      * 2nd phase of construction.

   206      *

   207      * @param aResourceId Tree root resource.

   208      */

   209     void BaseConstructL( const TInt aResourceId );

   210 

   211 protected:  // Data

   212 

   213     /**

   214      * Events invoked by array changes.

   215      */

   216     enum TIpsSetUiArrayEvent

   217         {

   218         EIpsSetUiArrayAdded = 0,

   219         EIpsSetUiArrayRemoved,

   220         EIpsSetUiArrayChanged,

   221         EIpsSetUiArrayStackForward,

   222         EIpsSetUiArrayStackBackward

   223         };

   224 

   225 // New virtual functions

   226 

   227     /**

   228      * Initializes the data in the item.

   229      *

   230      * @param aBaseItem Item to be initialized.

   231      */

   232     virtual void InitUserData( CIpsSetUiItem& aBaseItem ) = 0;

   233 

   234     /**

   235      * Handler for array change events.

   236      *

   237      * @param aEvent The invoked event.

   238      * @return KErrNone, when ok.

   239      */

   240     virtual TInt EventArrayChangedL(

   241         const TIpsSetUiArrayEvent aEvent ) = 0;

   242 

   243     /**

   244      * Custom drawing operation for items.

   245      *

   246      * @param aId Unique Id of the item to be drawn.

   247      * @param aString String to be constructed.

   248      * @return ETrue, when handled.

   249      */

   250     virtual TBool EventCustomMdcaPoint(

   251         const TUid& aId,

   252         TPtr& aString ) const = 0;

   253 

   254     /**

   255      * Creates array of items.

   256      *

   257      * @param aId Unique Id of the item to be drawn.

   258      * @return Created item with client ownership.

   259      */

   260     virtual CIpsSetUiItem* CreateCustomItemToArrayLC(

   261         const TUid& aId );

   262 

   263     /**

   264      * Fills the label text to item.

   265      *

   266      * @param aBaseItem Item which contains the label.

   267      * @param aText Return parameter for the label.

   268      */

   269     virtual void ListboxItemFillMultiLineLabel(

   270         const CIpsSetUiItem& aBaseItem,

   271         TIpsSetUtilsTextPlain& aText ) const;

   272 

   273     /**

   274      * Fills the label text to item.

   275      *

   276      * @param aBaseItem Item which contains the label.

   277      * @param aText Return parameter for the label.

   278      */

   279     virtual void ListboxItemFillEditTextLabel(

   280         const CIpsSetUiItem& aBaseItem,

   281         TIpsSetUtilsTextPlain& aText ) const;

   282 

   283     /**

   284      * Fills the label text to item.

   285      *

   286      * @param aBaseItem Item which contains the label.

   287      * @param aText Return parameter for the label.

   288      */

   289     virtual void ListboxItemFillEditValueLabel(

   290         const CIpsSetUiItem& aBaseItem,

   291         TIpsSetUtilsTextPlain& aText ) const;

   292 

   293     /**

   294      * Fills the label text to item.

   295      *

   296      * @param aBaseItem Item which contains the label.

   297      * @param aText Return parameter for the label.

   298      */

   299     virtual void ListboxItemFillEditTimeLabel(

   300         const CIpsSetUiItem& aBaseItem,

   301         TIpsSetUtilsTextPlain& aText ) const;

   302 

   303     /**

   304      * Fills the label text to item.

   305      *

   306      * @param aBaseItem Item which contains the label.

   307      * @param aText Return parameter for the label.

   308      */

   309     virtual void ListboxUndefinedFillLabel(

   310         const CIpsSetUiItem& aBaseItem,

   311         TIpsSetUtilsTextPlain& aText ) const;

   312 

   313     /**

   314      * Fills the label text to item.

   315      *

   316      * @param aBaseItem Item which contains the label.

   317      * @param aText Return parameter for the label.

   318      */

   319     virtual void ListboxRadioButtonFillArrayLabel(

   320         const CIpsSetUiItem& aBaseItem,

   321         TIpsSetUtilsTextPlain& aText ) const;

   322 

   323     /**

   324      * Fills the label text to item.

   325      *

   326      * @param aBaseItem Item which contains the label.

   327      * @param aText Return parameter for the label.

   328      */

   329     virtual void ListboxCheckboxFillArrayLabel(

   330         const CIpsSetUiItem& aBaseItem,

   331         TIpsSetUtilsTextPlain& aText ) const;

   332 

   333 // New functions

   334 

   335     /**

   336      * Locates the item behind the provided item.

   337      *

   338      * @param aBaseItem Item which contains the array of items.

   339      * @param aId Unique Id to be searched.

   340      * @param aExcludeHidden Skip hidden items.

   341      * @return Located item.

   342      */

   343     CIpsSetUiItem* GetSubItem(

   344         const CIpsSetUiItem& aBaseItem,

   345         const TUid& aId,

   346         const TBool aExcludeHidden = ETrue ) const;

   347 

   348     /**

   349      * Locates the item behind the provided item.

   350      *

   351      * @param aBaseItem Item which contains the array of items.

   352      * @param aIndex Index of the item in array.

   353      * @param aExcludeHidden Skip hidden items.

   354      * @return Located item.

   355      */

   356     CIpsSetUiItem* GetSubItem(

   357         const CIpsSetUiItem& aBaseItem,

   358         const TInt aIndex,

   359         const TBool aExcludeHidden = ETrue ) const;

   360 

   361     /**

   362      * Locates item of specific subtype from array.

   363      *

   364      * @param aBaseItem Item which contains the array of items.

   365      * @param aType Type of the item to be searched.

   366      * @return Located item.

   367      */

   368     CIpsSetUiItem* GetSubItemByType(

   369         const CIpsSetUiItem& aBaseItem,

   370         const TInt aType ) const;

   371 

   372     /**

   373      * Gets the index of the item in the array.

   374      *

   375      * @param aLinkItem Item which contains the array.

   376      * @param aId Unique Id to be searched.

   377      * @param aExcludeHidden Skip hidden items.

   378      * @return Index of the item.

   379      */

   380     TInt GetSubItemIndex(

   381         const CIpsSetUiItemLink& aLinkItem,

   382         const TUid& aId,

   383         const TBool aExcludeHidden = ETrue ) const;

   384 

   385     /**

   386      * Gets the index of the item in the array.

   387      *

   388      * @param aLinkItem Item which contains the array.

   389      * @param aIndex Index of the item in array.

   390      * @param aActualIndex

   391      *    ETrue  : aIndex is from visible list and index

   392      *             from the actual resource is required

   393      *    EFalse : aIndex is from resource and visible

   394      *             index is required

   395      */

   396     TInt GetSubItemIndex(

   397         const CIpsSetUiItemLink& aLinkItem,

   398         const TInt aIndex,

   399         const TBool aActualIndex ) const;

   400 

   401     /**

   402      * Gets all item, which belongs to certain resource.

   403      *

   404      * @param aResourceId The certain resource.

   405      * @param aExcludeHidden Skip hidden items.

   406      * @return Array of items in certain resource with ownership.

   407      */

   408     CIpsSetUiFinderArray* GetResourceL(

   409         const TInt aResourceId,

   410         const TBool aExcludeHidden = ETrue ) const;

   411 

   412     /**

   413      * Gets all item, which belongs to certain resource.

   414      *

   415      * @param aResourceId The certain resource.

   416      * @param aExcludeHidden Skip hidden items.

   417      * @return Array of items in certain resource with ownership.

   418      */

   419     CIpsSetUiFinderArray* GetResourceLC(

   420         const TInt aResourceId,

   421         const TInt aExcludeHidden = ETrue ) const;

   422 

   423     /**

   424      * Index of the item in array.

   425      *

   426      * @param aId Unique Id to be searched.

   427      * @param aExcludeHidden Skip hidden items.

   428      * @return Index of the item.

   429      */

   430     TInt ItemIndex(

   431         const TUid& aId,

   432         const TBool aExcludeHidden = ETrue ) const;

   433 

   434     /**

   435      * Check whether the provided value is between the limits.

   436      *

   437      * @param aValue Value to be modified between the limits.

   438      * @param aMin Minimun value.

   439      * @param aMax Maximum value.

   440      */

   441     void SetBetweenValues(

   442         TInt& aValue,

   443         TInt aMin,

   444         TInt aMax ) const;

   445 

   446     /**

   447      * Checks if the item contains array of items.

   448      *

   449      * @param aBaseItem Item to be check.

   450      * @return ETrue, when item has submenu.

   451      */

   452     TBool ItemSubArrayCheck(

   453         const CIpsSetUiItem& aBaseItem ) const;

   454 

   455     /**

   456      * Checks if the item contains array of items.

   457      *

   458      * @param aBaseItem Item to be check.

   459      * @return ETrue, when item has submenu.

   460      */

   461     TBool ItemSubItemCheck(

   462         const CIpsSetUiItem& aBaseItem ) const;

   463 

   464     /**

   465      * @return Currently active resource.

   466      */

   467     TInt StackActiveResource() const;

   468 

   469     /**

   470      * Check if the item is visible or not.

   471      *

   472      * @param aBaseItem Item to be inspected.

   473      * @param aExcludeHidden To make the check useless.

   474      * @return ETrue, when item is visible.

   475      */

   476     TBool IsVisibleCheck(

   477         const CIpsSetUiItem& aBaseItem,

   478         const TBool aExcludeHidden ) const;

   479 

   480 // Functions from base classes

   481 

   482     /**

   483      * @return Number of items in array

   484      */

   485     TInt MdcaCount() const;

   486 

   487 // From MIpsSetUiFinder

   488 

   489     /**

   490      * Handle error in search.

   491      *

   492      * @return ETrue, Search can continue.

   493      */

   494     virtual TBool SearchDoError();

   495 

   496     /**

   497      * Check if the search criterias have been filled.

   498      *

   499      * @param aItem Item to be checked.

   500      * @param aIndex Index of the item.

   501      * @return ETrue, when search should continue.

   502      */

   503     virtual TBool SearchDoContinuationCheck(

   504         const CIpsSetUiItem& aItem,

   505         const TInt aIndex );

   506 

   507     /**

   508      * Checks if the item is the one we are searching for.

   509      *

   510      * @param aItem to be checked.

   511      * @return ETrue, Our precious.

   512      */

   513     virtual TBool SearchDoItemCheck(

   514         CIpsSetUiItem& aItem );

   515     

   516     TInt GetLastResourceId( );

   517 

   518 private:  // New functions

   519 

   520     /**

   521      * Clear array of items.

   522      */

   523     void CleanArrayItems();

   524 

   525     /**

   526      * Load array of items from the specific resource.

   527      *

   528      * @param aResourceId specific resource.

   529      */

   530     void LoadSettingArrayFromResourceL( const TInt aResourceId );

   531 

   532     /**

   533      * Load array of items from the specific resource.

   534      *

   535      * @param aResourceId Specific resource.

   536      * @param aItemArray Array to be filled.

   537      * @return Result of the operation.

   538      */

   539     TInt LoadSettingItemsToArrayL(

   540         const TInt aResourceId,

   541         CIpsSetUiBaseItemArray& aItemArray );

   542 

   543     /**

   544      * Count items in the array.

   545      *

   546      * @param aNewCount Already counted number.

   547      */

   548     void UpdateActiveItemsCount( const TInt aNewCount = KErrNotFound );

   549 

   550     /**

   551      * Fill in the data in the item.

   552      *

   553      * @param aBaseItem Item to be filled.

   554      * @param aMaxLength Maximum length of user data.

   555      * @param aSubType Subtype of the item.

   556      * @param aLinkResourceId Possible id of subarray of items.

   557      */

   558     void HandleDynamicSettingsItemL(

   559         CIpsSetUiItem& aBaseItem,

   560         const TInt aMaxLength,

   561         const TIpsSetUiSettingsType aSubType,

   562         const TInt aLinkResourceId );

   563 

   564     /**

   565      * Loads the item from resource.

   566      *

   567      * @param aReader The resource reader.

   568      * @param aBaseItem Item to be filled.

   569      */

   570     void LoadDynamicSettingItemL(

   571         TResourceReader& aReader,

   572         CIpsSetUiItem& aBaseItem );

   573 

   574     /**

   575      * @param aBaseItem Item which contains data.

   576      * @return Label of the item.

   577      */

   578     TPtrC16 ListboxItemLabelFillL(

   579         CIpsSetUiItem& aBaseItem ) const;

   580 

   581     /**

   582      * Creates item to array.

   583      *

   584      * @param aType Type of the item.

   585      * @param aId Unique id of the item.

   586      * @param aItemArray Array the item will be added.

   587      * @return Created item.

   588      */

   589     CIpsSetUiItem* CreateItemToArrayL(

   590         const TIpsSetUiSettingsType aType,

   591         const TUid& aId,

   592         CIpsSetUiBaseItemArray& aItemArray );

   593 

   594     /**

   595      * Functions to load special item settings

   596      *

   597      * @param aBaseItem, Item to be used as base to settings

   598      * @param aItemArray, Array that item should be stored

   599      */

   600     void LoadDynamicSettingsItemLinkItemL(

   601         CIpsSetUiItem& aBaseItem,

   602         const TIpsSetUiSettingsType aSubType,

   603         const TInt aLinkResourceId );

   604 

   605     /**

   606      * Functions to load special item settings

   607      *

   608      * @param aBaseItem, Item to be used as base to settings

   609      * @param aItemArray, Array that item should be stored

   610      */

   611     void LoadDynamicSettingsItemRadioButtonArrayL(

   612         CIpsSetUiItem& aBaseItem,

   613         CIpsSetUiBaseArray& aItemArray );

   614 

   615     /**

   616      * Functions to load special item settings

   617      *

   618      * @param aBaseItem, Item to be used as base to settings

   619      * @param aItemArray, Array that item should be stored

   620      */

   621     void LoadDynamicSettingsItemCheckBoxArrayL(

   622         CIpsSetUiItem& aBaseItem,

   623         CIpsSetUiBaseArray& aItemArray );

   624 

   625     /**

   626      * Fills in text in the item.

   627      *

   628      * @param aBaseItem Item to be modified.

   629      * @param aMaxLength Maximum length of the text.

   630      */

   631     void UpdateItemEditTextL(

   632         CIpsSetUiItem& aBaseItem,

   633         const TInt aMaxLength );

   634 

   635     /**

   636      * Fills in value in the item.

   637      *

   638      * @param aBaseItem Item to be modified.

   639      * @param aMaxLength Maximum length of the value.

   640      */

   641     void UpdateItemEditValueL(

   642         CIpsSetUiItem& aBaseItem,

   643         const TInt aMaxLength );

   644 

   645     /**

   646      * @param aFlags Flags to be loaded.

   647      */

   648     void LoadDynamicSettingItemFlags(

   649         const TUint32 aFlags );

   650 

   651     /**

   652      * Search for the specific resource.

   653      *

   654      * @param aResourceId Teh specific resource.

   655      * @param aExcludeHidden Skip hidden item.

   656      */

   657     void SearchResourceL(

   658         const TInt aResourceId,

   659         const TBool aExcludeHidden ) const;

   660 

   661     /**

   662      * Hide items.

   663      *

   664      * @param aHide Hide/Unhide.

   665      */

   666     void DoHideItems( const TBool aHide );

   667 

   668     /**

   669      * Prepare search operation.

   670      *

   671      * @param aExcludeHidden Skip hidden item.

   672      */

   673     void InitDefaultSearch(

   674         const TBool aExcludeHidden = ETrue ) const;

   675 

   676     /**

   677      * count item in stack.

   678      *

   679      * @param aExcludeHidden Skip hidden item.

   680      * @return Number of items.

   681      */

   682     TInt StackCountItems(

   683         const TBool aExcludeHidden = ETrue ) const;

   684 

   685         

   686     /**

   687      * Forces the redraw

   688      */

   689     void RefreshL();

   690 

   691 private:  // Functions from base classes

   692 

   693 // from MDesCArray

   694 

   695     /**

   696      * Create listbox item string.

   697      *

   698      * @param aIndex Index of the item in array.

   699      * @return Item string.

   700      */

   701     TPtrC16 MdcaPoint( TInt aIndex ) const;

   702 

   703 protected:  // Data

   704 

   705     /**

   706      * Flags to control the array behaviour

   707      */

   708     enum TIpsSetUiArrayFlags

   709         {

   710         /** Allows updating of the array items. */

   711         EIpsSetUiArrayAllowRefresh = 0x01

   712         };

   713 

   714     /**

   715      * Text array for temporary usage, should be deleted after the use

   716      */

   717     HBufC*                  iTempText;

   718 

   719     /**

   720      * Flags for array handling

   721      */

   722     TIpsSetUtilsFlags       iArrayFlags;

   723 

   724 private:    // Data

   725 

   726     /**

   727      * Item finder object

   728      * Owned.

   729      */

   730     CIpsSetUiFinder* iFinder;

   731 

   732     /**

   733      * Stack to track the active resources

   734      * Owned.

   735      */

   736     RResourceStack*         iResourceStack;

   737 

   738     /**

   739      * Array of items to be shown

   740      */

   741     CIpsSetUiBaseItemArray* iItemArray;

   742 

   743     /**

   744      * String to fill empty compulsary fields

   745      * Owned.

   746      */

   747     HBufC*                  iCompulsoryText;

   748 

   749     /**

   750      * Char to replace character in password fields

   751      */

   752     TUint16                 iPasswordFill;

   753 

   754     /**

   755      * Count of active items in array

   756      */

   757     TInt                    iActiveCount;

   758 

   759     /**

   760      * Error state

   761      */

   762     TInt                    iError;

   763     

   764     /**

   765     * Not owned

   766     */

   767     CEikonEnv*              iEnv;

   768     

   769     };

   770 

   771 #endif      // IPSSETUIARRAY_H

   772 

   773 // End of File