CAknSingleColumnStyleTreeList Class Reference

Link against: aknhlist.lib

#include <aknsinglecolumnstyletreelist.h>

Detailed Description

Single style hierarchical column list is hierarchical list type that can contain three types of items: Core data rows, simple data rows, and subtitle rows.

Core data row is a list item that consists of two text columns in portrait mode, and in addition to those, it can have an optional third text column in landscape mode. Core data row can contain one icon in front of text columns, and up to two optional indicator icons at the other end of the row.

Simple data row is a list item that consists of single text column, and can have one leaf icon in front of the text, and one optional icon at the other end.

Subtitle row is otherwise similar to simple data row, but as core data row and simple data row are tree leaves that cannot contain other list items as children, the subtitle row is a tree node that can be used in forming the hierarchy for the list. As a node, subtitle row has expand and collapse functionality, and it can group other tree items, including other subtitle rows. However, since hierarchical column list does not support indention of tree items or drawing of tree structure lines, the hierarchy should be limited to two levels for clarity.

The CAknSingleColumnStyleTreeList class contains only methods for constructing the list, constructing and adding the list type specific items to the list, and setting and getting item type specific properties. Other methods for list usage can be found from its parent class.

See also:: CAknTreeList

Here is an example of how an instance of window-owning single style hierarchical column list can be constructed:

  // Construct the list, set its size, and make it visible.
  CAknSingleColumnStyleTreeList* list
      = CAknSingleColumnStyleTreeList::NewL();
  list->SetRect( rect );
  list->MakeVisible( ETrue );

Adding items to the constructed list:

  TUint32 flags = CAknSingleColumnStyleTreeList::EPersistent;
  TBool drawNow = EFalse;

  // Add simple data row to the top-most level of the tree.
  _LIT( KSimpleDataRowText, "Simple data row" );
  TAknTreeItemID simpleItem = list->AddSimpleDataRowL( KAknTreeIIDRoot,
      KSimpleDataRowText, flags, drawNow );

  // Add subtitle row to the to the top-most level of the tree.
  _LIT( KSubtitleRowText, "Subtitle row" );
  TAknTreeItemID subtitle = list->AddSubtitleRowL( KAknTreeIIDRoot,
      KSubtitleRowText, flags, drawNow );

  // Add core data row to the previously added subtitle row.
  _LIT( KCoreDataRowText, "Core data row" );
  TAknTreeItemID coreItem = list->AddCoreDataRowL( subtitle,
      KCoreDataRowText, KNulDesC, flags, drawNow );

Dll aknhlist.lib

Since:: S60 v5.0


Public Types
enum	TItemType { ENone = 0, ETreeRoot = 1, ESimpleDataRow = 2, ECoreDataRow = 3, ESubtitleRow = 4 }
	Item types used in single style hierarchical column list. More...
enum	TItemFlags { EPersistent = 0x01, EMarked = 0x02, EExpanded = 0x04, ENonEmpty = 0x08, EEmphasis = 0x10, EMarkingDisabled = 0x20 }
	Flags usable with single column style tree items. More...
enum	TIconType { ELeaf = 0, EHighlightedLeaf = 1, EExpandedNode = 2, EHighlightedExpandedNode = 3, ECollapsedNode = 4, EHighlightedCollapsedNode = 5, EOptionalIcon1 = 6, EHighlightedOptionalIcon1 = 7, EOptionalIcon2 = 8, EHighlightedOptionalIcon2 = 9 }
	Icon types usable with single column style hierarchical list. More...
Public Member Functions
virtual	~CAknSingleColumnStyleTreeList ()
	Destructor.
IMPORT_C TAknTreeItemID	AddSimpleDataRowL (TAknTreeItemID aParent, const TDesC &aText, TUint32 aFlags, TBool aDrawNow)
	Adds new simple data row to single style hierarchical column list.
IMPORT_C TAknTreeItemID	AddCoreDataRowL (TAknTreeItemID aParent, const TDesC &aFirstColumn, const TDesC &aSecondColumn, TUint32 aFlags, TBool aDrawNow)
	Adds new core data row to single style hierarchical column list.
IMPORT_C TAknTreeItemID	AddCoreDataRowL (TAknTreeItemID aParent, const TDesC &aFirstColumnd, const TDesC &aSecondColumn, const TDesC &aThirdColumn, TUint32 aFlags, TBool aDrawNow)
	Adds new core data row to single style hierarchical column list.
IMPORT_C TAknTreeItemID	AddSubtitleRowL (TAknTreeItemID aParent, const TDesC &aText, TUint32 aFlags, TBool aDrawNow)
	Adds new subtitle row to single style hierarchical column list.
IMPORT_C const TDesC &	Text (TAknTreeItemID aItem) const
	Returns the text field of the specified list item.
