--- 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 <akntreelist.h>
+
+
+/**
+ * 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