diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/aknsinglestyletreelist.h --- a/epoc32/include/mw/aknsinglestyletreelist.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mw/aknsinglestyletreelist.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,350 @@ -aknsinglestyletreelist.h +/* +* Copyright (c) 2006, 2007 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +* which accompanies this distribution, and is available +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Single style hierarchical list. +* +*/ + + +#ifndef C_AKNSINGLESTYLETREELIST_H +#define C_AKNSINGLESTYLETREELIST_H + + +#include + + +/** + * Single style hierarchical list. + * + * Single style hierarchical list is a hierarchical list specialisation for + * a list type with simple list items, which contain only a folder or file + * icon, single line of text and some optional icons. This class provides + * only the specialisation specific APIs for the list usage. The common + * hierarchical list APIs are located in its base class. + * + * Here is an example of how an instance of window-owning single style + * hierarchical list can be constructed: + * + * @code + * // Construct the list, set its size, and make it visible. + * CAknSingleStyleTreeList* list = CAknSingleStyleTreeList::NewL(); + * list->SetRect( rect ); + * list->MakeVisible( ETrue ); + * @endcode + * + * Adding items to the constructed list: + * + * @code + * // Add a node to the top-most level of the tree. + * _LIT( KNodeText, "Node" ); + * TUint32 flags = CAknSingleStyleTreeList::EPersistent; + * TAknTreeItemID node = list->AddNodeL( KAknTreeIIDRoot, KNodeText, + * flags, EFalse ); + * + * // Add a leaf to the previously added node. + * _LIT( KLeafText, "Leaf" ); + * TAknTreeItemID leaf = list->AddLeafL( node, KLeafText, flags, EFalse ); + * @endcode + * + * Changing icons for the list items: + * + * @code + * // Add icon to the list and set it to existing list item. + * TInt iconId = list->AddIconL( KAknsIIDQgnPropBtCarkit, + * AknIconUtils::AvkonIconFileName(), EMbmAvkonQgn_prop_bt_carkit, + * EMbmAvkonQgn_prop_bt_carkit_mask, EAspectRatioPreserved ); + * list->SetIcon( leaf, CAknSingleStyleTreeList::ELeaf, iconId, ETrue ); + * @endcode + * + * @see CAknTreeList + * + * @lib aknhlist.lib + * @since S60 v3.2 + */ +NONSHARABLE_CLASS( CAknSingleStyleTreeList ) : public CAknTreeList + { + +public: + + /** Icon types usable with single style hierarchical list. Normal icons + are used when the list item is not focused, and highlighted icons are + used when list item is focused. Normal icons are used also when list + item is focused, if corresponding highlighted icon is not specified + for the list item. */ + enum TIconType + { + /** Leaf icon. Only usable with tree leaves. */ + ELeaf = 0, + /** Highlighted leaf icon. Only usable with tree leaves. */ + EHighlightedLeaf = 1, + /** Expanded node icon. Only usable with tree nodes. */ + EExpandedNode = 2, + /** Highlighted expanded node icon. Only usable with tree nodes. */ + EHighlightedExpandedNode = 3, + /** Collapsed node icon. Only usable with tree nodes. */ + ECollapsedNode = 4, + /** Highlighted collapsed node icon. Only usable with tree nodes. */ + EHighlightedCollapsedNode = 5, + /** First optional icon. */ + EOptionalIcon1 = 6, + /** First highlighted optional icon. */ + EHighlightedOptionalIcon1 = 7, + /** Second optional icon. */ + EOptionalIcon2 = 8, + /** Second highlighted optional icon. */ + EHighlightedOptionalIcon2 = 9 + }; + + /** Single style hierarchical list ordering types. */ + enum TOrdering + { + /** Ascending alphabetical ordering based on item text fields. */ + EAscendingAlphabeticalOrdering, + /** Descending alphabetical ordering based on item text fields. */ + EDescendingAlphabeticalOrdering + }; + + /** Flags usable with single style tree items. */ + enum TSingleStyleItemFlags + { + /** Item is persistent. */ + EPersistent = 0x01, + /** Item is marked. */ + EMarked = 0x02, + /** Item is expanded. Applicable to nodes only. */ + EExpanded = 0x04, + /** Item appears non-empty. Applicable to nodes only. */ + ENonEmpty = 0x08 + }; + + /** + * Two phased constructor. Creates a new single style hierarchical list + * instance as window-owning control. + * + * @return Newly constructed object. + * + * @leave KErrNoMemory Not enough memory. + */ + IMPORT_C static CAknSingleStyleTreeList* NewL(); + + /** + * Two phased constructor. Creates a new single style hierarchical list + * instance as non-window-owning component control to the compound control + * given as parameter. + * + * @param aContainer The compound control used as container for the list. + * + * @return Newly constructed object. + * + * @leave KErrNoMemory Not enough memory. + */ + IMPORT_C static CAknSingleStyleTreeList* NewL( + const CCoeControl& aContainer ); + + /** + * Otherwise identical to @c NewL(), but leaves the newly created object + * in the cleanup stack. + * + * @copydoc CAknSingleStyleTreeList::NewL() + * + * @post Newly constructed object is left in cleanup stack. + */ + IMPORT_C static CAknSingleStyleTreeList* NewLC(); + + /** + * Otherwise identical to @c NewL( const CCoeControl& ), but leaves the + * newly created object in the cleanup stack. + * + * @copydoc CAknSingleStyleTreeList::NewL( const CCoeControl& ) + * + * @post Newly constructed object is left in cleanup stack. + */ + IMPORT_C static CAknSingleStyleTreeList* NewLC( + const CCoeControl& aContainer ); + + /** + * Destructor. + */ + virtual ~CAknSingleStyleTreeList(); + + /** + * Adds new leaf (file) to single style hierarchical list. New leaf with + * the specified content is created and added to the specified parent node. + * Constant @c KAknTreeIIDRoot can be used, if the new item is to be added + * to the top-most level of the hierarchical list. + * + * @param aParent The item ID of the parent node. + * + * @param aText Text for the added item. + * + * @param aFlags Flags for the added item. + * + * @param aDrawNow @c ETrue, if the list is to be redrawn after the item + * has been added to the list, otherwise @c EFalse. + * + * @return The item ID for the added leaf. + * + * @leave KErrNoMemory Not enough memory. + * + * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. + * + * @panic EAknHListPanicInvalidItemType Specified parent item is not a node. + */ + IMPORT_C TAknTreeItemID AddLeafL( TAknTreeItemID aParent, + const TDesC& aText, TUint32 aFlags, TBool aDrawNow ); + + /** + * Adds new node (folder) to single style hierarchical list. New node with + * the specified content is created and added to the specified parent node. + * Constant @c KAknTreeIIDRoot can be used, if the new item is to be added + * to the top-most level of the hierarchical list. + * + * @param aParent The item ID of the parent node. + * + * @param aText Text for the added node. + * + * @param aFlags Flags for the added node. + * + * @param aDrawNow @c ETrue to redraw the list after the node has been + * added, otherwise @c EFalse. + * + * @return The Item ID for the added node. + * + * @leave KErrNoMemory Not enough memory. + * + * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. + * + * @panic EAknHListPanicInvalidItemType Specified parent item is not a node. + */ + IMPORT_C TAknTreeItemID AddNodeL( TAknTreeItemID aParent, + const TDesC& aText, TUint32 aFlags, TBool aDrawNow ); + + /** + * Sorts the hierarchical list according to the given ordering. + * + * @param aOrdering Type of ordering. + * + * @param aDrawNow @c ETrue to redraw the list after it has been sorted + * according the new ordering, otherwise @c EFalse. + * + * @leave KErrNoMemory Not enough memory. + */ + IMPORT_C void SortL( TOrdering aOrdering, TBool aDrawNow ); + + /** + * Changes the text of the specified item. Note that the change of text + * might also affect the item's position in the list, when the items are + * ordered based on their text fields. + * + * @param aItem Item ID of modified item. + * + * @param aText New text for the item. + * + * @param aDrawNow @c ETrue if the list is to be redrawn after the text + * has been changed. + * + * @leave KErrNoMemory Not enough memory for adding text. + * + * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. + * + * @panic EAknHListPanicInvalidItemType Specified item has invalid type. + */ + IMPORT_C void SetTextL( TAknTreeItemID aItem, const TDesC& aText, + TBool aDrawNow ); + + /** + * Returns the text field of the specified item. + * + * @param aItem Item ID. + * + * @return Text of the specified item. + * + * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. + */ + IMPORT_C const TDesC& Text( TAknTreeItemID aItem ) const; + + /** + * Sets an icon for a list item. Every list item may have several icons, + * so the correct icon has to be specified with the icon type. Note that + * the type has to be applicable to the specified list item. Pre-defined + * icon IDs can be found within @c AknTreeListIconID namespace. Constant + * @c AknTreeListIconID::KDefault can be used to indicate that default + * icon is to be used, and constant @c AknTreeListIconID::KNone to + * indicate that no icon is to be used. + * + * @param aItem Item ID of the modified list item. + * + * @param aType The type of the icon to be added. + * + * @param aIconId Icon ID. Icon ID is the integer value returned by the + * @c AddIconL() method when the icon was added to the list. + * + * @param aDrawNow @c ETrue to redraw the list after the icon has been + * changed, othewise @c EFalse. + * + * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. + * + * @panic EAknHListPanicInvalidItemType Specified icon is not applicable + * with the item type. + */ + IMPORT_C void SetIcon( TAknTreeItemID aItem, TIconType aType, + TInt aIconId, TBool aDrawNow ); + + /** + * Returns the icon ID set for the specified icon of a list item. + * + * @param aItem Item ID of a list item. + * + * @param aType Type defining the specific icon within list item. + * + * @return Icon ID. The value @c AknTreeListIconID::KDefault is returned, + * if no icon has been set. Value @c KErrNotFound is returned, if the + * item does not contain icon of specified type. + * + * @panic EAknHListPanicInvalidItemID Item with specified ID is not found. + */ + IMPORT_C TInt Icon( TAknTreeItemID aItem, TIconType aType ) const; + +// from base class CAknTreeList + + /** + * From CAknTreeList. + * Sets the flags for the single style hierarchical list. + * + * @param aFlags Flags. + */ + void SetFlags( TUint32 aFlags ); + +private: + + /** + * Default constructor. + */ + CAknSingleStyleTreeList(); + + /** + * Second phase constructor. + */ + void ConstructL(); + + /** + * Second phase constructor. + * + * @param aContainer Container for the list. + */ + void ConstructL( const CCoeControl& aContainer ); + + }; + + +#endif // C_AKNSINGLESTYLETREELIST_H