IMPORT_C const TDesC &	Text (TAknTreeItemID aItem, TInt aColumnIndex) const
	Returns the specified text column of specified list item.
IMPORT_C void	SetTextL (TAknTreeItemID aItem, const TDesC &aText, TBool aDrawNow)
	Sets the text for specified hierarchical column list item.
IMPORT_C void	SetTextL (TAknTreeItemID aItem, const TDesC &aText, TInt aColumnIndex, TBool aDrawNow)
	Sets the text for specified column of specified hierarchical column list item.
IMPORT_C TBool	IsEmphasised (TAknTreeItemID aItem) const
	Checks whether the specified core data row is emphasised.
IMPORT_C void	SetEmphasis (TAknTreeItemID aItem, TBool aEmphasis, TBool aDrawNow)
	Sets the emphasis for specified core data row.
IMPORT_C TBool	IsThirdColumnEnabled (TAknTreeItemID aItem) const
	Checks whether the third text column is enabled for specified core data row.
IMPORT_C void	EnableThirdColumn (TAknTreeItemID aItem, TBool aEnable, TBool aDrawNow)
	Enables or disables third text column usage in landscape mode for specified core data row.
IMPORT_C TInt	Icon (TAknTreeItemID aItem, TIconType aType) const
	Returns the icon ID set for the specified icon of a list item.
IMPORT_C void	SetIcon (TAknTreeItemID aItem, TIconType aType, TInt aIconId, TBool aDrawNow)
	Sets an icon for a list item.
IMPORT_C TItemType	ItemType (TAknTreeItemID aItem) const
	Checks the type of the specified list item.
void	SetFlags (TUint32 aFlags)
	From CAknTreeList.
void	HandleResourceChange (TInt aType)
	From CAknTreeList.
Static Public Member Functions
static IMPORT_C CAknSingleColumnStyleTreeList *	NewL ()
	Two phased constructor.
static IMPORT_C CAknSingleColumnStyleTreeList *	NewL (const CCoeControl &aContainer)
	Two phased constructor.
static IMPORT_C CAknSingleColumnStyleTreeList *	NewLC ()
	Otherwise identical to `NewL()`, but leaves the newly created object in the cleanup stack.
static IMPORT_C CAknSingleColumnStyleTreeList *	NewLC (const CCoeControl &aContainer)
	Otherwise identical to `NewL( const CCoeControl& )`, but leaves the newly created object in the cleanup stack.

Member Enumeration Documentation

enum CAknSingleColumnStyleTreeList::TIconType

Icon types usable with single column style hierarchical list.

Highlighted icons are used when item is focused, and normal icons are used when item is not focused, or corresponding highlighted icon is not specified for the item.

Enumerator:

ELeaf	Leaf icon. Only usable with core data rows and simple data rows.
EHighlightedLeaf	Highlighted leaf icon. Only usable with core data rows and simple data rows.
EExpandedNode	Expanded node icon. Only usable with subtitle rows.
EHighlightedExpandedNode	Highlighted expanded node icon. Only usable with subtitle rows.
ECollapsedNode	Collapsed node icon. Only usable with subtitle rows.
EHighlightedCollapsedNode	Highlighted collapsed node icon. Only usable with subtitle rows.
EOptionalIcon1	First optional icon.
EHighlightedOptionalIcon1	First highlighted optional icon.
EOptionalIcon2	Second optional icon. Only usable with core data rows.
EHighlightedOptionalIcon2	Second highlighted optional icon. Only usable with core data rows.

enum CAknSingleColumnStyleTreeList::TItemFlags

Flags usable with single column style tree items.

These flags can be given, when adding new items to the list.

Enumerator:

EPersistent	Item is persistent.
EMarked	Item is marked.
EExpanded	Item is expanded. Applicable to subtitle rows only.
ENonEmpty	Item appears non-empty. Applicable to subtitle rows only.
EEmphasis	Emphasis. Applicable to core data rows only.
EMarkingDisabled	Item is not markable.

enum CAknSingleColumnStyleTreeList::TItemType

Item types used in single style hierarchical column list.

The type of each item can be get with ItemType() method.

Enumerator:

ENone	No item type. Associated with constant `KAknTreeIIDNone`.
ETreeRoot	Tree root. Associated with constant `KAknTreeIIDRoot`.
ESimpleDataRow	Simple data row.
ECoreDataRow	Core data row.
ESubtitleRow	Subtitle row.

Constructor & Destructor Documentation

virtual CAknSingleColumnStyleTreeList::~CAknSingleColumnStyleTreeList ( ) [virtual]

Destructor.

Member Function Documentation

