1 /*

     2 * Copyright (c) 2006, 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:  An interface to the hierarchical list tree structure.

    15 *

    16 */

    17 

    18 

    19 #ifndef C_AKNTREE_H

    20 #define C_AKNTREE_H

    21 

    22 

    23 #include <AknIconUtils.h> // TScaleMode

    24 #include <babitflags.h>

    25 

    26 #include "akntreenode.h"

    27 #include "akntreeobserver.h"

    28 

    29 class CAknTreeList;

    30 class CAknTreeListIcon;

    31 class CAknTreeOrdering;

    32 class CAknMarqueeControl;

    33 class CFont;

    34 class MAknCustomTreeOrdering;

    35 class TAknsItemID;

    36 class TAknTreeIterator;

    37 class TAknTextComponentLayout;

    38 class TRgb;

    39 

    40 

    41 /**

    42  *  Hierarchical list tree structure.

    43  *

    44  *  The tree structure is formed from hierarchical list items. These items

    45  *  can be either leaves or nodes. The names do not refer to their dynamic

    46  *  state; a leaf is a tree item that cannot ever have children in the tree

    47  *  structure while node can. @c CAknTree is derived from @c CAknTreeNode

    48  *  class, which is an abstract base class for all tree nodes. An instance of

    49  *  @c CAknTree is always set as a root of the tree structure, so that it can

    50  *  be always reached from all the tree items through parent pointers, or

    51  *  simply by calling the @c CAknTreeItem::Root() method.

    52  *

    53  *  @c CAknTree class provides fast access to all the tree items it contains.

    54  *  The tree structure should always be modified through this class and not

    55  *  by directly modifying the related tree items, as this class is responsible

    56  *  for notifying the tree list view of the occurring tree events.

    57  *

    58  *  Furthermore, this class can create an iterator (an instance of

    59  *  @c CAknTreeIterator) for traversing the tree structure, it stores the

    60  *  ordering of the tree items, and it can also store the icons shared by

    61  *  several tree items.

    62  *

    63  *  @lib aknhlist.lib

    64  *  @since S60 v3.2

    65  */

    66 NONSHARABLE_CLASS( CAknTree ) : public CAknTreeNode

    67     {

    68 

    69 public:

    70 

    71     /** Pre-defined IDs for the icons constructed by the tree. */

    72     enum TTreeListIcon

    73         {

    74         ENone                           = AknTreeListIconID::KNone,

    75         /** Tree structure line with branch. */

    76         ELineBranchIndication           = AknTreeListIconID::KLineBranchIndication,

    77         /** Tree structure end line. */

    78         ELineEndIndication              = AknTreeListIconID::KLineEndIndication,

    79         /** Tree structure straight line indication. */

    80         ELineStraightIndication         = AknTreeListIconID::KLineStraightIndication,

    81         /** Default file indication. */

    82         EDefaultFileIndication          = AknTreeListIconID::KDefaultFileIndication,

    83         /** Closed folder indication. */

    84         EClosedFolderIndication         = AknTreeListIconID::KClosedFolderIndication,

    85         /** Open folder indication. */

    86         EOpenFolderIndication           = AknTreeListIconID::KOpenFolderIndication,

    87         /** Collapse function indication, superimposed. */

    88         ECollapseFunctionIndication     = AknTreeListIconID::KCollapseFunctionIndication,

    89         /** Expand function indication, superimposed. */

    90         EExpandFunctionIndication       = AknTreeListIconID::KExpandFunctionIndication,

    91         /** Item marked indication. */

    92         EMarkedIndication               = AknTreeListIconID::KMarkedIndication,

    93         /** Highlighted item marked indication. */

    94         EHighlightedMarkedIndication    = AknTreeListIconID::KHighlightedMarkedIndication,

    95         /** Denotes the range for pre-defined IDs. */

    96         EPreDefinedIconIdRange

    97         };

    98 

    99     /**

   100      * Two-phased constructor.

   101      *

   102      * @param aList Reference to the tree list object which owns the created

   103      *      tree structure.

   104      *

   105      * @param aOrdering Ordering for the tree list items. The ownership of

   106      *      of the ordering is transferred to the tree.

   107      *

   108      * @return Newly created tree instance.

   109      */

   110     static CAknTree* NewL( CAknTreeList& aList, CAknTreeOrdering* aOrdering );

   111 

   112     /**

   113      * Destructor.

   114      */

   115     virtual ~CAknTree();

   116 

   117     /**

   118      * Returns the ID assigned for the specified tree item. The constant

   119      * @c KAknTreeIIDRoot is returned for the tree root, and constant @c

   120      * KAknTreeIIDNone for null pointer.

   121      *

   122      * @param aItem Pointer to a tree item.

   123      *

   124      * @return ID of the given tree item.

   125      */

   126     TAknTreeItemID Id( const CAknTreeItem* aItem ) const;

   127 

   128     /**

   129      * Sets the ordering of the tree list.

   130      * The ordering defines the order of hierarchical list items. The list

   131      * items are always kept sorted according the set ordering object, and

   132      * whenever the ordering object is changed, the tree is sorted according

   133      * the newly set ordering.

   134      *

   135      * @param aOrdering Specialisation specific implementation for the

   136      *      abstract @c CAknTreeListOrdering class. This object defines the

   137      *      order of hierarchical list items.

   138      *

   139      * @param aDrawNow @c ETrue to redraw the list after it has been sorted.

   140      *

   141      * @post The list is sorted according to the set ordering.

   142      */

   143     void SetOrdering( CAknTreeOrdering* aOrdering, TBool aDrawNow );

   144 

   145     /**

   146      * Sets custom ordering for the tree.

   147      *

   148      * @param aOrdering Implementation for custom ordering interface defining

   149      *      the order of hierarchical list items.

   150      *

   151      * @param aDrawNow @c ETrue to redraw the list after it has been sorted.

   152      */

   153     void SetCustomOrdering( MAknCustomTreeOrdering* aOrdering, TBool aDrawNow );

   154 

   155     /**

   156      * Sorts the specified tree node.

   157      *

   158      * @param aNode Item ID of the node that has to be sorted.

   159      *

   160      * @param aSortDescendants @c ETrue to sort the content of the specified

   161      *      node including the content of its descendant nodes, @c EFalse to

   162      *      to sort only the child items within the specified node.

   163      *

   164      * @param aDrawNow @c ETrue to redraw the list after sorting.

   165      *

   166      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   167      *

   168      * @panic EAknHListPanicInvalidItemType Specified item is not a node.

   169      */

   170     void Sort( TAknTreeItemID aNode, TBool aSortDescendants, TBool aDrawNow );

   171 

   172     /**

   173      * Compares two tree items.

   174      *

   175      * @param aFirst First item.

   176      *

   177      * @param aSecond Second item.

   178      *

   179      * @return Positive, if the first item is greater than the second item;

   180      *      negative, if the first item is less than the second item;

   181      *      and zero, if the items are equal.

   182      */

   183     TInt Compare( const CAknTreeItem& aFirst, const CAknTreeItem& aSecond ) const;

   184 

   185     /**

   186      * Returns the number of items in the tree.

   187      *

   188      * @return Number of items.

   189      */

   190     TInt ItemCount() const;

   191 

   192     /**

   193      * Returns the number of visible items in the tree. This excludes all the

   194      * items in collapsed folders.

   195      *

   196      * @return Number of visible items.

   197      */

   198     TInt VisibleItemCount() const;

   199 

   200     /**

   201      * Returns the index of specified item. The index is equal to the number

   202      * of tree items in the tree structure before the specified item.

   203      *

   204      * @param aItem Pointer to tree item.

   205      *

   206      * @return The index of specified item. Value @c KErrNotFound is returned

   207      *      if the specified item is not found.

   208      */

   209     TInt ItemIndex( const CAknTreeItem* aItem ) const;

   210 

   211     /**

   212      * Returns the index from subset of visible items. The index is equal to

   213      * the number of tree items in the expanded tree structure before the 

   214      * specified item.

   215      *

   216      * @param aItem Pointer to tree item.

   217      *

   218      * @return The index of specified item. Value @c KErrNotFound is returned

   219      *      if the specified item is not found, or not in the expanded tree

   220      *      structure.

   221      */

   222     TInt VisibleItemIndex( const CAknTreeItem* aItem ) const;

   223 

   224     /**

   225      * Returns visible item based on the given index.

   226      *

   227      * @param aIndex Index defining the items position in expanded tree.

   228      *

   229      * @return Pointer to tree item. @c NULL, if item with given index is found.

   230      */ 

   231     CAknTreeItem* VisibleItem( TInt aIndex ) const;

   232 

   233     /**

   234      * Returns the depth of the tree, which equals to number of levels in the

   235      * expanded part of the tree.

   236      *

   237      * @return The depth of expanded tree structure.

   238      */

   239     TInt Depth() const;

   240 

   241     /**

   242      * Retrieves the specified item from the tree.

   243      *

   244      * @param aItemId ID of the item to be retrieved.

   245      *

   246      * @param aItem Reference to a pointer, which is replaced with a pointer

   247      *      to the specified item, if it is found from the tree.

   248      *

   249      * @return @c KErrNone, if the item is found from the tree. The return

   250      *      value @c KErrNotFound indicates that the item was not found.

   251      */

   252     TInt GetItem( TAknTreeItemID aItemId, CAknTreeItem*& aItem ) const;

   253 

   254     /**

   255      * Retrieves the specified item from the tree structure.

   256      *

   257      * @param aItemId ID of the item to be retrieved.

   258      *

   259      * @return The retrieved tree item.

   260      *

   261      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   262      */

   263     CAknTreeItem* Item( TAknTreeItemID aItemId ) const;

   264 

   265     /**

   266      * Retrieves the specified node from the tree structure.

   267      *

   268      * @param aNodeId ID of the node to be retrieved.

   269      *

   270      * @return The retrieved tree node.

   271      *

   272      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   273      *

   274      * @panic EAknHListPanicInvalidItemType Specified item is not a node.

   275      */

   276     CAknTreeNode* Node( TAknTreeItemID aNodeId ) const;

   277 

   278     /** 

   279      * Add a new item to the tree. The constant @c KAknTreeIIDRoot is to be

   280      * used as the ID of parent node, when item is added to the the top-most

   281      * level of the tree.

   282      *

   283      * @param aItem The item to be added to the tree structure.

   284      *

   285      * @param aParent ID of the parent node to which the item is to be added.

   286      *

   287      * @param aDrawNow @c ETrue, if the view is to be updated after the

   288      *      item has been added to the tree.

   289      *

   290      * @return Item ID assigned for the added item.

   291      */

   292     TAknTreeItemID AddItemL( CAknTreeItem* aItem, TAknTreeItemID aParent,

   293         TBool aDrawNow );

   294 

   295     /**

   296      * Moves the specified item to the specified target node. The constant

   297      * @c KAknTreeIIDRoot can be used as the ID of target node, when moving

   298      * the item to the top-most level of the tree.

   299      *

   300      * @param aItem ID of the item to be moved.

   301      *

   302      * @param aTargetNode ID of the node, where the item is to be moved.

   303      *

   304      * @param aDrawNow @c ETrue, if the view is to be updated after the

   305      *      item has been moved.

   306      *

   307      * @leave KErrArgument The specified item is the same as the target node

   308      *      or one of the ancestors of target node. 

   309      *

   310      * @leave KErrNoMemory Not enough memory is available for adding the

   311      *      specified item to the target node.

   312      *

   313      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   314      *

   315      * @panic EAknHListPanicInvalidItemType Specified target node is not a node.

   316      */

   317     void MoveItemL( TAknTreeItemID aItem, TAknTreeItemID aTargetNode,

   318         TBool aDrawNow );

   319 

   320     /**

   321      * Remove an existing item from the tree. If the specified item is a node,

   322      * all of its descendants will be removed from the tree as well.

   323      *

   324      * @param aItem The item to be removed from the tree structure.

   325      *

   326      * @param aDrawNow @c ETrue, if the view is to be updated after the

   327      *      item has been removed from the tree.

   328      *

   329      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   330      */

   331     void RemoveItem( TAknTreeItemID aItem, TBool aDrawNow );

   332 

   333     /**

   334      * Changes the state of the specified node to expanded. Using constant

   335      * @c KAknTreeIIDRoot as the node ID expands every node in the tree.

   336      *

   337      * @param aNode Item ID of the node to be expanded.

   338      *

   339      * @param aDrawNow @c ETrue, if the view is to be updated after the node

   340      *      has been expanded.

   341      *

   342      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   343      *

   344      * @panic EAknHListPanicInvalidItemType Specified item is not a node.

   345      */

   346     void ExpandNode( TAknTreeItemID aNode, TBool aDrawNow );

   347 

   348     /**

   349      * Changes the state of the specified node to collapsed. All the children

   350      * that are not set persistent will be deleted. Using constant @c

   351      * KAknTreeIIDRoot as the node ID collapses every node in the tree.

   352      *

   353      * @param aNode Item ID of the node to be collapsed.

   354      *

   355      * @param aDrawNow @c ETrue, if the view is to be updated after the node

   356      *      has been collapsed.

   357      *

   358      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   359      *

   360      * @panic EAknHListPanicInvalidItemType Specified item is not a node.

   361      */

   362     void CollapseNode( TAknTreeItemID aNode, TBool aDrawNow );

   363 

   364     /**

   365      * Checks if the specified node is expanded. 

   366      *

   367      * @param aNode Item ID of the node.

   368      *

   369      * @return @c ETrue, if the node is expanded.

   370      *

   371      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   372      *

   373      * @panic EAknHListPanicInvalidItemType Specified item is not a node.

   374      */

   375     TBool IsExpanded( TAknTreeItemID aNode ) const;

   376 

   377     /**

   378      * Returns the number of children of a tree node. This method, along with

   379      * @c Child() method, can be used for enquiring information of the tree

   380      * structure. Constant @c KAknTreeIIDRoot can be used to get the

   381      * item count on the top-most level of the list.

   382      *

   383      * @param aNode Item ID of a node.

   384      *

   385      * @return Number of children of specified node.

   386      *

   387      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   388      *

   389      * @panic EAknHListPanicInvalidItemType Specified item is not a node.

   390      */

   391     TInt ChildCount( TAknTreeItemID aNode ) const;

   392 

   393     /**

   394      * Returns the item ID of a child of a tree node. The specific child is

   395      * specified with an index. The child count for any hierarchical

   396      * list node can be get with @c ChildCount() method.

   397      *

   398      * @param aNode Item ID of the node, whose child is enquiried.

   399      *

   400      * @param aIndex Index of the enquiried child.

   401      *

   402      * @return Item ID of the specified child. Value @c KAknTreeIIDNone is

   403      *      returned, if the child with specified index does not exist.

   404      * 

   405      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   406      *

   407      * @panic EAknHListPanicInvalidItemType Specified item is not a node.

   408      */

   409     TAknTreeItemID Child( TAknTreeItemID aNode, TInt aIndex ) const;

   410 

   411     /**

   412      * Returns the item ID of a parent node of specified tree item.

   413      * 

   414      * @param aItem Item ID of the item, whose parent is queried.

   415      *

   416      * @return Item ID of the parent node.

   417      *

   418      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   419      */

   420     TAknTreeItemID Parent( TAknTreeItemID aItem ) const;

   421     

   422     /**

   423      * Adds new observer for the tree. The ownership of the observer interface

   424      * is not transferred to the tree.

   425      *

   426      * @param aObserver Observer.

   427      */

   428     void AddObserverL( MAknTreeObserver* aObserver );

   429 

   430     /**

   431      * Removes an observer from the tree.

   432      *

   433      * @param aObserver Observer to be removed.

   434      *

   435      * @return @c KErrNotFound, if the specified observer is not found.

   436      *      Otherwise, the value @c KErrNone is used.

   437      */

   438     TInt RemoveObserver( MAknTreeObserver* aObserver );

   439 

   440     /**

   441      * Checks whether the specified item is marked.

   442      *

   443      * @param aItem Item ID.

   444      *

   445      * @return @c ETrue, if the item is marked.

   446      *

   447      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   448      */

   449     TBool IsMarked( TAknTreeItemID aItem ) const;

   450 

   451     /**

   452      * Sets the specified item marked or unmarked.

   453      *

   454      * @param aItem Item ID of modified item.

   455      *

   456      * @param aMarked @c ETrue to set item marked, @c EFalse to unmarked.

   457      *

   458      * @param aDrawNow @c ETrue to redraw the view.

   459      *

   460      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   461      */

   462     void SetMarked( TAknTreeItemID aItem, TBool aMarked, TBool aDrawNow );

   463 

   464     /**

   465      * Enables or disables marking of specified list item.

   466      *

   467      * @param aItem Item ID of the list item.

   468      *

   469      * @param aEnable @c ETrue to enable marking, @c EFalse to disable it.

   470      *

   471      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   472      */

   473     void EnableMarking( TAknTreeItemID aItem, TBool aEnable );

   474 

   475     /**

   476      * Gets all the marked items from the specified node. The marked items

   477      * are appended to the end of the array passed as parameter.

   478      *

   479      * @param aNode Item ID of a node from where the marked items are

   480      *      retrieved.

   481      *

   482      * @param aMarkedItems On return, contains item IDs of marked items in

   483      *      the specified node.

   484      *

   485      * @leave KErrNoMemory Appending item to the array fails.

   486      *

   487      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   488      *

   489      * @panic EAknHListPanicInvalidItemType Specified item is not a node.

   490      */

   491     void GetMarkedItemsL( TAknTreeItemID aNode,

   492         RArray<TAknTreeItemID>& aMarkedItems ) const;

   493 

   494     /**

   495      * Checks whether the specified node is empty.

   496      *

   497      * @param aNode Item ID for a node.

   498      *

   499      * @return @c ETrue, if the item is empty.

   500      *

   501      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   502      *

   503      * @panic EAknHListPanicInvalidItemType Specified target item is not a node.

   504      */

   505     TBool IsEmpty( TAknTreeItemID aNode ) const;

   506 

   507     /**

   508      * Sets whether the specified node appears as non-empty when empty.

   509      *

   510      * @param aNode Item ID for a node.

   511      *

   512      * @param aNonEmpty @c ETrue to set node appear non-empty, @c EFalse to

   513      *      to remove previously set flag.

   514      *

   515      * @param aDrawNow @c ETrue to redraw the list.

   516      *

   517      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   518      *

   519      * @panic EAknHListPanicInvalidItemType Specified target item is not a node.

   520      */

   521     void SetNonEmpty( TAknTreeItemID aNode, TBool aNonEmpty, TBool aDrawNow );

   522 

   523     /**

   524      * Checks whether the specified item is persistent.

   525      *

   526      * @param aItem Item ID.

   527      *

   528      * @return @c ETrue, if the item is persistent.

   529      *

   530      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   531      */

   532     TBool IsPersistent( TAknTreeItemID aItem ) const;

   533 

   534     /**

   535      * Sets the specified item persistent or non-persistent.

   536      *

   537      * @param aItem Item ID of modified item.

   538      *

   539      * @param aPersistent @c ETrue to set item persistent.

   540      *

   541      * @panic EAknHListPanicInvalidItemID Item with specified ID is not found.

   542      */

   543     void SetPersistent( TAknTreeItemID aItem, TBool aPersistent );

   544 

   545     /**

   546      * Creates an iterator for the the expanded tree structure.

   547      *

   548      * @return Iterator.

   549      */

   550     TAknTreeIterator Iterator() const;

   551 

   552     /**

   553      * Creates an iterator for traversing the tree structure under the

   554      * specified tree node.

   555      *

   556      * @param aNode Iterated node.

   557      *

   558      * @param aFlags Flags for the iterator. The @c KSkipCollapsedNodeContents

   559      *      flag can be used to skip the contents of all collapsed nodes.

   560      *

   561      * @return Iterator.

   562      */

   563     TAknTreeIterator Iterator( CAknTreeNode* aNode, TUint aFlags ) const;

   564 

   565     /**

   566      * Notifies the observers that an item has been modified.

   567      *

   568      * @param aItem Modified item.

   569      */

   570     void ItemModified( CAknTreeItem* aItem );

   571 

   572     /**

   573      * Adds icon to the tree. The icon is constructed based on the given

   574      * parameters and the parameters are stored in the tree, so that the icon

   575      * can be reconstructed on skin change event.

   576      *

   577      * @param aId ID of the masked bitmap to be created.

   578      *

   579      * @param aFilename Filename to be used to construct the item, if no

   580      *      matching item was found in the currently active skin.

   581      *

   582      * @param aBitmapId ID of the bitmap in the file. Used only if no matching

   583      *      item was found in the currently active skin.

   584      *

   585      * @param aMaskId ID of the mask in the file. Used only if no matching item

   586      *      was found in the currently active skin.

   587      *

   588      * @param aScaleMode Scale mode used when icon's bitmap is resized.

   589      *

   590      * @return Icon ID assigned for the created icon.

   591      */

   592     TInt AddIconL( const TAknsItemID& aId, const TDesC& aFilename,

   593         TInt aBitmapId, TInt aMaskId, TScaleMode aScaleMode );

   594 

   595     /**

   596      * Adds icon to the tree. Icons added with this method are not

   597      * reconstructed on skin change events.

   598      *

   599      * @param aIcon Pointer to the bitmap.

   600      *

   601      * @param aMask Pointer to the mask bitmap.

   602      *

   603      * @param aTransferOwnership @c ETrue, if ownership of bitmaps is

   604      * transferred to the list. If the method leaves, it is always on the

   605      * responsibility of the client code to take care of deleting the bitmaps.

   606      *

   607      * @param aScaleMode Scale mode used when icon's bitmap is resized.

   608      *

   609      * @return Icon ID assigned for the created icon.

   610      */

   611     TInt AddIconL( CFbsBitmap* aIcon, CFbsBitmap* aMask,

   612         TBool aTransferOwnership, TScaleMode aScaleMode );

   613 

   614     /**

   615      * Adds colored icon to the tree. The icon is constructed based on the

   616      * given parameters and the parameters are stored in the tree, so that the

   617      * icon can be reconstructed on skin change event

   618      *

   619      * @param aId Item ID of the masked bitmap to be created.

   620      *

   621      * @param aColorId Item ID of the color table.

   622      *

   623      * @param aColorIndex Index in the color table.

   624      *

   625      * @param aFilename Filename to be used to construct the item, if no

   626      *      matching item was found in the currently active skin.

   627      *

   628      * @param aBitmapId ID of the bitmap in the file. Used only if no matching

   629      *      item was found in the currently active skin.

   630      *

   631      * @param aMaskId ID of the mask in the file. Used only if no matching item

   632      *      was found in the currently active skin.

   633      *

   634      * @param aDefaultColor Color RGB value to be used, if no color is found in

   635      *      the currently active skin.

   636      *

   637      * @param aScaleMode Scale mode used when icon's bitmap is resized.

   638      *

   639      * @return Icon ID assigned for the created icon.

   640      */

   641     TInt AddColorIconL( const TAknsItemID& aId, const TAknsItemID& aColorId,

   642         TInt aColorIndex, const TDesC& aFilename, TInt aBitmapId,

   643         TInt aMaskId, TRgb aDefaultColor, TScaleMode aScaleMode );

   644 

   645     /**

   646      * Sets icon to the list with specified icon ID. If icon with the same ID

   647      * is already added to the tree, the existing icon is replaced with the

   648      * new.

   649      *

   650      * @param aIconId Assigned icon ID for the icon.

   651      *

   652      * @param aId Item ID of the masked bitmap to be created.

   653      *

   654      * @param aFilename Filename to be used to construct the item, if no

   655      *      matching item was found in the currently active skin.

   656      *

   657      * @param aBitmapId ID of the bitmap in the file. Used only if no matching

   658      *      item was found in the currently active skin.

   659      *

   660      * @param aMaskId ID of the mask in the file. Used only if no matching item

   661      *      was found in the currently active skin.

   662      *

   663      * @param aScaleMode Scale mode used when icon's bitmap is resized.

   664      */

   665     void SetIconL( TInt aIconId, const TAknsItemID& aId,

   666         const TDesC& aFilename, TInt aBitmapId, TInt aMaskId,

   667         TScaleMode aScaleMode );

   668 

   669     /**

   670      * Sets icon to the list with specified icon ID. If icon with the same ID

   671      * is already added to the tree, the existing icon is replaced with the

   672      * new. This method adds only the bitmaps to the list, and they cannot

   673      * be reconstructed by the list on skin change events.

   674      * 

   675      * @param aIconId Assigned icon ID for the icon.

   676      *

   677      * @param aIcon Pointer to the bitmap.

   678      *

   679      * @param aMask Pointer to the mask bitmap.

   680      *

   681      * @param aTransferOwnership @c ETrue, if ownership of bitmaps is

   682      * transferred to the list. If the method leaves, it is always on the

   683      * responsibility of the client code to take care of deleting the bitmaps.

   684      *

   685      * @param aScaleMode Scale mode used when icon's bitmap is resized.

   686      */

   687     void SetIconL( TInt aIconId, CFbsBitmap* aIcon, CFbsBitmap* aMask, 

   688         TBool aTransferOwnership, TScaleMode aScaleMode );

   689 

   690     /**

   691      * Sets color icon to the list with specified icon ID. If icon with the

   692      * same ID is already added to the tree, the existing icon is replaced with

   693      * the new.

   694      *

   695      * @param aIconId Assigned icon ID for the icon.

   696      *

   697      * @param aId Item ID of the masked bitmap to be created.

   698      *

   699      * @param aColorId Item ID of the color table.

   700      *

   701      * @param aColorIndex Index in the color table.

   702      *

   703      * @param aFilename Filename to be used to construct the item, if no

   704      *      matching item was found in the currently active skin.

   705      *

   706      * @param aBitmapId ID of the bitmap in the file. Used only if no matching

   707      *      item was found in the currently active skin.

   708      *

   709      * @param aMaskId ID of the mask in the file. Used only if no matching item

   710      *      was found in the currently active skin.

   711      *

   712      * @param aDefaultColor Color RGB value to be used, if no color is found in

   713      *      the currently active skin.

   714      *

   715      * @param aScaleMode Scale mode used when icon's bitmap is resized.

   716      */

   717     void SetColorIconL( TInt aIconId, const TAknsItemID& aId,

   718         const TAknsItemID& aColorId, TInt aColorIndex, const TDesC& aFilename,

   719         TInt aBitmapId, TInt aMaskId, TRgb aDefaultColor,

   720         TScaleMode aScaleMode );

   721 

   722     /**

   723      * Removes previously added icon from the tree.

   724      *

   725      * @param aIconId ID of the removed icon.

   726      *

   727      * @leave KErrArgument if specified icon is one of the default icons.

   728      */

   729     void RemoveIconL( TInt aIconId );

   730 

   731     /**

   732      * Gets pointer to the specified tree list icon. The ownership of the

   733      * icon is not transferred to the caller.

   734      *

   735      * @param aIconId Icon ID specifying the requested icon.

   736      *

   737      * @return Pointer to the requested icon, or NULL if icon with specified

   738      *      ID was not found.

   739      */

   740     CAknTreeListIcon* Icon( TInt aIconId ) const;

   741 

   742     /**

   743      * Draws the specified icon. The icon is specified with the ID value,

   744      * which can be one of the default values in @c CAknTree::TIcon enumeration,

   745      * or a value returned when the icon was added to the list.

   746      *

   747      * @param aIconId Icon ID specifying the icon.

   748      *

   749      * @param aSize Size of the icon.

   750      *

   751      * @param aGc Graphics context the icon is drawn to.

   752      *

   753      * @param aPoint A position for the top left corner of the icon.

   754      *

   755      * @param aSourceRect A rectangle defining the piece of the icon to be

   756      *      drawn, with co-ordinates relative to the top left corner of the

   757      *      bitmap.

   758      *

   759      * @return @c KErrNotFound, if no icon with specified ID is found,

   760      *      otherwise @c KErrNone.

   761      */

   762     TInt DrawIcon( TInt aIconId, const TSize& aSize, CWindowGc& aGc,

   763         const TPoint& aPoint, const TRect& aSourceRect );

   764 

   765     /**

   766      * Draws text for tree list item. Text is drawn with marquee scrolling

   767      * when marquee scrolling is enabled, the text does not fit to the

   768      * rectangle appointed to it, and the item is focused. Otherwise, when

   769      * some of the conditions above are not true, text is drawn normally with

   770      * clipping.

   771      *

   772      * @param aGc Graphics context.

   773      *

   774      * @param aRect Parent rectangle for the text layout.

   775      *

   776      * @param aTextLayout Text layout.

   777      *

   778      * @param aText Text.

   779      *

   780      * @param aFont Font. @c NULL if the font defined in layout is used.

   781      *

   782      * @param aItem Pointer to the tree list item, for which the text is drawn.

   783      *

   784      * @param aFocused @c ETrue, if the text is drawn for focused tree list

   785      *      item, otherwise @c EFalse.

   786      *

   787      * @param aMarquee @c ETrue, if marquee can be used for drawing the text

   788      *      when marquee scrolling is enabled for the list.

   789      */

   790      void DrawText( CWindowGc& aGc, const TRect& aRect,

   791         const TAknTextComponentLayout& aTextLayout, const TDesC& aText,

   792         const CFont* aFont, const CAknTreeItem* aItem, TBool aFocused,

   793         TBool aMarquee );

   794 

   795     /**

   796      * Handles skin change.

   797      */

   798     void HandleSkinChangeL();

   799 

   800     /**

   801      * Enables marquee scrolling.

   802      *

   803      * @param aEnable @c ETrue to enable marquee, @c EFalse to disable it.

   804      */

   805     void EnableMarquee( TBool aEnable );

   806 

   807     /**

   808      * Returns whether marquee scrolling is enabled.

   809      *

   810      * @return @c ETrue when enabled, otherwise @c EFalse.

   811      */

   812     TBool IsMarqueeOn() const;

   813 

   814     /**

   815      * Callback function for marquee control.

   816      *

   817      * @param aThis Pointer to an instance of @c CAknTree.

   818      */

   819     static TInt MarqueeRedrawRequest( TAny* aThis );

   820 

   821     /**

   822      * Enables tabulator mode expand and collapse function indicators.

   823      *

   824      * @param @aEnable @c ETrue to enable tabulator mode indicators.

   825      */

   826     void EnableTabModeFunctionIndicatorsL( TBool aEnable );

   827 

   828     /**

   829      * Checks whether tabulator mode expand and collapse function indicators are

   830      * enabled.

   831      *

   832      * @return @c ETrue when enabled, otherwise @c EFalse.

   833      */

   834     TBool TabModeFunctionIndicators() const;

   835 

   836 // from base class CAknTreeItem

   837 

   838     /**

   839      * From CAknTreeItem.

   840      * Returns the type of the item.

   841      *

   842      * @return Item type.

   843      */

   844     TInt Type() const;

   845 

   846     /**

   847      * From CAknTreeItem.

   848      * Returns pointer to the root of the tree. This implementation will simply

   849      * return the pointer to this object, as an instance of @c CAknTree will

   850      * always be set as the root of the tree.

   851      *

   852      * @return Pointer to the tree root.

   853      */

   854     CAknTree* Root() const;

   855 

   856 // from base class CAknTreeNode

   857 

   858     /**

   859      * From CAknTreeNode.

   860      * Changes the state of the whole tree, that is, every node, to expanded.

   861      */

   862     void Expand();

   863 

   864     /**

   865      * From CAknTreeNode.

   866      * Changes the state of the whole tree, that is, every node, to collapsed.

   867      */

   868     void Collapse();

   869 

   870 private:

   871 

   872     /**

   873      * Constructor.

   874      *

   875      * @param aList The list owning the tree instance.

   876      *

   877      * @param aOrdering Ordering for the tree items.

   878      */

   879     CAknTree( CAknTreeList& aList, CAknTreeOrdering* aOrdering );

   880 

   881     /**

   882      * Second phase constructor.

   883      */

   884     void ConstructL();

   885 

   886     /**

   887      * Notifies the observers of the tree of specified tree event.

   888      *

   889      * @param aEvent Tree event.

   890      *

   891      * @param aItem Pointer to the tree item affected by the tree event.

   892      *

   893      * @param aDrawNow @c ETrue, if the view is to be redrawn after the event.

   894      */

   895     void NotifyObservers( MAknTreeObserver::TEvent aEvent, CAknTreeItem* aItem,

   896         TBool aDrawNow );

   897 

   898     /**

   899      * Used in marquee control callback.

   900      */

   901     TInt DoMarqueeRedrawRequest();

   902 

   903     /**

   904      * Searches for available icon ID.

   905      *

   906      * @return Available icon ID.

   907      */

   908     TInt AvailableIconId() const;

   909 

   910     /**

   911      * Adds an icon to the icon array. The icons in the array are kept

   912      * ordered based on their ID's. If some icon in the array already has the

   913      * same ID as the added icon, it is replaced with the new icon.

   914      *

   915      * @param aIcon Icon.

   916      */

   917     void AddIconL( CAknTreeListIcon* aIcon );

   918 

   919     /**

   920      * Sorts every node in the tree according to set ordering.

   921      *

   922      * @param aDrawNow @c ETrue to redraw the list after it has been sorted.

   923      */

   924     void Sort( TBool aDrawNow );

   925 

   926     /**

   927      * Expands the specified node and notifies the observers of the event.

   928      *

   929      * @param aNode Pointer to the node to be expanded.

   930      *

   931      * @param aDrawNow @c ETrue, if the view is to be redrawn after the node

   932      *      has been expanded.

   933      */

   934     void DoExpandNode( CAknTreeNode* aNode, TBool aDrawNow );

   935 

   936 // from base class CAknTreeItem

   937 

   938     /**

   939      * From CAknTreeItem.

   940      */

   941     void Draw( CWindowGc& aGc, const TRect& aItemRect, const TRect& aRect,

   942         TBool aFocused ) const;

   943 

   944 private: // data

   945 

   946     /**

   947      * The tree list owning the tree instance.

   948      */

   949     CAknTreeList& iList;

   950 

   951     /**

   952      * Ordering for the tree.

   953      * Own.

   954      */

   955     CAknTreeOrdering* iOrdering;

   956 

   957     /**

   958      * Custom ordering for the tree.

   959      * Not owned.

   960      */

   961     MAknCustomTreeOrdering* iCustomOrdering;

   962 

   963     /**

   964      * Tree observers.

   965      * Not owned.

   966      */

   967     RPointerArray<MAknTreeObserver> iObservers;

   968 

   969     /**

   970      * Pointer array containin pointers to all tree items.

   971      * Not owned.

   972      */

   973     RPointerArray<CAknTreeItem> iItems;

   974 

   975     /**

   976      * Pointer array containing pointers to stored icons.

   977      * Own.

   978      */

   979     RPointerArray<CAknTreeListIcon> iIcons;

   980 

   981     /**

   982      * Marquee control.

   983      * Own.

   984      */

   985     CAknMarqueeControl* iMarquee;

   986 

   987     /**

   988      * The tree item using the marquee control.

   989      * Not own.

   990      */

   991     const CAknTreeItem* iMarqueeItem;

   992 

   993     /**

   994      * Flags for tree settings.

   995      */

   996     TBitFlags32 iFlags;

   997 

   998     };

   999 

  1000 

  1001 #endif // C_AKNTREE_H