williamr@2: /* williamr@2: * Copyright (c) 2006, 2007 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@2: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: Abstract base class for hierarchical lists. williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: #ifndef C_AKNTREELIST_H williamr@2: #define C_AKNTREELIST_H williamr@2: williamr@2: williamr@4: #include williamr@2: #include williamr@2: #include williamr@4: #include // TScaleMode williamr@2: williamr@2: class CAknTree; williamr@2: class CAknTreeListView; williamr@2: class MAknCustomTreeOrdering; williamr@2: class TAknsItemID; williamr@2: williamr@2: /** Flag to indicate that hierarchical list is looping. */ williamr@2: const TUint32 KAknTreeListLooping = 0x0001; williamr@2: williamr@2: /** Flag to indicate that hierarchical list structure lines are not visible. */ williamr@2: const TUint32 KAknTreeListNoStructureLines = 0x0002; williamr@2: williamr@2: /** Flag to set marquee scrolling on. */ williamr@2: const TUint32 KAknTreeListMarqueeScrolling = 0x0004; williamr@2: williamr@2: /** Flag to disable indention of hierarchical list items. Setting this flag williamr@2: also forces the tree structure lines invisible. */ williamr@2: const TUint32 KAknTreeListNoIndention = 0x0008; williamr@2: williamr@2: /** Flag to set hierarchical list markable. The list items can always be williamr@2: marked by list client with API methods, but when list is set markable, williamr@2: it responds to specified pointer and key event by marking/unmarking williamr@2: items as required. */ williamr@2: const TUint32 KAknTreeListMarkable = 0x0010; williamr@2: williamr@2: williamr@2: /** williamr@2: * Abstract base class for hierarchical lists. williamr@2: * williamr@2: * This class functions as a base class for hierarchical lists. It contains williamr@2: * the APIs common to all hierarchical lists. The internal structure of the williamr@2: * list is not exposed directly to the list clients, instead the structure williamr@2: * can be accessed through the APIs in this class. The items in the list are williamr@2: * referred with item IDs, which are returned to the client when the items williamr@2: * are added to the list. williamr@2: * williamr@2: * List items are divided into leaves and nodes, the difference being that williamr@2: * nodes have expand and collapse functionality and can contain other tree williamr@2: * items as child items, whereas leaves cannot contain other list items. williamr@2: * Methods @c IsLeaf() and @c IsNode() can be used for checking if items williamr@2: * belong into these groups. williamr@2: * williamr@2: * The expand and collapse events, among other list events, are send to list williamr@2: * observers through @c MAknTreeListObserver interface. This enables that williamr@2: * the whole list does not have to be populated at once, as the content of williamr@2: * each node can be added when the node is expanded. To avoid unnecessary williamr@2: * memory consumption, the content of each node is removed from the list williamr@2: * when the node is collapsed. However, list items can be set persistent, williamr@2: * in which case they are not removed from nodes on collapse events. williamr@2: * williamr@2: * As the hierarchical list items are list specialisation specific, the williamr@2: * specialisations of this class have to provide APIs for constructing and williamr@2: * adding new items to the list, and getting and setting specialisation williamr@2: * specific properties of the list items. williamr@2: * williamr@2: * All the methods that might affect the appearance of the list view have an williamr@2: * additional @c aDrawNow parameter, which can be used to indicate whether williamr@2: * the list view should be redrawn to correspond to the modified list williamr@2: * structure. This allows consecutive calls to be made without the list view williamr@2: * being updated between every call by setting the @c aDrawNow parameter to williamr@2: * @c EFalse in all of the calls but the last. The normal draw methods williamr@2: * inherited from @c CCoeControl can also be used to draw the updated view. williamr@2: * williamr@2: * @see MAknTreeListObserver williamr@2: * williamr@2: * @lib aknhlist.lib williamr@2: * @since S60 v3.2 williamr@2: */ williamr@2: NONSHARABLE_CLASS( CAknTreeList ) : public CAknControl williamr@2: { williamr@2: williamr@2: public: williamr@2: williamr@2: williamr@2: // for focus handling after Sort williamr@2: enum TFocusBehaviour williamr@2: { williamr@2: ESaveFocus, williamr@2: EMoveFocusToFirstItem williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Destructor. williamr@2: */ williamr@2: virtual ~CAknTreeList(); williamr@2: williamr@2: /** williamr@2: * Sets the flags for the hierarchical list. williamr@2: * williamr@2: * Flags @c KAknTreeListLooping, @c KAknTreeListNoStructureLines, williamr@2: * @c KAknTreeListMarqueeScrolling, @c KAknTreeListNoIndention, and williamr@2: * @c KAknTreeListMarkable can be used to change the behaviour williamr@2: * of the list. williamr@2: * williamr@2: * Note: Specialisations may override this method in order to restrict the williamr@2: * use of some of the flags in specialised list or to handle specialisation williamr@2: * specific flags. williamr@2: * williamr@2: * @param aFlags Flags. williamr@2: */ williamr@2: IMPORT_C virtual void SetFlags( TUint32 aFlags ); williamr@2: williamr@2: /** williamr@2: * Returns the flags set for the list. williamr@2: * williamr@2: * @return Flags. williamr@2: */ williamr@2: IMPORT_C TUint32 Flags() const; williamr@2: williamr@2: /** williamr@2: * Moves an existing list item to specified target node. The moved item williamr@2: * and the target node have to be specified with the item IDs returned williamr@2: * when the items were added to the hierarchical list. The target node williamr@2: * cannot be a descendant of the moved node. Otherwise, the moving would williamr@2: * break the hierarchical structure. Constant @c KAknTreeIIDRoot can be williamr@2: * used as an ID for the target node when the item is to be moved to the williamr@2: * top-most level of the list. williamr@2: * williamr@2: * @param aItem Item ID of the item to be moved. williamr@2: * williamr@2: * @param aTargetNode ID of the node, where the item is to be moved. williamr@2: * williamr@2: * @param aDrawNow @c ETrue to redraw the list after the item has been williamr@2: * moved, otherwise @c EFalse. williamr@2: * williamr@2: * @leave KErrArgument The specified item is the same as the target node williamr@2: * or one of the ancestors of target node. williamr@2: * williamr@2: * @leave KErrNoMemory Not enough memory is available for adding the williamr@2: * specified item to the target node. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemType Specified target item is not a node. williamr@2: * williamr@2: * @pre The moved item and the target node exist in the list, and the williamr@2: * target node is not a descendant of the moved item. williamr@2: * williamr@2: * @post The item is moved to the specified target node and into a such williamr@2: * position that the children of the target node remain in sorted williamr@2: * order. The updated list is redrawn, if it is requested with the williamr@2: * aDrawNow parameter. williamr@2: */ williamr@2: IMPORT_C void MoveItemL( TAknTreeItemID aItem, TAknTreeItemID aTargetNode, williamr@2: TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Removes an item from the hierarchical list. The item to be removed has williamr@2: * to be specified with the ID value returned when the item was added to williamr@2: * the hierarchical list. If the removed item is a node containing other williamr@2: * list items, those items are removed from the list as well. Constant williamr@2: * @c KAknTreeIIDRoot can be used to remove every item from the list. williamr@2: * williamr@2: * @param aItem Item ID of the item to be removed. williamr@2: * williamr@2: * @param aDrawNow @c ETrue to redraw the list after the item has been williamr@2: * removed, othewise @c EFalse. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @pre The specified item exists in the hierarchical list. williamr@2: * williamr@2: * @post The specified item and all of its descendants are removed from williamr@2: * the list. The updated list is drawn, when it is requested with williamr@2: * the aDrawNow parameter. williamr@2: */ williamr@2: IMPORT_C void RemoveItem( TAknTreeItemID aItem, TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Expands a node in hierarchical list. When a node in the hierarchical williamr@2: * list is expanded, either with this method, or with pointer or key williamr@2: * event, the observer of the list is notified with respective event. williamr@2: * The client of the list can then update the content of the expanded williamr@2: * node. Constant @c KAknTreeIIDRoot can be used to expand every node williamr@2: * in the tree structure. williamr@2: * williamr@2: * @param aNode Item ID of the node to be expanded. williamr@2: * williamr@2: * @param aDrawNow @c ETrue to redraw the list after the node has been williamr@2: * expanded, otherwise @c EFalse. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemType Specified item is not a node. williamr@2: * williamr@2: * @pre The specified item exists in the hierarchical list and it is a williamr@2: * node. williamr@2: * williamr@2: * @post The specified node is expanded. The updated list is drawn, when williamr@2: * it is requested with the aDrawNow parameter. williamr@2: */ williamr@2: IMPORT_C void ExpandNode( TAknTreeItemID aNode, TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Collapses a node in hierarchical list. When a node in the hierarchical williamr@2: * list is collapsed, either with this method, or with pointer or key williamr@2: * event, all its content that is not set persistent is removed from the williamr@2: * list to reduce memory consumption. The observer of the hierarchical williamr@2: * list is nofied with the respective event. Constant @c KAknTreeIIDRoot williamr@2: * can be used to collapse every node in the tree structure. williamr@2: * williamr@2: * @param aNode Item ID of the node to be collapsed. williamr@2: * williamr@2: * @param aDrawNow @c ETrue to redraw the list after the node has been williamr@2: * collapsed, otherwise @c EFalse. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemType Specified item is not a node. williamr@2: * williamr@2: * @pre The specified item exists in the hierarchical list and it is a williamr@2: * node. williamr@2: * williamr@2: * @post The specified item is collapsed and all of its children, which are williamr@2: * not set persistent, are removed from the list. williamr@2: */ williamr@2: IMPORT_C void CollapseNode( TAknTreeItemID aNode, TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Checks whether the specified node is expanded. williamr@2: * williamr@2: * @param aNode Item ID of a node. williamr@2: * williamr@2: * @return @c ETrue if the node is expanded. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemType Specified item is not a node. williamr@2: */ williamr@2: IMPORT_C TBool IsExpanded( TAknTreeItemID aNode ) const; williamr@2: williamr@2: /** williamr@2: * Gets the item ID of the focused item. williamr@2: * williamr@2: * @return Item ID of the focused item. Value @c KAknTreeIIDNone is williamr@2: * returned if no item is focused. williamr@2: */ williamr@2: IMPORT_C TAknTreeItemID FocusedItem() const; williamr@2: williamr@2: /** williamr@2: * Sets the focused item and its position on the list view. When the williamr@2: * focused item is changed, the vertical position of the view is changed williamr@2: * so that the position of the focused item on the view matches the given williamr@2: * index. The horizontal position of the view is changed so that the williamr@2: * the beginning of the focused item is visible. williamr@2: * williamr@2: * @param aItem Item ID of the item to be focused. williamr@2: * williamr@2: * @param aIndex The position of the focused item on the list view. If the williamr@2: * index does not refer to any visible view location, that is, the williamr@2: * index is less than zero or greater than or equal to the number of williamr@2: * items in the view, the focused item is changed to specified item, williamr@2: * but the position of the view is not changed. williamr@2: * williamr@2: * @param aDrawNow @c ETrue to redraw the list after the focused item williamr@2: * has been changed, otherwise @c EFalse. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: */ williamr@2: IMPORT_C void SetFocusedItem( TAknTreeItemID aItem, TInt aIndex, williamr@2: TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Highlight rectangle for the focused item. The returned rectangle is williamr@2: * screen relative and it can be used, for example, when positioning williamr@2: * pop-up for focused item. If the focused item is not visible, the williamr@2: * method returns an empty rectangle. williamr@2: * williamr@2: * @return Highlight rectangle of focused list item. williamr@2: */ williamr@2: IMPORT_C TRect HighlightRect() const; williamr@2: williamr@2: /** williamr@2: * Adds a new icon to the list to be used by all list items. The same williamr@2: * icon can be used by multiple tree items and its referenced by the williamr@2: * ID returned by this function. The given parameters are also stored williamr@2: * in the tree list, which enables the tree list to reconstruct the williamr@2: * bitmaps on skin change events. If this behaviour is insufficient for williamr@2: * the client, it can always replace the existing icons by itself with williamr@2: * @c AssignIconL or @c AssignColorIconL method. williamr@2: * williamr@2: * @param aId Item ID of the icon to be added. williamr@2: * williamr@2: * @param aFilename Filename to be used to construct the item, williamr@2: * if no matching item was found in the currently active skin. williamr@2: * williamr@2: * @param aBitmapId ID of the bitmap in the file. williamr@2: * Used only if no matching item was found in the currently williamr@2: * active skin. williamr@2: * williamr@2: * @param aMaskId ID of the mask in the file. williamr@2: * Used only if no matching item was found in the currently williamr@2: * active skin. williamr@2: * williamr@2: * @param aScaleMode Scale mode used when icon's bitmap is resized. williamr@2: * williamr@2: * @return ID assigned for the added icon. williamr@2: * williamr@2: * @leave KErrNoMemory Not enough memory. williamr@2: */ williamr@2: IMPORT_C TInt AddIconL( const TAknsItemID& aId, const TDesC& aFilename, williamr@2: TInt aBitmapId, TInt aMaskId, TScaleMode aScaleMode ); williamr@2: williamr@2: /** williamr@2: * Adds a new icon to the list. The ownership of given bitmaps is williamr@2: * transferred to the list only if specified with @c aTransferOwnership williamr@2: * parameter. Note that icons added to the list with this method cannot williamr@2: * be reconstructed on skin change events by the list. If necessary, williamr@2: * previously added icons can be replaced with @c AssignIconL method. williamr@2: * williamr@2: * @param aIcon Pointer to the bitmap. williamr@2: * williamr@2: * @param aMask Pointer to the mask bitmap. williamr@2: * williamr@2: * @param aTransferOwnership @c ETrue, if ownership of bitmaps is williamr@2: * transferred to the list. If the method leaves, it is always on the williamr@2: * responsibility of the client code to take care of deleting the bitmaps. williamr@2: * williamr@2: * @param aScaleMode The scale mode used when the icon is resized. williamr@2: * williamr@2: * @return ID assigned for the added icon. williamr@2: * williamr@2: * @leave KErrNoMemory Not enough memory. williamr@2: */ williamr@2: IMPORT_C TInt AddIconL( CFbsBitmap* aIcon, CFbsBitmap* aMask, williamr@2: TBool aTransferOwnership, TScaleMode aScaleMode ); williamr@2: williamr@2: /** williamr@2: * Adds a new icon to the list to be used by all list items. The same williamr@2: * icon can be used by multiple tree items and it is referenced by the williamr@2: * icon ID returned by this function. The given parameters are stored williamr@2: * in the tree list, and they are used in reconstructing the bitmaps on williamr@2: * skin change events. williamr@2: * williamr@2: * @param aId Item ID of the icon to be added. williamr@2: * williamr@2: * @param aColorId Item ID of the color table. williamr@2: * williamr@2: * @param aColorIndex Index in the color table. williamr@2: * williamr@2: * @param aFilename Filename to be used to construct the item, williamr@2: * if no matching item was found in the currently active skin. williamr@2: * williamr@2: * @param aBitmapId ID of the bitmap in the file. williamr@2: * Used only if no matching item was found in the currently williamr@2: * active skin. williamr@2: * williamr@2: * @param aMaskId ID of the mask in the file. williamr@2: * Used only if no matching item was found in the currently williamr@2: * active skin. williamr@2: * williamr@2: * @param aDefaultColor Color RGB value to be used, if no color williamr@2: * is found in the currently active skin. williamr@2: * williamr@2: * @param aScaleMode Scale mode used when icon's bitmap is resized. williamr@2: * williamr@2: * @return ID assigned for the added icon. williamr@2: * williamr@2: * @leave KErrNoMemory Not enough memory. williamr@2: */ williamr@2: IMPORT_C TInt AddColorIconL( const TAknsItemID& aId, williamr@2: const TAknsItemID& aColorId, TInt aColorIndex, const TDesC& aFilename, williamr@2: TInt aBitmapId, TInt aMaskId, TRgb aDefaultColor, williamr@2: TScaleMode aScaleMode ); williamr@2: williamr@2: /** williamr@2: * Assigns an icon to the tree list with the specified ID. If an icon williamr@2: * with specified ID already exists in the list, the existing icon is williamr@2: * replaced with the new one. The given parameters are stored in the williamr@2: * tree list, and they are used in reconstructing the bitmaps on skin williamr@2: * change events. williamr@2: * williamr@2: * @param aIconId Icon ID assigned for the icon. williamr@2: * williamr@2: * @param aId Item ID of the icon to be added. williamr@2: * williamr@2: * @param aFilename Filename to be used to construct the item, williamr@2: * if no matching item was found in the currently active skin. williamr@2: * williamr@2: * @param aBitmapId ID of the bitmap in the file. williamr@2: * Used only if no matching item was found in the currently williamr@2: * active skin. williamr@2: * williamr@2: * @param aMaskId ID of the mask in the file. williamr@2: * Used only if no matching item was found in the currently williamr@2: * active skin. williamr@2: * williamr@2: * @param aScaleMode Scale mode used when icon's bitmap is resized. williamr@2: * williamr@2: * @leave KErrNoMemory Not enough memory. williamr@2: * williamr@2: * @leave KErrArgument Specified icon ID is out of allowed range. williamr@2: */ williamr@2: IMPORT_C void AssignIconL( TInt aIconId, const TAknsItemID& aId, williamr@2: const TDesC& aFilename, TInt aBitmapId, TInt aMaskId, williamr@2: TScaleMode aScaleMode ); williamr@2: williamr@2: /** williamr@2: * Assigns an icon to the tree list with the specified ID. If an icon williamr@2: * with specified ID already exists in the list, the existing icon is williamr@2: * replaced with the new one. The ownership of bitmaps is transferred to williamr@2: * the list only if so specifed with @c aTransferOnwership parameter. williamr@2: * Note that icons added with this method cannot be reconstructed on williamr@2: * skin change events by list. williamr@2: * williamr@2: * @param aIconId Icon ID assigned for the icon. williamr@2: * williamr@2: * @param aIcon Pointer to the bitmap. williamr@2: * williamr@2: * @param aMask Pointer to the mask bitmap. williamr@2: * williamr@2: * @param aTransferOwnership @c ETrue, if ownership of bitmaps is williamr@2: * transferred to the list. If the method leaves, it is always on williamr@2: * the responsibility of the client code to take care of deleting williamr@2: * the bitmaps. williamr@2: * williamr@2: * @param aScaleMode Scale mode used when icon's bitmap is resized. williamr@2: * williamr@2: * @leave KErrNoMemory Not enough memory. williamr@2: * williamr@2: * @leave KErrArgument Specified icon ID is out of allowed range. williamr@2: */ williamr@2: IMPORT_C void AssignIconL( TInt aIconId, CFbsBitmap* aIcon, williamr@2: CFbsBitmap* aMask, TBool aTransferOwnership, TScaleMode aScaleMode ); williamr@2: williamr@2: /** williamr@2: * Assigns a color icon to the list with the specified ID. If an icon williamr@2: * with specified ID already exists in the list, the existing icon is williamr@2: * replaced with the new one. The given parameters are stored in the williamr@2: * tree list, and they are used in reconstructing the bitmaps on skin williamr@2: * change events. williamr@2: * williamr@2: * @param aIconId Icon ID assigned for the icon. williamr@2: * williamr@2: * @param aId Item ID of the icon to be added. williamr@2: * williamr@2: * @param aColorId Item ID of the color table. williamr@2: * williamr@2: * @param aColorIndex Index in the color table. williamr@2: * williamr@2: * @param aFilename Filename to be used to construct the item, williamr@2: * if no matching item was found in the currently active skin. williamr@2: * williamr@2: * @param aBitmapId ID of the bitmap in the file. williamr@2: * Used only if no matching item was found in the currently williamr@2: * active skin. williamr@2: * williamr@2: * @param aMaskId ID of the mask in the file. williamr@2: * Used only if no matching item was found in the currently williamr@2: * active skin. williamr@2: * williamr@2: * @param aDefaultColor Color RGB value to be used, if no color williamr@2: * is found in the currently active skin. williamr@2: * williamr@2: * @param aScaleMode Scale mode used when icon's bitmap is resized. williamr@2: * williamr@2: * @leave KErrNoMemory Not enough memory. williamr@2: * williamr@2: * @leave KErrArgument Specified icon ID is out of allowed range. williamr@2: */ williamr@2: IMPORT_C void AssignColorIconL( TInt aIconId, const TAknsItemID& aId, williamr@2: const TAknsItemID& aColorId, TInt aColorIndex, const TDesC& aFilename, williamr@2: TInt aBitmapId, TInt aMaskId, TRgb aDefaultColor, williamr@2: TScaleMode aScaleMode ); williamr@2: williamr@2: /** williamr@2: * Removes the specified icon from the tree list. The specified icon cannot williamr@2: * be any of the default tree list icon, in which case the leaves with williamr@2: * value @c KErrArgument. If the specified icon is not found, the function williamr@2: * does nothing. williamr@2: * williamr@2: * @param aIconId Icon ID of the removed icon. williamr@2: * williamr@2: * @leave KErrArgument if specified icon is one of the default icons. williamr@2: */ williamr@2: IMPORT_C void RemoveIconL( TInt aIconId ); williamr@2: williamr@2: /** williamr@2: * Returns the number of children of a hierarchical list node. This method, williamr@2: * along with @c Child() method, can be used for enquiring information of williamr@2: * the list structure. Constant @c KAknTreeIIDRoot can be used to get the williamr@2: * item count on the top-most level of the list. williamr@2: * williamr@2: * @param aNode Item ID of a node. williamr@2: * williamr@2: * @return Number of children of specified node. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemType Specified item is not a node. williamr@2: */ williamr@2: IMPORT_C TInt ChildCount( TAknTreeItemID aNode ) const; williamr@2: williamr@2: /** williamr@2: * Gets the item ID of a child of a hierarcical list node. The specific williamr@2: * child is specified with an index. The child count for any hierarchical williamr@2: * list node can be get with @c ChildCount() method. williamr@2: * williamr@2: * @param aNode Item ID of the node, whose child is enquiried. williamr@2: * williamr@2: * @param aIndex Index of the enquiried child. williamr@2: * williamr@2: * @return Item ID of the specified child. Value @c KAknTreeIIDNone is williamr@2: * returned, if the child with specified index does not exist. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemType Specified item is not a node. williamr@2: */ williamr@2: IMPORT_C TAknTreeItemID Child( TAknTreeItemID aNode, TInt aIndex ) const; williamr@2: williamr@2: /** williamr@2: * Returns the item ID of the parent of a hierarchical list item. The williamr@2: * constant @c KAknTreeIIDRoot is returned for all the items on the williamr@2: * top-most level of the tree, and constant @c KaknTereIIDNone for the williamr@2: * items that have no parent, that is, the root node. williamr@2: * williamr@2: * @param aItem Item ID of the item, whose parent is enquiried. williamr@2: * williamr@2: * @return Item ID of the parent node. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: */ williamr@2: IMPORT_C TAknTreeItemID Parent( TAknTreeItemID aItem ) const; williamr@2: williamr@2: /** williamr@2: * Checks whether the hierarchical list contains the list item with williamr@2: * specified item ID. The returned value for constant @c KAknTreeIIDRoot williamr@2: * will always be @c ETrue, and for constant @c KAknTreeIIDNone @c EFalse. williamr@2: * williamr@2: * @param aItem Item ID. williamr@2: * williamr@2: * @return @c ETrue, if the list contains the specified item. williamr@2: */ williamr@2: IMPORT_C TBool Contains( TAknTreeItemID aItem ) const; williamr@2: williamr@2: /** williamr@2: * Checks whether a hierarchical list item is a node. williamr@2: * williamr@2: * @param aItem Item ID of checked item. williamr@2: * williamr@2: * @return @c ETrue, if the specified item is a node. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: */ williamr@2: IMPORT_C TBool IsNode( TAknTreeItemID aItem ) const; williamr@2: williamr@2: /** williamr@2: * Checks whether a hierarchical list item is a leaf. williamr@2: * williamr@2: * @param aItem Item ID of checked item. williamr@2: * williamr@2: * @return @c ETrue, if the specified item is a leaf. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: */ williamr@2: IMPORT_C TBool IsLeaf( TAknTreeItemID aItem ) const; williamr@2: williamr@2: /** williamr@2: * Checks whether a hierarchical list item is marked. williamr@2: * williamr@2: * @param aItem Item ID of checked item. williamr@2: * williamr@2: * @return @c ETrue for marked item. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: */ williamr@2: IMPORT_C TBool IsMarked( TAknTreeItemID aItem ) const; williamr@2: williamr@2: /** williamr@2: * Sets an item marked. If the marked item is a node, all of its williamr@2: * descendants are also set marked. williamr@2: * williamr@2: * Note that item marking can be changed with this method, even if the williamr@2: * list itself is not set markable. Marking changes can be enabled and williamr@2: * disabled with @c EnableMarking() method. williamr@2: * williamr@2: * @param aItem Item ID of the item to be modified. williamr@2: * williamr@2: * @param aMarked @c ETrue to set item marked, @c EFalse to unmarked. williamr@2: * williamr@2: * @param aDrawNow @c ETrue to redraw the list after the item has been williamr@2: * set marked, otherwise @c EFalse. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: */ williamr@2: IMPORT_C void SetMarked( TAknTreeItemID aItem, TBool aMarked, williamr@2: TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Enables or disables marking of specified list item. By default, williamr@2: * marking is enabled for every list item. williamr@2: * williamr@2: * When marking is enabled for an item, its marking can be changed from williamr@2: * unmarked to marked, and vice versa, with SetMarked() method, and for williamr@2: * markable list, the marking can also change as a result of user action. williamr@2: * williamr@2: * When marking is disabled, the item can still be either unmarked or williamr@2: * marked, but the marking cannot be changed in any way, until it has williamr@2: * been enabled again for the item. williamr@2: * williamr@2: * @param aItem Item ID of the list item. williamr@2: * williamr@2: * @param aEnable @c ETrue to enable marking, @c EFalse to disable it. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: */ williamr@2: IMPORT_C void EnableMarking( TAknTreeItemID aItem, TBool aEnable ); williamr@2: williamr@2: /** williamr@2: * Gets all the marked items from the tree list. The marked items are williamr@2: * appended to the end of the array passed as parameter. williamr@2: * williamr@2: * @param aMarkedItems On return, contains item IDs of all marked items. williamr@2: * williamr@2: * @leave KErrNoMemory Appending item to the array fails. williamr@2: */ williamr@2: IMPORT_C void GetMarkedItemsL( RArray& aMarkedItems ) const; williamr@2: williamr@2: /** williamr@2: * Gets all the marked items from the specified node. The marked items williamr@2: * are appended to the end of the array passed as parameter. williamr@2: * williamr@2: * @param aNode Item ID of a node from where the marked items are williamr@2: * retrieved. williamr@2: * williamr@2: * @param aMarkedItems On return, contains item IDs of marked items in williamr@2: * the specified node. williamr@2: * williamr@2: * @leave KErrNoMemory Appending item to the array fails. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemType Specified item is not a node. williamr@2: */ williamr@2: IMPORT_C void GetMarkedItemsL( TAknTreeItemID aNode, williamr@2: RArray& aMarkedItems ) const; williamr@2: williamr@2: /** williamr@2: * Checks whether the specified node is empty. To decrease memory williamr@2: * consumption, the descendants of tree nodes can be removed from the williamr@2: * hierarchical list when the node is collapsed. As the empty nodes may williamr@2: * have different appearances in the list view, the collapsed nodes can be williamr@2: * set to appear as non-empty with @c SetNonEmpty() method to indicate that williamr@2: * nodes will have some content when expanded. williamr@2: * williamr@2: * @param aNode Item ID of checked item. williamr@2: * williamr@2: * @return @c ETrue, if the item has been set non-empty. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemType Specified target item is not a node. williamr@2: */ williamr@2: IMPORT_C TBool IsEmpty( TAknTreeItemID aNode ) const; williamr@2: williamr@2: /** williamr@2: * Sets a node non-empty. williamr@2: * williamr@2: * @param aNode Item ID of the item to be modified. williamr@2: * williamr@2: * @param aNonEmpty @c ETrue to set node non-empty, @c EFalse to empty. williamr@2: * williamr@2: * @param aDrawNow @c ETrue to redraw the list after the setting has been williamr@2: * change, otherwise @c EFalse. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemType Specified target item is not a node. williamr@2: */ williamr@2: IMPORT_C void SetNonEmpty( TAknTreeItemID aNode, TBool aNonEmpty, williamr@2: TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Checks if the specified item is set persistent. If an item is set williamr@2: * persistent, it is not removed from the list, when its parent or any of williamr@2: * its ancestors is collapsed. This means also that a node cannot be williamr@2: * automatically removed from the list on collapse event, if any of its williamr@2: * descendants is set persistent. williamr@2: * williamr@2: * @param aItem Item ID. williamr@2: * williamr@2: * @return @c ETrue, if item is set persistent. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: */ williamr@2: IMPORT_C TBool IsPersistent( TAknTreeItemID aItem ) const; williamr@2: williamr@2: /** williamr@2: * Sets an item persistent. If the specified item is a node, the state williamr@2: * of all its descendants is also changed accordingly. williamr@2: * williamr@2: * @param aItem Item ID. williamr@2: * williamr@2: * @param aPersistent @c ETrue to set item persistent. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: */ williamr@2: IMPORT_C void SetPersistent( TAknTreeItemID aItem, williamr@2: TBool aPersistent ); williamr@2: williamr@2: /** williamr@2: * Sets custom ordering for the hierarchical list and sorts the list williamr@2: * with the use of given ordering interface. The given interface is williamr@2: * used until it is replaced with some other ordering. williamr@2: * williamr@2: * Note: Ownership of the interface is not transferred to the list. williamr@2: * williamr@2: * Note: When custom ordering is set to the list, new items are added williamr@2: * to the end of their parent nodes, because the interface cannot williamr@2: * be used for determining the position for inserted item, as the williamr@2: * client receives its identifier only after it has been inserted. williamr@2: * @c Sort(TAknTreeItemID, TBool, TBool) method can be used for sorting williamr@2: * the node with custom ordering interface after new items have been williamr@2: * inserted in the list. williamr@2: * williamr@2: * @param aOrdering Custom ordering interface used in list sorting. williamr@2: * williamr@2: * @param aDrawNow @c ETrue to redraw the list after sorting. williamr@2: */ williamr@2: IMPORT_C void Sort( MAknCustomTreeOrdering* aOrdering, TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Sorts the specified node with the use of previously set ordering williamr@2: * interface. The sorting can be restricted to the specified node, or williamr@2: * the sorting can be set to include also every descendant node of the williamr@2: * specified node. Whole list can be sorted by giving the constant williamr@2: * @c KAknTreeIIDRoot as the @c aNode parameter. This method has no williamr@2: * effect, if no ordering has been set for the list. williamr@2: * williamr@2: * @param aNode Item ID of the node that has to be sorted. williamr@2: * williamr@2: * @param aSortDescendants @c ETrue to sort the content of the specified williamr@2: * node including the content of its descendant nodes, @c EFalse to williamr@2: * sort only the child items within the specified node. williamr@2: * williamr@2: * @param aDrawNow @c ETrue to redraw the list after sorting. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemType Specified item is not a node. williamr@2: */ williamr@2: IMPORT_C void Sort( TAknTreeItemID aNode, TBool aSortDescendants, williamr@2: TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Adds an observer for the hierarchical list. Notifications of the list williamr@2: * events are sent to all observers set with this method. Observers can williamr@2: * be removed from the list with @c RemoveObserver() method. williamr@2: * williamr@2: * Note: Hierarchical list also sends a state changed event on every list williamr@2: * event through the usual control observer interface that can be set with williamr@2: * @c CCoeControl::SetObserver method. williamr@2: * williamr@2: * @param aObserver Implementation of the observer interface. williamr@2: * williamr@2: * @post The given interface is set as the observer of the list. The williamr@2: * ownership of the interface is not transferred to the list. williamr@2: */ williamr@2: IMPORT_C void AddObserverL( MAknTreeListObserver* aObserver ); williamr@2: williamr@2: /** williamr@2: * Removes an observer from the hierarchical list. williamr@2: * williamr@2: * @param aObserver The observer interface to be removed. williamr@2: */ williamr@2: IMPORT_C void RemoveObserver( MAknTreeListObserver* aObserver ); williamr@2: williamr@2: /** williamr@2: * Notifies all of the tree list observers of the specified event. This williamr@2: * method is not exported, as it is intended for internal use only. williamr@2: * williamr@2: * @param aEvent The event to be notified. williamr@2: * williamr@2: * @param aItem ID of the tree item related to the event. williamr@2: */ williamr@2: void NotifyObservers( MAknTreeListObserver::TEvent aEvent, williamr@2: TAknTreeItemID aItem ); williamr@2: williamr@2: /** williamr@2: * Checks whether tabulator mode function indicators are enabled. williamr@2: * williamr@2: * @return @c ETrue if tabulator mode is enabled. williamr@2: */ williamr@2: IMPORT_C TBool TabModeFunctionIndicators() const; williamr@2: williamr@2: /** williamr@2: * Changes the appearance of collapse and expand function indicators. The williamr@2: * appearance of default function indicators suggest that left and right williamr@2: * arrow keys expand and collapse the focused nodes, but when the list is williamr@2: * used with tabulators, those keys are used in changing tabulators. williamr@2: * Alternate representation for function indicator can be set by enabling williamr@2: * tabulator mode indicator with this method. williamr@2: * williamr@2: * @param aEnable @c ETrue to enable tabulator mode function indicators, williamr@2: * @c EFalse to use the default function indicators. williamr@2: */ williamr@2: IMPORT_C void EnableTabModeFunctionIndicatorsL( TBool aEnable ); williamr@2: williamr@2: williamr@2: /** williamr@2: * Sets the focused item and its position on the list view. williamr@2: * williamr@2: * When the focused item is changed, the vertical position of the view williamr@2: * is changed as follows: williamr@2: * williamr@2: * If the focused item is set on the first page, view is changed williamr@2: * to the beginning of the list. williamr@2: * williamr@2: * If the focused item is not set on the first page, view is changed so williamr@2: * that focused item is at the lowest line on the screen. williamr@2: * williamr@2: * (In this context first page means actual lines from 0 williamr@2: * to max. number of visible lines - 1) williamr@2: * williamr@2: * The horizontal position of the view is changed so that the williamr@2: * the beginning of the focused item is visible. williamr@2: * williamr@2: * @param aItem Item ID of the item to be focused. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: */ williamr@2: IMPORT_C void SetFocusedItem( TAknTreeItemID aItem ); williamr@2: williamr@2: /** williamr@2: * Gets the index of the focused item on the screen. Possible values are williamr@2: * from 0 to max. number of visible lines - 1. Value -1 is williamr@2: * returned if no item is focused or focused item is not visible. williamr@2: * williamr@2: * @return index of the focused item on the screen. williamr@2: */ williamr@2: IMPORT_C TInt FocusedItemIndex() const; williamr@2: williamr@2: /** williamr@2: * Gets the index of the item on the screen. Possible values are williamr@2: * from 0 to max. number of visible lines - 1. Value -1 is williamr@2: * returned if the requested item is not visible on the screen. williamr@2: * williamr@2: * @return index of the requested item. williamr@2: */ williamr@2: IMPORT_C TInt VisibleItemIndex( TAknTreeItemID aItem ) const; williamr@2: williamr@2: williamr@2: /** williamr@2: * Sets custom ordering for the hierarchical list and sorts the list williamr@2: * with the use of given ordering interface. The given interface is williamr@2: * used until it is replaced with some other ordering. williamr@2: * williamr@2: * @param aOrdering Custom ordering interface used in list sorting. williamr@2: * williamr@2: * @param aFocusBehaviour Tells how focus should be handled after sorting. williamr@2: * @c ESaveFocus saves focus in the item where it was before sorting, williamr@2: * @c EMoveFocusToFirstItem changes view to the beginning of the list williamr@2: * and moves focus to the first item. williamr@2: * williamr@2: * @param aDrawNow @c ETrue to redraw the list after sorting. williamr@2: */ williamr@2: IMPORT_C void Sort( MAknCustomTreeOrdering* aOrdering, TFocusBehaviour aFocusBehaviour, TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Sorts the specified node with the use of previously set ordering williamr@2: * interface. The sorting can be restricted to the specified node, or williamr@2: * the sorting can be set to include also every descendant node of the williamr@2: * specified node. Whole list can be sorted by giving the constant williamr@2: * @c KAknTreeIIDRoot as the @c aNode parameter. This method has no williamr@2: * effect, if no ordering has been set for the list. williamr@2: * williamr@2: * @param aNode Item ID of the node that has to be sorted. williamr@2: * williamr@2: * @param aFocusBehaviour Tells how focus should be handled after sorting. williamr@2: * @c ESaveFocus saves focus in the item where it was before sorting, williamr@2: * @c EMoveFocusToFirstItem changes view to the beginning of the list williamr@2: * and moves focus to the first item. williamr@2: * williamr@2: * @param aSortDescendants @c ETrue to sort the content of the specified williamr@2: * node including the content of its descendant nodes, @c EFalse to williamr@2: * sort only the child items within the specified node. williamr@2: * williamr@2: * @param aDrawNow @c ETrue to redraw the list after sorting. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. williamr@2: * williamr@2: * @panic EAknHListPanicInvalidItemType Specified item is not a node. williamr@2: */ williamr@2: IMPORT_C void Sort( TAknTreeItemID aNode, TFocusBehaviour aFocusBehaviour, TBool aSortDescendants, TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Sets text for the empty list. This text is visible if the list box williamr@2: * has no items. williamr@2: * williamr@2: * @param aText The text for the empty list. williamr@2: */ williamr@2: IMPORT_C void SetEmptyTextL(const TDesC& aText); williamr@2: williamr@2: williamr@2: // From base class CCoeControl williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Handles key events. The method will return @c EKeyWasNotConsumed, if williamr@2: * the list is not focused. williamr@2: * williamr@2: * @param aKeyEvent The key event. williamr@2: * williamr@2: * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or williamr@2: * @c EEventKeyDown. williamr@2: */ williamr@2: TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType ); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Changes the visibility of the hierarchical list. williamr@2: * williamr@2: * @param aVisible @c ETrue to make the list visible, @c EFalse to make williamr@2: * it invisible. williamr@2: */ williamr@2: void MakeVisible( TBool aVisible ); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Sets whether the list is dimmed. williamr@2: * williamr@2: * @param aDimmed @c ETrue to set list dimmed, otherwise @c EFalse. williamr@2: */ williamr@2: void SetDimmed( TBool aDimmed ); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Sets the control's containing window by copying it from aContainer. williamr@2: * williamr@2: * @param aContainer The compound control that is the container for this williamr@2: * control. williamr@2: */ williamr@2: void SetContainerWindowL( const CCoeControl& aContainer ); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Sets the control as ready to be drawn. williamr@2: */ williamr@2: void ActivateL(); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Handles resource changes. williamr@2: * williamr@2: * @param aType williamr@2: */ williamr@2: void HandleResourceChange( TInt aType ); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Gets the control's input capabilities. williamr@2: * williamr@2: * @return The control's input capabilities. williamr@2: */ williamr@2: TCoeInputCapabilities InputCapabilities() const; williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Handles pointer events. williamr@2: * williamr@2: * @param aPointerEvent Pointer event. williamr@2: */ williamr@2: void HandlePointerEventL( const TPointerEvent& aPointerEvent ); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Gets the number of controls contained in a compound control. williamr@2: * williamr@2: * @return The number of component controls contained by this control. williamr@2: */ williamr@2: TInt CountComponentControls() const; williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Gets an indexed component of a compound control. williamr@2: * williamr@2: * @param aIndex The index of the control. williamr@2: * williamr@2: * @return The component control with an index of aIndex. williamr@2: */ williamr@2: CCoeControl* ComponentControl( TInt aIndex ) const; williamr@2: williamr@2: protected: williamr@2: williamr@2: /** williamr@2: * Constructor. williamr@2: */ williamr@2: CAknTreeList(); williamr@2: williamr@2: /** williamr@2: * Second phase constructor. Completes the construction of the base class. williamr@2: * When this version of @c BaseConstructL() is used, new window is created williamr@2: * for the list. williamr@2: */ williamr@2: void BaseConstructL(); williamr@2: williamr@2: /** williamr@2: * Second phase constructor. Completes the construction of the base class. williamr@2: * williamr@2: * @param aContainer Container for the list. williamr@2: */ williamr@2: void BaseConstructL( const CCoeControl& aContainer ); williamr@2: williamr@2: /** williamr@2: * Reference to the tree structure. williamr@2: * williamr@2: * @return Reference to tree structure. williamr@2: */ williamr@2: CAknTree& Tree(); williamr@2: williamr@2: /** williamr@2: * Constant reference to the tree structure. williamr@2: * williamr@2: * @return Constant reference to tree structure. williamr@2: */ williamr@2: const CAknTree& Tree() const; williamr@2: williamr@2: /** williamr@2: * Reference to the tree list view. williamr@2: * williamr@2: * @return Reference to tree list view. williamr@2: */ williamr@2: CAknTreeListView& View(); williamr@2: williamr@2: /** williamr@2: * Constant reference to the tree list view. williamr@2: * williamr@2: * @return Constant reference to tree list view. williamr@2: */ williamr@2: const CAknTreeListView& View() const; williamr@2: williamr@2: // from base class CCoeControl williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Handles focus change. williamr@2: * williamr@2: * @param aDrawNow @c EDrawNow to redraw the list. williamr@2: */ williamr@2: void FocusChanged( TDrawNow aDrawNow ); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Responds to changes to the size and position of this control. williamr@2: */ williamr@2: void SizeChanged(); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Responds to changes in the position of this control. williamr@2: */ williamr@2: void PositionChanged(); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Retrieves an object of the same type as that encapsulated in aId. williamr@2: * williamr@2: * @param aId An encapsulated object type ID. williamr@2: * williamr@2: * @return Encapsulates the pointer to the object provided. Note that the williamr@2: * encapsulated pointer may be NULL williamr@2: */ williamr@2: TTypeUid::Ptr MopSupplyObject( TTypeUid aId ); williamr@2: williamr@2: private: williamr@2: williamr@2: // from base class CCoeControl williamr@2: williamr@2: /** williamr@2: * From CCoeControl. williamr@2: * Draws the list. williamr@2: * williamr@2: * @param aRect Specifies the area that needs to be redrawn. williamr@2: */ williamr@2: void Draw( const TRect& aRect ) const; williamr@2: williamr@2: private: // data williamr@2: williamr@2: /** williamr@2: * Flags. williamr@2: */ williamr@2: TUint32 iFlags; williamr@2: williamr@2: /** williamr@2: * Tree structure. williamr@2: * Own. williamr@2: */ williamr@2: CAknTree* iTree; williamr@2: williamr@2: /** williamr@2: * Tree list view. williamr@2: * Own. williamr@2: */ williamr@2: CAknTreeListView* iView; williamr@2: williamr@2: /** williamr@2: * Tree list observers. williamr@2: * Not own. williamr@2: */ williamr@2: RPointerArray iObservers; williamr@2: williamr@2: /** williamr@2: * Index to observer array. williamr@2: */ williamr@2: TInt iIndex; williamr@2: williamr@2: }; williamr@2: williamr@2: williamr@2: #endif // C_AKNTREELIST_H