IMPORT_C TAknTreeItemID CAknSingleColumnStyleTreeList::AddCoreDataRowL	(	TAknTreeItemID	aParent,
		const TDesC &	aFirstColumnd,
		const TDesC &	aSecondColumn,
		const TDesC &	aThirdColumn,
		TUint32	aFlags,
		TBool	aDrawNow
	)

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

New core data row containing the specified three text columns is constructed and added to the specified parent node. Constant KAknTreeIIDRoot can be used as parent node, if the new item is to be added to the top-most level of the hierarchy. By default, the core data row created with this method has its third text column enabled, but it can later be disabled with EnableThirdColumn() method.

Parameters:

	aParent	The item ID of the parent node.
	aFirstColumn	Text for first column of core data row.
	aSecondColumn	Text for second column of core data row.
	aThirdColumn	Text for third column of core data row. The third column is visible only in landscape mode.
	aFlags	Flags for core data row. Possible flags are defined in `CAknSingleColumnStyleTreeList::TItemFlags` enumeration.
	aDrawNow	`ETrue`, if the list is to be redrawn after the item has been added to the list, otherwise `EFalse`.

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 CAknSingleColumnStyleTreeList::AddCoreDataRowL	(	TAknTreeItemID	aParent,
		const TDesC &	aFirstColumn,
		const TDesC &	aSecondColumn,
		TUint32	aFlags,
		TBool	aDrawNow
	)

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

New core data row containing specified two text columns is constructed and added to the specified parent node. Constant KAknTreeIIDRoot can be used as parent node, if the new item is to be added to the top-most level of the hierarchy. By default, the core data row created with this method has its third text column disabled, but it can later be enabled with EnableThirdColumn() method.

Parameters:

	aParent	The item ID of the parent node.
	aFirstColumn	Text for first column of core data row.
	aSecondColumn	Text for second column of core data row.
	aFlags	Flags for core data row. Possible flags are defined in `CAknSingleColumnStyleTreeList::TItemFlags` enumeration.
	aDrawNow	`ETrue`, if the list is to be redrawn after the item has been added to the list, otherwise `EFalse`.

Returns:: 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 CAknSingleColumnStyleTreeList::AddSimpleDataRowL	(	TAknTreeItemID	aParent,
		const TDesC &	aText,
		TUint32	aFlags,
		TBool	aDrawNow
	)

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

New simple data row with the specified content is constructed and added to the specified parent node. Constant KAknTreeIIDRoot can be used as parent node, if the new item is to be added to the top-most level of the hierarchy.

Parameters:

	aParent	The item ID of the parent node.
	aText	Text for simple data row.
	aFlags	Flags for simple data row. Possible flags are defined in `CAknSingleColumnStyleTreeList::TItemFlags` enumeration.
	aDrawNow	`ETrue`, if the list is to be redrawn after the item has been added to the list, otherwise `EFalse`.

Returns:: 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 CAknSingleColumnStyleTreeList::AddSubtitleRowL	(	TAknTreeItemID	aParent,
		const TDesC &	aText,
		TUint32	aFlags,
		TBool	aDrawNow
	)

Adds new subtitle row to single style hierarchical column list.

New row with the given content is constructed and added to the specified parent node. Constant KAknTreeIIDRoot can be used as parent node, if the new item is to be added to the top-most level of hierarchy.

Parameters:

	aParent	The item ID of the parent node.
	aText	Text for subtitle row.
	aFlags	Flags for subtitle row. Possible flags are defined in `CAknSingleColumnStyleTreeList::TItemFlags` enumeration.
	aDrawNow	`ETrue`, if the list is to be redrawn after the item has been added to the list, otherwise `EFalse`.

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 void CAknSingleColumnStyleTreeList::EnableThirdColumn	(	TAknTreeItemID	aItem,
		TBool	aEnable,
		TBool	aDrawNow
	)

Enables or disables third text column usage in landscape mode for specified core data row.

Parameters:

	aItem	Item ID or core data row.
	aEnable	`ETrue` to enable third text column usage, `EFalse` to disable it.
	aDrawNow	`ETrue` to redraw the list, otherwise `EFalse`.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Invalid item type.

void CAknSingleColumnStyleTreeList::HandleResourceChange

From CAknTreeList.

Handles resource changes.

Parameters:

aType

Reimplemented from CAknTreeList.

IMPORT_C TInt CAknSingleColumnStyleTreeList::Icon	(	TAknTreeItemID	aItem,
		TIconType	aType
	)	const

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

Parameters:

	aItem	Item ID of a list item.
	aType	Type defining the specific icon within list item.

Returns:: Icon ID. The value AknTreeListIconID::KDefault is returned, if no icon has been set. Value KErrNotFound is returned, if the item does not contain icon of specified type.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

IMPORT_C TBool CAknSingleColumnStyleTreeList::IsEmphasised

Checks whether the specified core data row is emphasised.

When core data row is emphasized, it uses different text layout for emphasising the row.

