1 aknsinglecolumnstyletreelist.h

     1 /*

     2 * Copyright (c) 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Single style hierarchical column list.

    15 *

    16 */

    17 

    18 

    19 #ifndef C_AKNSINGLECOLUMNSTYLETREELIST_H

    20 #define C_AKNSINGLECOLUMNSTYLETREELIST_H

    21 

    22 

    23 #include <akntreelist.h>

    24 

    25 

    26 /**

    27  *  Single style hierarchical column list.

    28  *

    29  *  Single style hierarchical column list is hierarchical list type that

    30  *  can contain three types of items: Core data rows, simple data rows, and

    31  *  subtitle rows.

    32  *

    33  *  Core data row is a list item that consists of two text columns in

    34  *  portrait mode, and in addition to those, it can have an optional

    35  *  third text column in landscape mode. Core data row can contain one icon

    36  *  in front of text columns, and up to two optional indicator icons at the

    37  *  other end of the row.

    38  *

    39  *  Simple data row is a list item that consists of single text column, and

    40  *  can have one leaf icon in front of the text, and one optional icon at

    41  *  the other end.

    42  *

    43  *  Subtitle row is otherwise similar to simple data row, but as core data

    44  *  row and simple data row are tree leaves that cannot contain other list

    45  *  items as children, the subtitle row is a tree node that can be used in 

    46  *  forming the hierarchy for the list. As a node, subtitle row has expand

    47  *  and collapse functionality, and it can group other tree items, including

    48  *  other subtitle rows. However, since hierarchical column list does not

    49  *  support indention of tree items or drawing of tree structure lines,

    50  *  the hierarchy should be limited to two levels for clarity.

    51  * 

    52  *  The @c CAknSingleColumnStyleTreeList class contains only methods for

    53  *  constructing the list, constructing and adding the list type specific

    54  *  items to the list, and setting and getting item type specific properties.

    55  *  Other methods for list usage can be found from its parent class.

    56  *

    57  *  @see CAknTreeList

    58  *

    59  *  Here is an example of how an instance of window-owning single style

    60  *  hierarchical column list can be constructed:

    61  *

    62  *  @code

    63  *  // Construct the list, set its size, and make it visible.

    64  *  CAknSingleColumnStyleTreeList* list

    65  *      = CAknSingleColumnStyleTreeList::NewL();

    66  *  list->SetRect( rect );

    67  *  list->MakeVisible( ETrue );

    68  *  @endcode

    69  *

    70  *  Adding items to the constructed list:

    71  *

    72  *  @code  

    73  *  TUint32 flags = CAknSingleColumnStyleTreeList::EPersistent;

    74  *  TBool drawNow = EFalse;

    75  *

    76  *  // Add simple data row to the top-most level of the tree.

    77  *  _LIT( KSimpleDataRowText, "Simple data row" );

    78  *  TAknTreeItemID simpleItem = list->AddSimpleDataRowL( KAknTreeIIDRoot,

    79  *      KSimpleDataRowText, flags, drawNow );

    80  *

    81  *  // Add subtitle row to the to the top-most level of the tree.

    82  *  _LIT( KSubtitleRowText, "Subtitle row" );

    83  *  TAknTreeItemID subtitle = list->AddSubtitleRowL( KAknTreeIIDRoot,

    84  *      KSubtitleRowText, flags, drawNow );

    85  *

    86  *  // Add core data row to the previously added subtitle row.

    87  *  _LIT( KCoreDataRowText, "Core data row" );

    88  *  TAknTreeItemID coreItem = list->AddCoreDataRowL( subtitle,

    89  *      KCoreDataRowText, KNulDesC, flags, drawNow );

    90  *  @endcode

    91  *

    92  *  @lib aknhlist.lib

    93  *  @since S60 v5.0

    94  */

    95 NONSHARABLE_CLASS( CAknSingleColumnStyleTreeList ) : public CAknTreeList

    96     {

    97 

    98 public:

    99 

   100     /** Item types used in single style hierarchical column list. The type

   101         of each item can be get with @c ItemType() method. */

   102     enum TItemType

   103         {

   104         /** No item type. Associated with constant @c KAknTreeIIDNone. */

   105         ENone           = 0,

   106         /** Tree root. Associated with constant @c KAknTreeIIDRoot. */

   107         ETreeRoot       = 1,

   108         /** Simple data row. */

   109         ESimpleDataRow  = 2,

   110         /** Core data row. */

   111         ECoreDataRow    = 3,

   112         /** Subtitle row. */

   113         ESubtitleRow    = 4

   114         };

   115 

   116     /** Flags usable with single column style tree items. These flags can

   117         be given, when adding new items to the list. */

   118     enum TItemFlags

   119         {

   120         /** Item is persistent. */

   121         EPersistent = 0x01,

   122         /** Item is marked. */

   123         EMarked     = 0x02,

   124         /** Item is expanded. Applicable to subtitle rows only. */

   125         EExpanded   = 0x04,

   126         /** Item appears non-empty. Applicable to subtitle rows only. */

   127         ENonEmpty   = 0x08,

   128         /** Emphasis. Applicable to core data rows only. */

   129         EEmphasis   = 0x10,

   130         /** Item is not markable. */

   131         EMarkingDisabled = 0x20

   132         };

   133 

   134     /** Icon types usable with single column style hierarchical list.

   135         Highlighted icons are used when item is focused, and normal icons are

   136         used when item is not focused, or corresponding highlighted icon is

   137         not specified for the item. */

   138     enum TIconType

   139         {

   140         /** Leaf icon. 

   141             Only usable with core data rows and simple data rows. */

   142         ELeaf                       = 0,

   143         /** Highlighted leaf icon.

   144             Only usable with core data rows and simple data rows. */

   145         EHighlightedLeaf            = 1,

   146         /** Expanded node icon. Only usable with subtitle rows. */

   147         EExpandedNode               = 2,

   148         /** Highlighted expanded node icon. Only usable with subtitle rows. */

   149         EHighlightedExpandedNode    = 3,

   150         /** Collapsed node icon. Only usable with subtitle rows. */

   151         ECollapsedNode              = 4,

   152         /** Highlighted collapsed node icon. Only usable with subtitle rows. */

   153         EHighlightedCollapsedNode   = 5,

   154         /** First optional icon. */

   155         EOptionalIcon1              = 6,

   156         /** First highlighted optional icon. */

   157         EHighlightedOptionalIcon1   = 7,

   158         /** Second optional icon. Only usable with core data rows. */

   159         EOptionalIcon2              = 8,

   160         /** Second highlighted optional icon.

   161             Only usable with core data rows. */

   162         EHighlightedOptionalIcon2   = 9

   163         };

   164 

   165     /**

   166      * Two phased constructor. Creates a new single style hierarchical column

   167      * list instance as window-owning control.

   168      *

   169      * @return Newly constructed object.

   170      *

   171      * @leave KErrNoMemory Not enough memory.

   172      */

   173     IMPORT_C static CAknSingleColumnStyleTreeList* NewL();

   174 

   175     /**

   176      * Two phased constructor. Creates a new single style hierarchical column

   177      * list instance as non-window-owning component control to the compound

   178      * control given as parameter.

   179      *

   180      * @param aContainer The compound control used as container for the list.

   181      *

   182      * @return Newly constructed object.

   183      *

   184      * @leave KErrNoMemory Not enough memory.

   185      */

   186     IMPORT_C static CAknSingleColumnStyleTreeList* NewL(

   187         const CCoeControl& aContainer );

   188 

   189     /**

   190      * Otherwise identical to @c NewL(), but leaves the newly created object

   191      * in the cleanup stack.

   192      *

   193      * @copydoc CAknSingleColumnStyleTreeList::NewL()

   194      *

   195      * @post Newly constructed object is left in cleanup stack.

   196      */

   197     IMPORT_C static CAknSingleColumnStyleTreeList* NewLC();

   198 

   199     /**

   200      * Otherwise identical to @c NewL( const CCoeControl& ), but leaves the

   201      * newly created object in the cleanup stack.

   202      *

   203      * @copydoc CAknSingleColumnStyleTreeList::NewL( const CCoeControl& )

   204      *

   205      * @post Newly constructed object is left in cleanup stack.

   206      */

   207     IMPORT_C static CAknSingleColumnStyleTreeList* NewLC(

   208         const CCoeControl& aContainer );

   209 

   210     /**

   211      * Destructor.

   212      */

   213     virtual ~CAknSingleColumnStyleTreeList();

   214 

   215     /**

   216      * Adds new simple data row to single style hierarchical column list. New

   217      * simple data row with the specified content is constructed and added to

   218      * the specified parent node. Constant @c KAknTreeIIDRoot can be used as

   219      * parent node, if the new item is to be added to the top-most level of

   220      * the hierarchy.

   221      *

   222      * @param aParent The item ID of the parent node.

   223      *

   224      * @param aText Text for simple data row.

   225      *

   226      * @param aFlags Flags for simple data row. Possible flags are defined

   227      *      in @c CAknSingleColumnStyleTreeList::TItemFlags enumeration.

   228      *

   229      * @param aDrawNow @c ETrue, if the list is to be redrawn after the item

   230      *      has been added to the list, otherwise @c EFalse.

   231      *

   232      * @return The Item ID for the added node.

   233      *

   234      * @leave KErrNoMemory Not enough memory.

   235      *

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

   237      *

   238      * @panic EAknHListPanicInvalidItemType Specified parent item is not a node.

   239      */

   240     IMPORT_C TAknTreeItemID AddSimpleDataRowL( TAknTreeItemID aParent,

   241         const TDesC& aText, TUint32 aFlags, TBool aDrawNow );

   242 

   243     /**

   244      * Adds new core data row to single style hierarchical column list. New

   245      * core data row containing specified two text columns is constructed and

   246      * added to the specified parent node. Constant @c KAknTreeIIDRoot can be

   247      * used as parent node, if the new item is to be added to the top-most

   248      * level of the hierarchy. By default, the core data row created with this

   249      * method has its third text column disabled, but it can later be enabled

   250      * with @c EnableThirdColumn() method.

   251      *

   252      * @param aParent The item ID of the parent node.

   253      *

   254      * @param aFirstColumn Text for first column of core data row.

   255      *

   256      * @param aSecondColumn Text for second column of core data row.

   257      *

   258      * @param aFlags Flags for core data row. Possible flags are defined

   259      *      in @c CAknSingleColumnStyleTreeList::TItemFlags enumeration.

   260      *

   261      * @param aDrawNow @c ETrue, if the list is to be redrawn after the item

   262      *      has been added to the list, otherwise @c EFalse.

   263      *

   264      * @return The Item ID for the added node.

   265      *

   266      * @leave KErrNoMemory Not enough memory.

   267      *

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

   269      *

   270      * @panic EAknHListPanicInvalidItemType Specified parent item is not a node.

   271      */

   272     IMPORT_C TAknTreeItemID AddCoreDataRowL( TAknTreeItemID aParent,

   273         const TDesC& aFirstColumn, const TDesC& aSecondColumn, TUint32 aFlags,

   274         TBool aDrawNow );

   275 

   276     /**

   277      * Adds new core data row to single style hierarchical column list. New

   278      * core data row containing the specified three text columns is constructed

   279      * and added to the specified parent node. Constant @c KAknTreeIIDRoot can

   280      * be used as parent node, if the new item is to be added to the top-most

   281      * level of the hierarchy. By default, the core data row created with this

   282      * method has its third text column enabled, but it can later be disabled

   283      * with @c EnableThirdColumn() method.

   284      *

   285      * @param aParent The item ID of the parent node.

   286      *

   287      * @param aFirstColumn Text for first column of core data row.

   288      *

   289      * @param aSecondColumn Text for second column of core data row.

   290      *

   291      * @param aThirdColumn Text for third column of core data row. The third

   292      *      column is visible only in landscape mode.

   293      *

   294      * @param aFlags Flags for core data row. Possible flags are defined

   295      *      in @c CAknSingleColumnStyleTreeList::TItemFlags enumeration.

   296      *

   297      * @param aDrawNow @c ETrue, if the list is to be redrawn after the item

   298      *      has been added to the list, otherwise @c EFalse.

   299      *

   300      * @leave KErrNoMemory Not enough memory.

   301      *

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

   303      *

   304      * @panic EAknHListPanicInvalidItemType Specified parent item is not a node.

   305      */

   306     IMPORT_C TAknTreeItemID AddCoreDataRowL( TAknTreeItemID aParent,

   307         const TDesC& aFirstColumnd, const TDesC& aSecondColumn,

   308         const TDesC& aThirdColumn, TUint32 aFlags, TBool aDrawNow );

   309 

   310     /**

   311      * Adds new subtitle row to single style hierarchical column list. New row

   312      * with the given content is constructed and added to the specified parent

   313      * node. Constant @c KAknTreeIIDRoot can be used as parent node, if the new

   314      * item is to be added to the top-most level of hierarchy.

   315      *

   316      * @param aParent The item ID of the parent node.

   317      *

   318      * @param aText Text for subtitle row.

   319      *

   320      * @param aFlags Flags for subtitle row. Possible flags are defined

   321      *      in @c CAknSingleColumnStyleTreeList::TItemFlags enumeration.

   322      *

   323      * @param aDrawNow @c ETrue, if the list is to be redrawn after the item

   324      *      has been added to the list, otherwise @c EFalse.

   325      *

   326      * @leave KErrNoMemory Not enough memory.

   327      *

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

   329      *

   330      * @panic EAknHListPanicInvalidItemType Specified parent item is not a node.

   331      */

   332     IMPORT_C TAknTreeItemID AddSubtitleRowL( TAknTreeItemID aParent,

   333         const TDesC& aText, TUint32 aFlags, TBool aDrawNow );

   334 

   335     /**

   336      * Returns the text field of the specified list item.

   337      *

   338      * @param aItem Item ID.

   339      *

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

   341      */

   342     IMPORT_C const TDesC& Text( TAknTreeItemID aItem ) const;

   343 

   344     /**

   345      * Returns the specified text column of specified list item. If the text

   346      * for specified column is not set, or the specified column does not

   347      * exist, empty descriptor is returned.

   348      * 

   349      * @param aItem Item ID.

   350      *

   351      * @param aColumnIndex Column index.

   352      *

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

   354      */

   355     IMPORT_C const TDesC& Text( TAknTreeItemID aItem, TInt aColumnIndex ) const;

   356 

   357     /**

   358      * Sets the text for specified hierarchical column list item.

   359      *

   360      * @param aItem Item ID.

   361      *

   362      * @param aText Text for specified list item.

   363      *

   364      * @param aDrawNow @c ETrue, if the list is to be redrawn after the text

   365      *      has been set, otherwise @c EFalse.

   366      *

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

   368      */

   369     IMPORT_C void SetTextL( TAknTreeItemID aItem, const TDesC& aText,

   370         TBool aDrawNow );

   371 

   372     /**

   373      * Sets the text for specified column of specified hierarchical column

   374      * list item. Non-zero value for column list can only be used with core

   375      * data row, as the other row types contain only one text column.

   376      *

   377      * @param aItem Item ID.

   378      *

   379      * @param aText Text for specified list item.

   380      *

   381      * @param aColumnIndex Index specifying the text column.

   382      *

   383      * @param aDrawNow @c ETrue, if the list is to be redrawn after the text

   384      *      has been set, otherwise @c EFalse.

   385      *

   386      * @leave KErrNotFound Specified column does not exist.

   387      *

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

   389      *

   390      * @panic EAknHListPanicInvalidItemType Invalid item type.

   391      */

   392     IMPORT_C void SetTextL( TAknTreeItemID aItem, const TDesC& aText,

   393         TInt aColumnIndex, TBool aDrawNow );

   394 

   395     /**

   396      * Checks whether the specified core data row is emphasised. When core

   397      * data row is emphasized, it uses different text layout for emphasising

   398      * the row.

   399      *

   400      * @param aItem Item ID for core data row.

   401      *

   402      * @return @c ETrue if item is emphasised, otherwise @c EFalse.

   403      *

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

   405      */

   406     IMPORT_C TBool IsEmphasised( TAknTreeItemID aItem ) const;

   407 

   408     /** 

   409      * Sets the emphasis for specified core data row. 

   410      *

   411      * @param aItem Item ID of core data row.

   412      *

   413      * @param aEmphasis @c ETrue to set emphasis on, @c EFalse to set it off.

   414      *

   415      * @param aDrawNow @c ETrue to redraw the list, otherwise @c EFalse.

   416      *

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

   418      *

   419      * @panic EAknHListPanicInvalidItemType Invalid item type.

   420      */

   421     IMPORT_C void SetEmphasis( TAknTreeItemID aItem, TBool aEmphasis,

   422         TBool aDrawNow );

   423 

   424     /**

   425      * Checks whether the third text column is enabled for specified core

   426      * data row. If third text column is enabled, it is shown for the item

   427      * in landscape mode, when list has enough space for the third column.

   428      *

   429      * @param aItem Item ID of core data row.

   430      *

   431      * @return @c ETrue if third column is enabled, otherwise @c EFalse.

   432      *

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

   434      */

   435     IMPORT_C TBool IsThirdColumnEnabled( TAknTreeItemID aItem ) const;

   436 

   437     /**

   438      * Enables or disables third text column usage in landscape mode for

   439      * specified core data row. 

   440      *

   441      * @param aItem Item ID or core data row.

   442      *

   443      * @param aEnable @c ETrue to enable third text column usage, @c EFalse

   444      *      to disable it.

   445      *

   446      * @param aDrawNow @c ETrue to redraw the list, otherwise @c EFalse.

   447      *

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

   449      *

   450      * @panic EAknHListPanicInvalidItemType Invalid item type.

   451      */

   452     IMPORT_C void EnableThirdColumn( TAknTreeItemID aItem, TBool aEnable,

   453         TBool aDrawNow );

   454 

   455     /**

   456      * Returns the icon ID set for the specified icon of a list item.

   457      *

   458      * @param aItem Item ID of a list item.

   459      *

   460      * @param aType Type defining the specific icon within list item.

   461      *

   462      * @return Icon ID. The value @c AknTreeListIconID::KDefault is returned,

   463      *      if no icon has been set. Value @c KErrNotFound is returned, if the

   464      *      item does not contain icon of specified type.

   465      *

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

   467      */

   468     IMPORT_C TInt Icon( TAknTreeItemID aItem, TIconType aType ) const;

   469 

   470     /**

   471      * Sets an icon for a list item. Every list item may have several icons,

   472      * so the correct icon has to be specified with the icon type. Note that

   473      * the type has to be applicable to the specified list item. Pre-defined

   474      * icon IDs can be found within @c AknTreeListIconID namespace. Constant

   475      * @c AknTreeListIconID::KDefault can be used to indicate that default

   476      * icon is to be used, and constant @c AknTreeListIconID::KNone to

   477      * indicate that no icon is to be used.

   478      *

   479      * @param aItem Item ID of the modified list item.

   480      *

   481      * @param aType The type of the icon to be added.

   482      *

   483      * @param aIconId Icon ID. Icon ID is one of the pre-defined icon IDs, or

   484      *      an integer value returned by @c AddIconL() or @c AddColorIconL()

   485      *      methods when new icon was added to the list.

   486      *

   487      * @param aDrawNow @c ETrue to redraw the list after the icon has been

   488      *      changed, otherwise @c EFalse.

   489      *

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

   491      *

   492      * @panic EAknHListPanicInvalidItemType Specified icon is not applicable

   493      *      with the item type.

   494      */

   495     IMPORT_C void SetIcon( TAknTreeItemID aItem, TIconType aType,

   496         TInt aIconId, TBool aDrawNow );

   497 

   498     /**

   499      * Checks the type of the specified list item.

   500      *

   501      * @param aItem Item ID specifying the list item.

   502      *

   503      * @return Type of the item.

   504      *

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

   506      */

   507     IMPORT_C TItemType ItemType( TAknTreeItemID aItem ) const;

   508 

   509 // from base class CAknTreeList

   510 

   511     /**

   512      * From CAknTreeList.

   513      * Sets the flags for the single style hierarchical column list.

   514      *

   515      * @param aFlags Flags.

   516      */

   517     void SetFlags( TUint32 aFlags );

   518 

   519     /**

   520      * From CAknTreeList.

   521      * Handles resource changes.

   522      *

   523      * @param aType

   524      */

   525     void HandleResourceChange( TInt aType );

   526 

   527 private:

   528 

   529     /**

   530      * Default constructor.

   531      */

   532     CAknSingleColumnStyleTreeList();

   533 

   534     /**

   535      * Second phase constructor.

   536      */

   537     void ConstructL();

   538 

   539     /**

   540      * Second phase constructor.

   541      *

   542      * @param aContainer Container for the list.

   543      */

   544     void ConstructL( const CCoeControl& aContainer );

   545 

   546     /**

   547      * Updates indention.

   548      */

   549     void UpdateIndention();

   550 

   551 private: // data

   552 

   553     };

   554 

   555 

   556 #endif // C_AKNSINGLECOLUMNSTYLETREELIST_H