CAknChoiceList Class Reference

Link against: avkon.lib

#include <aknchoicelist.h>

Detailed Description

CAknChoiceList Choice list is new component, which allows selection from vertical list of choices.

By default choice list shows currently selected item and a arrow for opening the the choice list. Choice list can be used also without showing current selection.

Dll avkon.lib

Since:: S60 5.0


Public Types
enum	TAknChoiceListFlags { EAknChoiceListWithCurrentSelection = 0x01, EAknChoiceListWithoutCurrentSelection = 0x02, EAknChoiceListPositionLeft = 0x04, EAknChoiceListPositionRight = 0x08, EAknChoiceListPositionBottom = 0x10 }
enum	TTooltipPosition { EPositionTop = 1, EPositionBottom, EPositionLeft, EPositionRight }
Public Member Functions
	~CAknChoiceList ()
	Destructor.
IMPORT_C TInt	ShowChoiceListL ()
	Open choice list.
IMPORT_C void	SetSelectedIndex (const TInt aIndex)
	Set certain index of the choice list array to selected.
IMPORT_C TInt	SelectedIndex () const
	Returns selected index from the choice list array.
IMPORT_C void	SetItems (CDesCArray *aArray)
	Set certain array as the contents of the choice list.
IMPORT_C void	SetItemsL (TInt aResourceId)
	Set certain array as the contents of the choice list.
IMPORT_C TInt	AddItemL (const TDesC *aDesC)
	Add a text as a new item in the end of the choice list array.
IMPORT_C void	RemoveItem (const TInt aIndex)
	Removes an item from the choice list array with the given index.
IMPORT_C void	SetFlags (const TInt aFlags)
	Sets flags for choice list.
IMPORT_C TInt	Flags () const
	Return choice list specific flags.
IMPORT_C void	SetButtonL (CAknButton *aButton)
	Set the button that launches choice list opening.
IMPORT_C void	HideChoiceList ()
	Hide choice list popup.
IMPORT_C void	SetTooltipTextL (const TDesC &aText)
	Set text for tooltip.
IMPORT_C void	SetTooltipTimeouts (const TInt aBeforeTimeout, const TInt aInViewTimeout)
	Set the delays for tooltip.
IMPORT_C void	SetTooltipPosition (const TTooltipPosition aPosition)
	Set the postion of tooltip.
IMPORT_C CCoeControl *	ComponentControl (TInt aIndex) const
	From CCoeControl.
IMPORT_C TInt	CountComponentControls () const
	From CCoeControl.
IMPORT_C TSize	MinimumSize ()
	From CCoeControl.
IMPORT_C void	HandleResourceChange (TInt aType)
	From CCoeControl.
IMPORT_C TKeyResponse	OfferKeyEventL (const TKeyEvent &aKeyEvent, TEventCode aType)
	From CCoeControl.
IMPORT_C void	Draw (const TRect &aRect) const
	From CCoeControl.
virtual IMPORT_C void	PositionChanged ()
	from CCoeControl
IMPORT_C void	HandleControlEventL (CCoeControl *aControl, TCoeEvent aEventType)
	From MCoeControlObserver.
IMPORT_C TInt	InsertItemL (const TInt aIndex, const TDesC &aText)
	Insert new item to a certain index.
Static Public Member Functions
static IMPORT_C CAknChoiceList *	NewL (CCoeControl aParent, CDesCArray aItemArray, TInt aFlags=EAknChoiceListWithCurrentSelection, CAknButton *aButton=NULL)
	Two-phased constructor.
static IMPORT_C CAknChoiceList *	NewLC (CCoeControl aParent, CDesCArray aItemArray, TInt aFlags=EAknChoiceListWithCurrentSelection, CAknButton *aButton=NULL)
	Two-phased constructor.
Protected Member Functions
void	SizeChanged ()
	From CCoeControl.
void	HandlePointerEventL (const TPointerEvent &aPointerEvent)
	From CCoeControl.

Member Enumeration Documentation

enum CAknChoiceList::TAknChoiceListFlags

Enumerator:

EAknChoiceListWithCurrentSelection
EAknChoiceListWithoutCurrentSelection
EAknChoiceListPositionLeft
EAknChoiceListPositionRight
EAknChoiceListPositionBottom

enum CAknChoiceList::TTooltipPosition

Enumerator:

EPositionTop
EPositionBottom
EPositionLeft
EPositionRight

Constructor & Destructor Documentation

CAknChoiceList::~CAknChoiceList

(

)

Destructor.

Member Function Documentation

IMPORT_C TInt CAknChoiceList::AddItemL

Add a text as a new item in the end of the choice list array.

Parameters:

aDesC

Pointer to a descriptor item that should be appended to the array. Transfers ownership.

Returns:: index in the choicelist array for newly added item.

IMPORT_C CCoeControl* CAknChoiceList::ComponentControl

From CCoeControl.

Returns the control inside control with given index.

Parameters:

aIndex

Index of a control be returned

Returns:: A Pointer to control.

IMPORT_C TInt CAknChoiceList::CountComponentControls

(

)

const

From CCoeControl.

Returns number of controls inside the control.

Returns:: Number of component controls.

IMPORT_C void CAknChoiceList::Draw

From CCoeControl.

Draws control to given area

Parameters:

aRect

The rectangle that should be drawn by the control.

IMPORT_C TInt CAknChoiceList::Flags

(

)

const

Return choice list specific flags.

Returns:: choice list flags

