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:  Abstract base class for hierarchical lists.

    15 *

    16 */

    17 

    18 

    19 #ifndef C_AKNTREELIST_H

    20 #define C_AKNTREELIST_H

    21 

    22 

    23 #include <AknControl.h>

    24 #include <w32std.h>

    25 #include <akntreelistobserver.h>

    26 #include <AknIconUtils.h> // TScaleMode

    27 

    28 class CAknTree;

    29 class CAknTreeListView;

    30 class MAknCustomTreeOrdering;

    31 class TAknsItemID;

    32 

    33 /** Flag to indicate that hierarchical list is looping. */

    34 const TUint32 KAknTreeListLooping = 0x0001;

    35 

    36 /** Flag to indicate that hierarchical list structure lines are not visible. */

    37 const TUint32 KAknTreeListNoStructureLines = 0x0002;

    38 

    39 /** Flag to set marquee scrolling on. */

    40 const TUint32 KAknTreeListMarqueeScrolling = 0x0004;

    41 

    42 /** Flag to disable indention of hierarchical list items. Setting this flag

    43     also forces the tree structure lines invisible. */

    44 const TUint32 KAknTreeListNoIndention = 0x0008;

    45 

    46 /** Flag to set hierarchical list markable. The list items can always be

    47     marked by list client with API methods, but when list is set markable,

    48     it responds to specified pointer and key event by marking/unmarking

    49     items as required. */

    50 const TUint32 KAknTreeListMarkable = 0x0010;

    51 

    52 

    53 /**

    54  *  Abstract base class for hierarchical lists.

    55  *

    56  *  This class functions as a base class for hierarchical lists. It contains

    57  *  the APIs common to all hierarchical lists. The internal structure of the

    58  *  list is not exposed directly to the list clients, instead the structure

    59  *  can be accessed through the APIs in this class. The items in the list are

    60  *  referred with item IDs, which are returned to the client when the items

    61  *  are added to the list.

    62  *

    63  *  List items are divided into leaves and nodes, the difference being that

    64  *  nodes have expand and collapse functionality and can contain other tree

    65  *  items as child items, whereas leaves cannot contain other list items.

    66  *  Methods @c IsLeaf() and @c IsNode() can be used for checking if items

    67  *  belong into these groups.

    68  *

    69  *  The expand and collapse events, among other list events, are send to list

    70  *  observers through @c MAknTreeListObserver interface. This enables that

    71  *  the whole list does not have to be populated at once, as the content of

    72  *  each node can be added when the node is expanded. To avoid unnecessary

    73  *  memory consumption, the content of each node is removed from the list

    74  *  when the node is collapsed. However, list items can be set persistent,

    75  *  in which case they are not removed from nodes on collapse events.

    76  *

    77  *  As the hierarchical list items are list specialisation specific, the

    78  *  specialisations of this class have to provide APIs for constructing and

    79  *  adding new items to the list, and getting and setting specialisation

    80  *  specific properties of the list items.

    81  *

    82  *  All the methods that might affect the appearance of the list view have an

    83  *  additional @c aDrawNow parameter, which can be used to indicate whether

    84  *  the list view should be redrawn to correspond to the modified list

    85  *  structure. This allows consecutive calls to be made without the list view

    86  *  being updated between every call by setting the @c aDrawNow parameter to

    87  *  @c EFalse in all of the calls but the last. The normal draw methods 

    88  *  inherited from @c CCoeControl can also be used to draw the updated view.

    89  *

    90  *  @see MAknTreeListObserver

    91  *

    92  *  @lib aknhlist.lib

    93  *  @since S60 v3.2

    94  */

    95 NONSHARABLE_CLASS( CAknTreeList ) : public CAknControl

    96     {

    97 

    98 public:

    99 

   100 

   101 	// for focus handling after Sort

   102    enum TFocusBehaviour

   103             {

   104             ESaveFocus,

   105             EMoveFocusToFirstItem

   106             };

   107 

   108     /**

   109      * Destructor.

   110      */

   111     virtual ~CAknTreeList();

   112 

   113     /**

   114      * Sets the flags for the hierarchical list.

   115      *

   116      * Flags @c KAknTreeListLooping, @c KAknTreeListNoStructureLines,

   117      * @c KAknTreeListMarqueeScrolling, @c KAknTreeListNoIndention, and

   118      * @c KAknTreeListMarkable can be used to change the behaviour

   119      * of the list.

   120      *

   121      * Note: Specialisations may override this method in order to restrict the

   122      * use of some of the flags in specialised list or to handle specialisation

   123      * specific flags.

   124      *

   125      * @param aFlags Flags.

   126      */

   127     IMPORT_C virtual void SetFlags( TUint32 aFlags );

   128 

   129     /**

   130      * Returns the flags set for the list.

   131      *

   132      * @return Flags.

   133      */

   134     IMPORT_C TUint32 Flags() const;

   135 

   136     /**

   137      * Moves an existing list item to specified target node. The moved item

   138      * and the target node have to be specified with the item IDs returned

   139      * when the items were added to the hierarchical list. The target node

   140      * cannot be a descendant of the moved node. Otherwise, the moving would

   141      * break the hierarchical structure. Constant @c KAknTreeIIDRoot can be

   142      * used as an ID for the target node when the item is to be moved to the

   143      * top-most level of the list.

   144      *

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

   146      *

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

   148      *

   149      * @param aDrawNow @c ETrue to redraw the list after the item has been

   150      *      moved, otherwise @c EFalse.

   151      *

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

   153      *      or one of the ancestors of target node. 

   154      *

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

   156      *      specified item to the target node.

   157      *

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

   159      *

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

   161      *

   162      * @pre The moved item and the target node exist in the list, and the

   163      *      target node is not a descendant of the moved item.

   164      *

   165      * @post The item is moved to the specified target node and into a such

   166      *      position that the children of the target node remain in sorted

   167      *      order. The updated list is redrawn, if it is requested with the

   168      *      aDrawNow parameter.

   169      */

   170     IMPORT_C void MoveItemL( TAknTreeItemID aItem, TAknTreeItemID aTargetNode,

   171         TBool aDrawNow );

   172 

   173     /**

   174      * Removes an item from the hierarchical list. The item to be removed has

   175      * to be specified with the ID value returned when the item was added to

   176      * the hierarchical list. If the removed item is a node containing other

   177      * list items, those items are removed from the list as well. Constant

   178      * @c KAknTreeIIDRoot can be used to remove every item from the list.

   179      *

   180      * @param aItem Item ID of the item to be removed.

   181      *

   182      * @param aDrawNow @c ETrue to redraw the list after the item has been

   183      *      removed, othewise @c EFalse.

   184      *

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

   186      *

   187      * @pre The specified item exists in the hierarchical list.

   188      *

   189      * @post The specified item and all of its descendants are removed from

   190      *      the list. The updated list is drawn, when it is requested with

   191      *      the aDrawNow parameter.

   192      */

   193     IMPORT_C void RemoveItem( TAknTreeItemID aItem, TBool aDrawNow );

   194 

   195     /**

   196      * Expands a node in hierarchical list. When a node in the hierarchical

   197      * list is expanded, either with this method, or with pointer or key

   198      * event, the observer of the list is notified with respective event.

   199      * The client of the list can then update the content of the expanded

   200      * node. Constant @c KAknTreeIIDRoot can be used to expand every node

   201      * in the tree structure.

   202      *

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

   204      * 

   205      * @param aDrawNow @c ETrue to redraw the list after the node has been

   206      *      expanded, otherwise @c EFalse.

   207      *

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

   209      *

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

   211      *

   212      * @pre The specified item exists in the hierarchical list and it is a

   213      *      node.

   214      *

   215      * @post The specified node is expanded. The updated list is drawn, when

   216      *      it is requested with the aDrawNow parameter.

   217      */

   218     IMPORT_C void ExpandNode( TAknTreeItemID aNode, TBool aDrawNow );

   219 

   220     /**

   221      * Collapses a node in hierarchical list. When a node in the hierarchical

   222      * list is collapsed, either with this method, or with pointer or key

   223      * event, all its content that is not set persistent is removed from the

   224      * list to reduce memory consumption. The observer of the hierarchical

   225      * list is nofied with the respective event. Constant @c KAknTreeIIDRoot

   226      * can be used to collapse every node in the tree structure.

   227      *

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

   229      *

   230      * @param aDrawNow @c ETrue to redraw the list after the node has been

   231      *      collapsed, otherwise @c EFalse.

   232      *

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

   234      *

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

   236      *

   237      * @pre The specified item exists in the hierarchical list and it is a

   238      *      node.

   239      *

   240      * @post The specified item is collapsed and all of its children, which are

   241      *      not set persistent, are removed from the list.

   242      */

   243     IMPORT_C void CollapseNode( TAknTreeItemID aNode, TBool aDrawNow );

   244 

   245     /**

   246      * Checks whether the specified node is expanded.

   247      *

   248      * @param aNode Item ID of a node.

   249      *

   250      * @return @c ETrue if the node is expanded.

   251      *

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

   253      *

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

   255      */

   256     IMPORT_C TBool IsExpanded( TAknTreeItemID aNode ) const;

   257 

   258     /**

   259      * Gets the item ID of the focused item.

   260      *

   261      * @return Item ID of the focused item. Value @c KAknTreeIIDNone is

   262      *      returned if no item is focused.

   263      */

   264     IMPORT_C TAknTreeItemID FocusedItem() const;

   265 

   266     /**

   267      * Sets the focused item and its position on the list view. When the

   268      * focused item is changed, the vertical position of the view is changed

   269      * so that the position of the focused item on the view matches the given

   270      * index. The horizontal position of the view is changed so that the

   271      * the beginning of the focused item is visible.

   272      *

   273      * @param aItem Item ID of the item to be focused.

   274      *

   275      * @param aIndex The position of the focused item on the list view. If the

   276      *      index does not refer to any visible view location, that is, the

   277      *      index is less than zero or greater than or equal to the number of

   278      *      items in the view, the focused item is changed to specified item,

   279      *      but the position of the view is not changed.

   280      *

   281      * @param aDrawNow @c ETrue to redraw the list after the focused item

   282      *      has been changed, otherwise @c EFalse.

   283      *

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

   285      */

   286     IMPORT_C void SetFocusedItem( TAknTreeItemID aItem, TInt aIndex,

   287         TBool aDrawNow );

   288 

   289     /**

   290      * Highlight rectangle for the focused item. The returned rectangle is

   291      * screen relative and it can be used, for example, when positioning

   292      * pop-up for focused item. If the focused item is not visible, the

   293      * method returns an empty rectangle.

   294      *

   295      * @return Highlight rectangle of focused list item.

   296      */

   297     IMPORT_C TRect HighlightRect() const;

   298 

   299     /**

   300      * Adds a new icon to the list to be used by all list items. The same

   301      * icon can be used by multiple tree items and its referenced by the

   302      * ID returned by this function. The given parameters are also stored

   303      * in the tree list, which enables the tree list to reconstruct the

   304      * bitmaps on skin change events. If this behaviour is insufficient for

   305      * the client, it can always replace the existing icons by itself with

   306      * @c AssignIconL or @c AssignColorIconL method.

   307      *

   308      * @param aId Item ID of the icon to be added.

   309      *

   310      * @param aFilename Filename to be used to construct the item, 

   311      *      if no matching item was found in the currently active skin.

   312      *

   313      * @param aBitmapId ID of the bitmap in the file. 

   314      *      Used only if no matching item was found in the currently 

   315      *      active skin.

   316      *

   317      * @param aMaskId ID of the mask in the file.

   318      *      Used only if no matching item was found in the currently

   319      *      active skin.

   320      * 

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

   322      *

   323      * @return ID assigned for the added icon.

   324      *

   325      * @leave KErrNoMemory Not enough memory.

   326      */

   327     IMPORT_C TInt AddIconL( const TAknsItemID& aId, const TDesC& aFilename,

   328         TInt aBitmapId, TInt aMaskId, TScaleMode aScaleMode );

   329 

   330     /**

   331      * Adds a new icon to the list. The ownership of given bitmaps is

   332      * transferred to the list only if specified with @c aTransferOwnership

   333      * parameter. Note that icons added to the list with this method cannot

   334      * be reconstructed on skin change events by the list. If necessary,

   335      * previously added icons can be replaced with @c AssignIconL method.

   336      *

   337      * @param aIcon Pointer to the bitmap.

   338      *

   339      * @param aMask Pointer to the mask bitmap.

   340      *

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

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

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

   344      *

   345      * @param aScaleMode The scale mode used when the icon is resized.

   346      *

   347      * @return ID assigned for the added icon.

   348      *

   349      * @leave KErrNoMemory Not enough memory.

   350      */

   351     IMPORT_C TInt AddIconL( CFbsBitmap* aIcon, CFbsBitmap* aMask,

   352         TBool aTransferOwnership, TScaleMode aScaleMode );

   353 

   354     /**

   355      * Adds a new icon to the list to be used by all list items. The same

   356      * icon can be used by multiple tree items and it is referenced by the

   357      * icon ID returned by this function. The given parameters are stored

   358      * in the tree list, and they are used in reconstructing the bitmaps on

   359      * skin change events.

   360      *

   361      * @param aId Item ID of the icon to be added.

   362      *

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

   364      *

   365      * @param aColorIndex Index in the color table.

   366      *

   367      * @param aFilename Filename to be used to construct the item, 

   368      *      if no matching item was found in the currently active skin.

   369      *

   370      * @param aBitmapId ID of the bitmap in the file. 

   371      *      Used only if no matching item was found in the currently 

   372      *      active skin.

   373      *

   374      * @param aMaskId ID of the mask in the file.

   375      *      Used only if no matching item was found in the currently

   376      *      active skin.

   377      *

   378      * @param aDefaultColor Color RGB value to be used, if no color

   379      *      is found in the currently active skin.

   380      *

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

   382      *

   383      * @return ID assigned for the added icon.

   384      *

   385      * @leave KErrNoMemory Not enough memory.

   386      */

   387     IMPORT_C TInt AddColorIconL( const TAknsItemID& aId,

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

   389         TInt aBitmapId, TInt aMaskId, TRgb aDefaultColor,

   390         TScaleMode aScaleMode );

   391 

   392     /**

   393      * Assigns an icon to the tree list with the specified ID. If an icon

   394      * with specified ID already exists in the list, the existing icon is

   395      * replaced with the new one. The given parameters are stored in the

   396      * tree list, and they are used in reconstructing the bitmaps on skin

   397      * change events.

   398      *

   399      * @param aIconId Icon ID assigned for the icon.

   400      *

   401      * @param aId Item ID of the icon to be added.

   402      *

   403      * @param aFilename Filename to be used to construct the item, 

   404      *      if no matching item was found in the currently active skin.

   405      *

   406      * @param aBitmapId ID of the bitmap in the file. 

   407      *      Used only if no matching item was found in the currently 

   408      *      active skin.

   409      *

   410      * @param aMaskId ID of the mask in the file.

   411      *      Used only if no matching item was found in the currently

   412      *      active skin.

   413      *

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

   415      *

   416      * @leave KErrNoMemory Not enough memory.

   417      *

   418      * @leave KErrArgument Specified icon ID is out of allowed range.

   419      */

   420     IMPORT_C void AssignIconL( TInt aIconId, const TAknsItemID& aId,

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

   422         TScaleMode aScaleMode );

   423 

   424     /**

   425      * Assigns an icon to the tree list with the specified ID. If an icon

   426      * with specified ID already exists in the list, the existing icon is

   427      * replaced with the new one. The ownership of bitmaps is transferred to

   428      * the list only if so specifed with @c aTransferOnwership parameter.

   429      * Note that icons added with this method cannot be reconstructed on

   430      * skin change events by list.

   431      *

   432      * @param aIconId Icon ID assigned for the icon.

   433      *

   434      * @param aIcon Pointer to the bitmap.

   435      *

   436      * @param aMask Pointer to the mask bitmap.

   437      *

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

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

   440      *      the responsibility of the client code to take care of deleting

   441      *      the bitmaps.

   442      *

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

   444      *

   445      * @leave KErrNoMemory Not enough memory.

   446      *

   447      * @leave KErrArgument Specified icon ID is out of allowed range.

   448      */

   449     IMPORT_C void AssignIconL( TInt aIconId, CFbsBitmap* aIcon,

   450         CFbsBitmap* aMask, TBool aTransferOwnership, TScaleMode aScaleMode );

   451 

   452     /**

   453      * Assigns a color icon to the list with the specified ID. If an icon

   454      * with specified ID already exists in the list, the existing icon is

   455      * replaced with the new one. The given parameters are stored in the

   456      * tree list, and they are used in reconstructing the bitmaps on skin

   457      * change events.

   458      *

   459      * @param aIconId Icon ID assigned for the icon.

   460      *

   461      * @param aId Item ID of the icon to be added.

   462      *

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

   464      *

   465      * @param aColorIndex Index in the color table.

   466      *

   467      * @param aFilename Filename to be used to construct the item, 

   468      *      if no matching item was found in the currently active skin.

   469      *

   470      * @param aBitmapId ID of the bitmap in the file. 

   471      *      Used only if no matching item was found in the currently 

   472      *      active skin.

   473      *

   474      * @param aMaskId ID of the mask in the file.

   475      *      Used only if no matching item was found in the currently

   476      *      active skin.

   477      *

   478      * @param aDefaultColor Color RGB value to be used, if no color

   479      *      is found in the currently active skin.

   480      *

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

   482      *

   483      * @leave KErrNoMemory Not enough memory.

   484      *

   485      * @leave KErrArgument Specified icon ID is out of allowed range.

   486      */ 

   487     IMPORT_C void AssignColorIconL( TInt aIconId, const TAknsItemID& aId,

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

   489         TInt aBitmapId, TInt aMaskId, TRgb aDefaultColor,

   490         TScaleMode aScaleMode );

   491 

   492     /**

   493      * Removes the specified icon from the tree list. The specified icon cannot

   494      * be any of the default tree list icon, in which case the leaves with

   495      * value @c KErrArgument. If the specified icon is not found, the function

   496      * does nothing.

   497      *

   498      * @param aIconId Icon ID of the removed icon.

   499      *

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

   501      */

   502     IMPORT_C void RemoveIconL( TInt aIconId );

   503 

   504     /**

   505      * Returns the number of children of a hierarchical list node. This method,

   506      * along with @c Child() method, can be used for enquiring information of

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

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

   509      *

   510      * @param aNode Item ID of a node.

   511      *

   512      * @return Number of children of specified node.

   513      *

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

   515      *

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

   517      */

   518     IMPORT_C TInt ChildCount( TAknTreeItemID aNode ) const;

   519 

   520     /**

   521      * Gets the item ID of a child of a hierarcical list node. The specific

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

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

   524      *

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

   526      *

   527      * @param aIndex Index of the enquiried child.

   528      *

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

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

   531      * 

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

   533      *

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

   535      */

   536     IMPORT_C TAknTreeItemID Child( TAknTreeItemID aNode, TInt aIndex ) const;

   537 

   538     /**

   539      * Returns the item ID of the parent of a hierarchical list item. The

   540      * constant @c KAknTreeIIDRoot is returned for all the items on the

   541      * top-most level of the tree, and constant @c KaknTereIIDNone for the

   542      * items that have no parent, that is, the root node.

   543      *

   544      * @param aItem Item ID of the item, whose parent is enquiried.

   545      *

   546      * @return Item ID of the parent node.

   547      *

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

   549      */

   550     IMPORT_C TAknTreeItemID Parent( TAknTreeItemID aItem ) const;

   551 

   552     /**

   553      * Checks whether the hierarchical list contains the list item with

   554      * specified item ID. The returned value for constant @c KAknTreeIIDRoot

   555      * will always be @c ETrue, and for constant @c KAknTreeIIDNone @c EFalse.

   556      *

   557      * @param aItem Item ID.

   558      *

   559      * @return @c ETrue, if the list contains the specified item.

   560      */

   561     IMPORT_C TBool Contains( TAknTreeItemID aItem ) const;

   562 

   563     /**

   564      * Checks whether a hierarchical list item is a node.

   565      *

   566      * @param aItem Item ID of checked item.

   567      *

   568      * @return @c ETrue, if the specified item is a node.

   569      *

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

   571      */

   572     IMPORT_C TBool IsNode( TAknTreeItemID aItem ) const;

   573 

   574     /**

   575      * Checks whether a hierarchical list item is a leaf.

   576      *

   577      * @param aItem Item ID of checked item.

   578      *

   579      * @return @c ETrue, if the specified item is a leaf.

   580      *

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

   582      */

   583     IMPORT_C TBool IsLeaf( TAknTreeItemID aItem ) const;

   584 

   585     /** 

   586      * Checks whether a hierarchical list item is marked.

   587      *

   588      * @param aItem Item ID of checked item.

   589      *

   590      * @return @c ETrue for marked item.

   591      *

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

   593      */

   594     IMPORT_C TBool IsMarked( TAknTreeItemID aItem ) const;

   595 

   596     /**

   597      * Sets an item marked. If the marked item is a node, all of its

   598      * descendants are also set marked.

   599      *

   600      * Note that item marking can be changed with this method, even if the

   601      * list itself is not set markable. Marking changes can be enabled and

   602      * disabled with @c EnableMarking() method.

   603      *

   604      * @param aItem Item ID of the item to be modified.

   605      * 

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

   607      *

   608      * @param aDrawNow @c ETrue to redraw the list after the item has been

   609      *      set marked, otherwise @c EFalse.

   610      *

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

   612      */

   613     IMPORT_C void SetMarked( TAknTreeItemID aItem, TBool aMarked,

   614         TBool aDrawNow );

   615 

   616     /**

   617      * Enables or disables marking of specified list item. By default,

   618      * marking is enabled for every list item.

   619      *

   620      * When marking is enabled for an item, its marking can be changed from

   621      * unmarked to marked, and vice versa, with SetMarked() method, and for

   622      * markable list, the marking can also change as a result of user action.

   623      *

   624      * When marking is disabled, the item can still be either unmarked or

   625      * marked, but the marking cannot be changed in any way, until it has

   626      * been enabled again for the item.

   627      *

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

   629      *

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

   631      *

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

   633      */

   634     IMPORT_C void EnableMarking( TAknTreeItemID aItem, TBool aEnable );

   635 

   636     /**

   637      * Gets all the marked items from the tree list. The marked items are

   638      * appended to the end of the array passed as parameter.

   639      *

   640      * @param aMarkedItems On return, contains item IDs of all marked items.

   641      *

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

   643      */

   644     IMPORT_C void GetMarkedItemsL( RArray<TAknTreeItemID>& aMarkedItems ) const;

   645 

   646     /**

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

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

   649      *

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

   651      *      retrieved.

   652      *

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

   654      *      the specified node.

   655      *

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

   657      *

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

   659      *

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

   661      */

   662     IMPORT_C void GetMarkedItemsL( TAknTreeItemID aNode,

   663         RArray<TAknTreeItemID>& aMarkedItems ) const;

   664 

   665     /**

   666      * Checks whether the specified node is empty. To decrease memory

   667      * consumption, the descendants of tree nodes can be removed from the

   668      * hierarchical list when the node is collapsed. As the empty nodes may

   669      * have different appearances in the list view, the collapsed nodes can be

   670      * set to appear as non-empty with @c SetNonEmpty() method to indicate that

   671      * nodes will have some content when expanded.

   672      *

   673      * @param aNode Item ID of checked item.

   674      *

   675      * @return @c ETrue, if the item has been set non-empty.

   676      *

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

   678      *

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

   680      */

   681     IMPORT_C TBool IsEmpty( TAknTreeItemID aNode ) const;

   682 

   683     /**

   684      * Sets a node non-empty.

   685      *

   686      * @param aNode Item ID of the item to be modified.

   687      *

   688      * @param aNonEmpty @c ETrue to set node non-empty, @c EFalse to empty.

   689      *

   690      * @param aDrawNow @c ETrue to redraw the list after the setting has been

   691      *      change, otherwise @c EFalse.

   692      *      

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

   694      *

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

   696      */

   697     IMPORT_C void SetNonEmpty( TAknTreeItemID aNode, TBool aNonEmpty,

   698         TBool aDrawNow );

   699 

   700     /**

   701      * Checks if the specified item is set persistent. If an item is set

   702      * persistent, it is not removed from the list, when its parent or any of

   703      * its ancestors is collapsed. This means also that a node cannot be

   704      * automatically removed from the list on collapse event, if any of its

   705      * descendants is set persistent.

   706      *

   707      * @param aItem Item ID.

   708      *

   709      * @return @c ETrue, if item is set persistent.

   710      *

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

   712      */

   713     IMPORT_C TBool IsPersistent( TAknTreeItemID aItem ) const;

   714 

   715     /**

   716      * Sets an item persistent. If the specified item is a node, the state

   717      * of all its descendants is also changed accordingly.

   718      *

   719      * @param aItem Item ID.

   720      *

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

   722      *

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

   724      */

   725     IMPORT_C void SetPersistent( TAknTreeItemID aItem,

   726         TBool aPersistent );

   727 

   728     /**

   729      * Sets custom ordering for the hierarchical list and sorts the list

   730      * with the use of given ordering interface. The given interface is

   731      * used until it is replaced with some other ordering.

   732      *

   733      * Note: Ownership of the interface is not transferred to the list.

   734      *

   735      * Note: When custom ordering is set to the list, new items are added

   736      * to the end of their parent nodes, because the interface cannot

   737      * be used for determining the position for inserted item, as the

   738      * client receives its identifier only after it has been inserted.

   739      * @c Sort(TAknTreeItemID, TBool, TBool) method can be used for sorting

   740      * the node with custom ordering interface after new items have been

   741      * inserted in the list.

   742      *

   743      * @param aOrdering Custom ordering interface used in list sorting.

   744      *

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

   746      */

   747     IMPORT_C void Sort( MAknCustomTreeOrdering* aOrdering, TBool aDrawNow );

   748 

   749     /**

   750      * Sorts the specified node with the use of previously set ordering

   751      * interface. The sorting can be restricted to the specified node, or

   752      * the sorting can be set to include also every descendant node of the

   753      * specified node. Whole list can be sorted by giving the constant

   754      * @c KAknTreeIIDRoot as the @c aNode parameter. This method has no

   755      * effect, if no ordering has been set for the list.

   756      * 

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

   758      *

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

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

   761      *      sort only the child items within the specified node.

   762      *

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

   764      *

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

   766      *

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

   768      */

   769     IMPORT_C void Sort( TAknTreeItemID aNode, TBool aSortDescendants,

   770         TBool aDrawNow );

   771 

   772     /**

   773      * Adds an observer for the hierarchical list. Notifications of the list

   774      * events are sent to all observers set with this method. Observers can

   775      * be removed from the list with @c RemoveObserver() method.

   776      *

   777      * Note: Hierarchical list also sends a state changed event on every list

   778      * event through the usual control observer interface that can be set with

   779      * @c CCoeControl::SetObserver method.

   780      *

   781      * @param aObserver Implementation of the observer interface.

   782      *

   783      * @post The given interface is set as the observer of the list. The

   784      *      ownership of the interface is not transferred to the list.

   785      */

   786     IMPORT_C void AddObserverL( MAknTreeListObserver* aObserver );

   787 

   788     /**

   789      * Removes an observer from the hierarchical list.

   790      *

   791      * @param aObserver The observer interface to be removed.

   792      */

   793     IMPORT_C void RemoveObserver( MAknTreeListObserver* aObserver );

   794 

   795     /**

   796      * Notifies all of the tree list observers of the specified event. This

   797      * method is not exported, as it is intended for internal use only.

   798      *

   799      * @param aEvent The event to be notified.

   800      *

   801      * @param aItem ID of the tree item related to the event.

   802      */

   803     void NotifyObservers( MAknTreeListObserver::TEvent aEvent,

   804         TAknTreeItemID aItem );

   805 

   806     /**

   807      * Checks whether tabulator mode function indicators are enabled.

   808      *

   809      * @return @c ETrue if tabulator mode is enabled.

   810      */

   811     IMPORT_C TBool TabModeFunctionIndicators() const;

   812 

   813     /**

   814      * Changes the appearance of collapse and expand function indicators. The

   815      * appearance of default function indicators suggest that left and right

   816      * arrow keys expand and collapse the focused nodes, but when the list is

   817      * used with tabulators, those keys are used in changing tabulators.

   818      * Alternate representation for function indicator can be set by enabling

   819      * tabulator mode indicator with this method.

   820      *

   821      * @param aEnable @c ETrue to enable tabulator mode function indicators,

   822      *      @c EFalse to use the default function indicators.

   823      */

   824     IMPORT_C void EnableTabModeFunctionIndicatorsL( TBool aEnable );

   825     

   826 

   827     /**

   828      * Sets the focused item and its position on the list view. 

   829      * 

   830      * When the focused item is changed, the vertical position of the view

   831      * is changed as follows:

   832      * 

   833      * If the focused item is set on the first page, view is changed

   834      * to the beginning of the list.

   835      * 

   836      * If the focused item is not set on the first page, view is changed so 

   837      * that focused item is at the lowest line on the screen.

   838      * 

   839      * (In this context first page means actual lines from 0

   840      * to max. number of visible lines - 1)

   841      *

   842      * The horizontal position of the view is changed so that the

   843      * the beginning of the focused item is visible.

   844      *

   845      * @param aItem Item ID of the item to be focused.

   846      *

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

   848      */

   849  	IMPORT_C void SetFocusedItem( TAknTreeItemID aItem );

   850  	 	

   851  	/**

   852      * Gets the index of the focused item on the screen. Possible values are

   853      * from 0 to max. number of visible lines - 1. Value -1 is

   854      * returned if no item is focused or focused item is not visible. 

   855      *

   856      * @return index of the focused item on the screen.

   857      */

   858  	IMPORT_C TInt FocusedItemIndex() const;

   859  	

   860  	/**

   861      * Gets the index of the item on the screen. Possible values are

   862      * from 0 to max. number of visible lines - 1. Value -1 is

   863      * returned if the requested item is not visible on the screen. 

   864      *

   865      * @return index of the requested item.

   866      */

   867  	IMPORT_C TInt VisibleItemIndex( TAknTreeItemID aItem ) const;

   868 

   869  	

   870  	/**

   871      * Sets custom ordering for the hierarchical list and sorts the list

   872      * with the use of given ordering interface. The given interface is

   873      * used until it is replaced with some other ordering.

   874      *

   875      * @param aOrdering Custom ordering interface used in list sorting.

   876      *

   877      * @param aFocusBehaviour Tells how focus should be handled after sorting.

   878      *      @c ESaveFocus saves focus in the item where it was before sorting, 

   879      *      @c EMoveFocusToFirstItem changes view to the beginning of the list

   880      *      and moves focus to the first item.  

   881      *

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

   883      */

   884  	IMPORT_C void Sort( MAknCustomTreeOrdering* aOrdering, TFocusBehaviour aFocusBehaviour, TBool aDrawNow );

   885 

   886 	/**

   887      * Sorts the specified node with the use of previously set ordering

   888      * interface. The sorting can be restricted to the specified node, or

   889      * the sorting can be set to include also every descendant node of the

   890      * specified node. Whole list can be sorted by giving the constant

   891      * @c KAknTreeIIDRoot as the @c aNode parameter. This method has no

   892      * effect, if no ordering has been set for the list.

   893      *

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

   895      * 

   896      * @param aFocusBehaviour Tells how focus should be handled after sorting.

   897      *      @c ESaveFocus saves focus in the item where it was before sorting, 

   898      *      @c EMoveFocusToFirstItem changes view to the beginning of the list

   899      *      and moves focus to the first item. 

   900      *

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

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

   903      *      sort only the child items within the specified node.

   904      *

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

   906      *

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

   908      *

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

   910      */

   911    	IMPORT_C void Sort( TAknTreeItemID aNode, TFocusBehaviour aFocusBehaviour, TBool aSortDescendants, TBool aDrawNow );

   912         

   913     /**

   914      * Sets text for the empty list. This text is visible if the list box 

   915      * has no items.

   916      *

   917      * @param aText The text for the empty list.

   918      */

   919 	IMPORT_C void SetEmptyTextL(const TDesC& aText);

   920 

   921 

   922 // From base class CCoeControl

   923 

   924     /**

   925      * From CCoeControl.

   926      * Handles key events. The method will return @c EKeyWasNotConsumed, if

   927      * the list is not focused.

   928      *

   929      * @param aKeyEvent The key event.

   930      *

   931      * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or 

   932      *      @c EEventKeyDown.

   933      */

   934     TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType );

   935 

   936     /**

   937      * From CCoeControl.

   938      * Changes the visibility of the hierarchical list.

   939      *

   940      * @param aVisible @c ETrue to make the list visible, @c EFalse to make

   941      *      it invisible.

   942      */

   943     void MakeVisible( TBool aVisible );

   944 

   945     /**

   946      * From CCoeControl.

   947      * Sets whether the list is dimmed.

   948      *

   949      * @param aDimmed @c ETrue to set list dimmed, otherwise @c EFalse.

   950      */

   951     void SetDimmed( TBool aDimmed );

   952 

   953     /**

   954      * From CCoeControl.

   955      * Sets the control's containing window by copying it from aContainer.

   956      *

   957      * @param aContainer The compound control that is the container for this

   958      *      control.

   959      */

   960     void SetContainerWindowL( const CCoeControl& aContainer );

   961 

   962     /**

   963      * From CCoeControl.

   964      * Sets the control as ready to be drawn.

   965      */

   966     void ActivateL();

   967 

   968     /**

   969      * From CCoeControl.

   970      * Handles resource changes.

   971      *

   972      * @param aType

   973      */

   974     void HandleResourceChange( TInt aType );

   975 

   976     /**

   977      * From CCoeControl.

   978      * Gets the control's input capabilities.

   979      *

   980      * @return The control's input capabilities.

   981      */

   982     TCoeInputCapabilities InputCapabilities() const;

   983 

   984     /**

   985      * From CCoeControl.

   986      * Handles pointer events.

   987      *

   988      * @param aPointerEvent Pointer event.

   989      */

   990     void HandlePointerEventL( const TPointerEvent& aPointerEvent );

   991 

   992     /**

   993      * From CCoeControl.

   994      * Gets the number of controls contained in a compound control.

   995      *

   996      * @return The number of component controls contained by this control.

   997      */

   998     TInt CountComponentControls() const;

   999 

  1000     /**

  1001      * From CCoeControl.

  1002      * Gets an indexed component of a compound control.

  1003      *

  1004      * @param aIndex The index of the control.

  1005      *

  1006      * @return The component control with an index of aIndex.

  1007      */

  1008     CCoeControl* ComponentControl( TInt aIndex ) const;

  1009 

  1010 protected:

  1011 

  1012     /**

  1013      * Constructor.

  1014      */

  1015     CAknTreeList();

  1016 

  1017     /**

  1018      * Second phase constructor. Completes the construction of the base class.

  1019      * When this version of @c BaseConstructL() is used, new window is created

  1020      * for the list.

  1021      */

  1022     void BaseConstructL();

  1023 

  1024     /** 

  1025      * Second phase constructor. Completes the construction of the base class.

  1026      *

  1027      * @param aContainer Container for the list.

  1028      */

  1029     void BaseConstructL( const CCoeControl& aContainer );

  1030 

  1031     /**

  1032      * Reference to the tree structure.

  1033      *

  1034      * @return Reference to tree structure.

  1035      */

  1036     CAknTree& Tree();

  1037 

  1038     /**

  1039      * Constant reference to the tree structure.

  1040      *

  1041      * @return Constant reference to tree structure.

  1042      */

  1043     const CAknTree& Tree() const;

  1044 

  1045     /**

  1046      * Reference to the tree list view.

  1047      *

  1048      * @return Reference to tree list view.

  1049      */

  1050     CAknTreeListView& View();

  1051 

  1052     /**

  1053      * Constant reference to the tree list view.

  1054      *

  1055      * @return Constant reference to tree list view.

  1056      */

  1057     const CAknTreeListView& View() const;

  1058 

  1059 // from base class CCoeControl

  1060 

  1061     /**

  1062      * From CCoeControl.

  1063      * Handles focus change.

  1064      *

  1065      * @param aDrawNow @c EDrawNow to redraw the list.

  1066      */

  1067     void FocusChanged( TDrawNow aDrawNow );

  1068 

  1069     /**

  1070      * From CCoeControl.

  1071      * Responds to changes to the size and position of this control.

  1072      */

  1073     void SizeChanged();

  1074 

  1075     /**

  1076      * From CCoeControl.

  1077      * Responds to changes in the position of this control.

  1078      */

  1079     void PositionChanged();

  1080 

  1081     /**

  1082      * From CCoeControl.

  1083      * Retrieves an object of the same type as that encapsulated in aId.

  1084      *

  1085      * @param aId An encapsulated object type ID.

  1086      *

  1087      * @return Encapsulates the pointer to the object provided. Note that the

  1088      *      encapsulated pointer may be NULL

  1089      */

  1090     TTypeUid::Ptr MopSupplyObject( TTypeUid aId );

  1091 

  1092 private:

  1093 

  1094 // from base class CCoeControl

  1095     

  1096     /**

  1097      * From CCoeControl.

  1098      * Draws the list.

  1099      *

  1100      * @param aRect Specifies the area that needs to be redrawn.

  1101      */

  1102     void Draw( const TRect& aRect ) const;

  1103 

  1104 private: // data

  1105 

  1106     /**

  1107      * Flags.

  1108      */

  1109     TUint32 iFlags;

  1110 

  1111     /**

  1112      * Tree structure.

  1113      * Own.

  1114      */

  1115     CAknTree* iTree;

  1116 

  1117     /**

  1118      * Tree list view.

  1119      * Own.

  1120      */

  1121     CAknTreeListView* iView;

  1122 

  1123     /**

  1124      * Tree list observers.

  1125      * Not own.

  1126      */

  1127     RPointerArray<MAknTreeListObserver> iObservers;

  1128 

  1129     /**

  1130      * Index to observer array.

  1131      */

  1132     TInt iIndex;

  1133 

  1134     };