Parameters:

aItem

Item ID for core data row.

Returns:: ETrue if item is emphasised, otherwise EFalse.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

IMPORT_C TBool CAknSingleColumnStyleTreeList::IsThirdColumnEnabled

Checks whether the third text column is enabled for specified core data row.

If third text column is enabled, it is shown for the item in landscape mode, when list has enough space for the third column.

Parameters:

aItem

Item ID of core data row.

Returns:: ETrue if third column is enabled, otherwise EFalse.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

IMPORT_C TItemType CAknSingleColumnStyleTreeList::ItemType

Checks the type of the specified list item.

Parameters:

aItem

Item ID specifying the list item.

Returns:: Type of the item.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

static IMPORT_C CAknSingleColumnStyleTreeList* CAknSingleColumnStyleTreeList::NewL ( const CCoeControl & aContainer ) [static]

Two phased constructor.

Creates a new single style hierarchical column list instance as non-window-owning component control to the compound control given as parameter.

Parameters:

aContainer

The compound control used as container for the list.

Returns:: Newly constructed object.

Leave:: KErrNoMemory Not enough memory.

static IMPORT_C CAknSingleColumnStyleTreeList* CAknSingleColumnStyleTreeList::NewL ( ) [static]

Two phased constructor.

Creates a new single style hierarchical column list instance as window-owning control.

Returns:: Newly constructed object.

Leave:: KErrNoMemory Not enough memory.

static IMPORT_C CAknSingleColumnStyleTreeList* CAknSingleColumnStyleTreeList::NewLC ( const CCoeControl & aContainer ) [static]

Otherwise identical to NewL( const CCoeControl& ), but leaves the newly created object in the cleanup stack.

Two phased constructor.

Creates a new single style hierarchical column list instance as non-window-owning component control to the compound control given as parameter.

Parameters:

aContainer

The compound control used as container for the list.

Returns:: Newly constructed object.

Leave:: KErrNoMemory Not enough memory.

Postcondition:: Newly constructed object is left in cleanup stack.

static IMPORT_C CAknSingleColumnStyleTreeList* CAknSingleColumnStyleTreeList::NewLC ( ) [static]

Otherwise identical to NewL(), but leaves the newly created object in the cleanup stack.

Two phased constructor.

Creates a new single style hierarchical column list instance as window-owning control.

Returns:: Newly constructed object.

Leave:: KErrNoMemory Not enough memory.

Postcondition:: Newly constructed object is left in cleanup stack.

IMPORT_C void CAknSingleColumnStyleTreeList::SetEmphasis	(	TAknTreeItemID	aItem,
		TBool	aEmphasis,
		TBool	aDrawNow
	)

Sets the emphasis for specified core data row.

Parameters:

	aItem	Item ID of core data row.
	aEmphasis	`ETrue` to set emphasis on, `EFalse` to set it off.
	aDrawNow	`ETrue` to redraw the list, otherwise `EFalse`.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Invalid item type.

void CAknSingleColumnStyleTreeList::SetFlags ( TUint32 aFlags ) [virtual]

From CAknTreeList.

Sets the flags for the single style hierarchical column list.

Parameters:

aFlags

Flags.

Reimplemented from CAknTreeList.

IMPORT_C void CAknSingleColumnStyleTreeList::SetIcon	(	TAknTreeItemID	aItem,
		TIconType	aType,
		TInt	aIconId,
		TBool	aDrawNow
	)

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 AknTreeListIconID namespace. Constant AknTreeListIconID::KDefault can be used to indicate that default icon is to be used, and constant AknTreeListIconID::KNone to indicate that no icon is to be used.

Parameters:

	aItem	Item ID of the modified list item.
	aType	The type of the icon to be added.
	aIconId	Icon ID. Icon ID is one of the pre-defined icon IDs, or an integer value returned by `AddIconL()` or `AddColorIconL()` methods when new icon was added to the list.
	aDrawNow	`ETrue` to redraw the list after the icon has been changed, otherwise `EFalse`.

Panic:: EAknHListPanicInvalidItemID Item with specified ID is not found.

Panic:: EAknHListPanicInvalidItemType Specified icon is not applicable with the item type.

IMPORT_C void CAknSingleColumnStyleTreeList::SetTextL	(	TAknTreeItemID	aItem,
		const TDesC &	aText,
		TInt	aColumnIndex,
		TBool	aDrawNow
	)

Sets the text for specified column of specified hierarchical column list item.

Non-zero value for column list can only be used with core data row, as the other row types contain only one text column.

Parameters:

	aItem	Item ID.
	aText	Text for specified list item.
	aColumnIndex	Index specifying the text column.
	aDrawNow	`ETrue`, if the list is to be redrawn after the text has been set, otherwise `EFalse`.