IMPORT_C void CAknChoiceList::HandleControlEventL	(	CCoeControl *	aControl,
		TCoeEvent	aEventType
	)

From MCoeControlObserver.

Handles an event from an observed control. If this component has observer, then a EEventStateChanged is sent to it when a item is selected from choice list

Parameters:

	aControl	The control that sent the event.
	aEventType	The event type.

void CAknChoiceList::HandlePointerEventL ( const TPointerEvent & aPointerEvent ) [protected]

From CCoeControl.

Handles pointer events

Parameters:

aPointerEvent

the pointer event be be handled.

IMPORT_C void CAknChoiceList::HandleResourceChange

From CCoeControl.

Handles a change to the control's resources.

Parameters:

aType

A message UID value.

IMPORT_C void CAknChoiceList::HideChoiceList

(

)

Hide choice list popup.

Current selection is not selected.

IMPORT_C TInt CAknChoiceList::InsertItemL	(	const TInt	aIndex,
		const TDesC &	aText
	)

Insert new item to a certain index.

The rest of the array will be reindexed. If given index is beyond current array then it's just appended to the end of the array.

Parameters:

	aIndex	The array index where new item is going to be inserted.
	aText	Items text

Returns:: The index of newly inserted item. Index can be other than passed if given index is out of array bounds

IMPORT_C TSize CAknChoiceList::MinimumSize

(

)

From CCoeControl.

Returns the Minimum size needed by the control.

Returns:: TSize minimum size.

static IMPORT_C CAknChoiceList* CAknChoiceList::NewL	(	CCoeControl *	aParent,
		CDesCArray *	aItemArray,
		TInt	aFlags = `EAknChoiceListWithCurrentSelection`,
		CAknButton *	aButton = `NULL`
	)	`[static]`

Two-phased constructor.

If the default flag is used then choice list shows an opening arrow and selected item on its left side. If flag EAknChoiceListUsesButton is and user has defined own button then choice list open with items in the given array. Selected item is not show when choice list is closed.

Parameters:

	aParent	the parent control for choice list
	aItemArray	Array of items to be shown in the choicelist. Transfers ownership.
	aFlags	Flags for choice list type and positioning
	aButton	user defined button for choicelist. Button replaces the typical choice list. Transfers ownership.

static IMPORT_C CAknChoiceList* CAknChoiceList::NewLC	(	CCoeControl *	aParent,
		CDesCArray *	aItemArray,
		TInt	aFlags = `EAknChoiceListWithCurrentSelection`,
		CAknButton *	aButton = `NULL`
	)	`[static]`

Two-phased constructor.

Parameters:

	aParent	the parent control for choice list
	aItemArray	Array of items to be shown in the choicelist. Transfers ownership.
	aFlags	Flags for choice list type and positioning
	aButton	user defined button for choicelist. Button replaces the typical choice list. Transfers ownership.

IMPORT_C TKeyResponse CAknChoiceList::OfferKeyEventL	(	const TKeyEvent &	aKeyEvent,
		TEventCode	aType
	)

From CCoeControl.

Handles key events.

Parameters:

	aKeyEvent	the key event
	aType	The type of key event

Returns:: Indicates whether or not the keyevent was used by this control

virtual IMPORT_C void CAknChoiceList::PositionChanged ( ) [virtual]

from CCoeControl

Responds to changes in the position of a control.

IMPORT_C void CAknChoiceList::RemoveItem

Removes an item from the choice list array with the given index.

Parameters:

aIndex

index for the item that should be removed from the choice list array

IMPORT_C TInt CAknChoiceList::SelectedIndex

(

)

const

Returns selected index from the choice list array.

Returns:: TInt selected index

IMPORT_C void CAknChoiceList::SetButtonL

Set the button that launches choice list opening.

Parameters:

aButton

The Button for opening choice list control

IMPORT_C void CAknChoiceList::SetFlags

Sets flags for choice list.

Choice lists position can be changed in runtime with right flags.

Parameters:

aFlags

The flags to be set for choice list

IMPORT_C void CAknChoiceList::SetItems

Set certain array as the contents of the choice list.

It's recommended to use CDesCArrayFlat. The ownership of the array is transferred to choice list.

Parameters:

aArray

Array of text items to be inserted as the content for choice list

IMPORT_C void CAknChoiceList::SetItemsL

Set certain array as the contents of the choice list.

It's recommended to use CDesCArrayFlat.

Parameters:

aResourceId

Resource id for an array.

IMPORT_C void CAknChoiceList::SetSelectedIndex

Set certain index of the choice list array to selected.

Parameters:

aIndex

Index of the array to be selected as default

IMPORT_C void CAknChoiceList::SetTooltipPosition

(

const TTooltipPosition

aPosition

)

Set the postion of tooltip.

Parameters:

aPosition

The position expressed with TTooltipPosition The default is EPositionTop

IMPORT_C void CAknChoiceList::SetTooltipTextL

Set text for tooltip.

Parameters:

aText

The text shown as tooltip

IMPORT_C void CAknChoiceList::SetTooltipTimeouts	(	const TInt	aBeforeTimeout,
		const TInt	aInViewTimeout
	)

Set the delays for tooltip.

Parameters:

	aBeforeTimeout	The delay in milliseconds before tooltip is shown. The default is 150 milliseconds
	aInViewTiemout	The interval in milliseconds how long the tooltip is displayed. The default is 3000 milliseconds.

IMPORT_C TInt CAknChoiceList::ShowChoiceListL

(

)

Open choice list.

Choicelist can be opened with this function. If the choicelist is already open nothing will happen.