CAknSelectionListDialog Class Reference

API published in: S60 1st Ed

Link against: avkon.lib eikctl.lib eikcoctl.lib

Capability Information

Required Capabilities

None

#include <aknselectionlist.h>

Inherits CAknDialog, and MEikListBoxObserver.

Inherited by CAknMarkableListDialog.

Detailed Description

CAknSelectionListDialog is the actual interface to the applications.

Use this class to get a full screen list.

This class only works in whole main pane. Do not try to use this directly for other places.

resource definition for this class:

 RESOURCE DIALOG r_res_id_for_a_dialog
   {
   flags = EAknDialogSelectionList;
   buttons = R_AVKON_SOFTKEYS_OPTIONS_BACK;
   items =
        {
        DLG_LINE
            {
            type = EAknCtSingleGraphicListBox;
            id = ESelectionListControl;
            control = LISTBOX
                {
                flags = EAknListBoxSelectionList;
                };
            }
     // the next dlg line is optional.
        ,
        DLG_LINE
            {
             itemflags = EEikDlgItemNonFocusing;
            id = EFindControl;
            type = EAknCtSelectionListFixedFind;
            }
        };
   }

The listbox type can be one of the following (defined in avkon.hrh and aknlists.h):

   EAknCtSingleListBox                (See CAknSingleStyleListBox)
   EAknCtSingleNumberListBox          (See CAknSingleNumberStyleListBox)
   EAknCtSingleHeadingListBox         (See CAknSingleHeadingStyleListBox)
   EAknCtSingleGraphicListBox         (See CAknSingleGraphicStyleListBox)
   EAknCtSingleGraphicHeadingListBox  (See CAknSingleGraphicHeadingStyleListBox)
   EAknCtSingleNumberHeadingListBox   (See CAknSingleNumberHeadingStyleListBox)
   EAknCtSingleLargeListBox           (See CAknSingleLargeStyleListBox)
   EAknCtDoubleListBox                (See CAknDoubleStyleListBox)
   EAknCtDoubleNumberListBox          (See CAknDoubleNumberStyleListBox)
   EAknCtDoubleTimeListBox            (See CAknDoubleTimeStyleListBox)
   EAknCtDoubleLargeListBox           (See CAknDoubleLargeStyleListBox)
   EAknCtDoubleGraphicListBox         (See CAknDoubleGraphicStyleListBox)

The type field while defining find can be one of the following:

EAknCtSelectionListFixedFind
EAknCtSelectionListPopupFind

The menubar you give for selection list dialog should have one of the following as one of its menu panes (defined in avkon.hrh):

R_AVKON_MENUPANE_SELECTION_LIST
R_AVKON_MENUPANE_SELECTION_LIST_WITH_FIND_POPUP

 RESOURCE MENU_BAR r_res_id_for_a_menubar
 {
 titles =
     {
     MENU_TITLE { menu_pane = R_AVKON_MENUPANE_SELECTION_LIST; } 
     };
 };

C++ Usage:

    TInt openedItem = 0;
    MDesCArray *array = ...;
    CAknSelectionListDialog *dialog = CAknSelectionListDialog::NewL(openedItem, array, R_RES_ID_FOR_A_MENUBAR);
    TInt result = dialog->ExecuteLD(R_RES_ID_FOR_A_DIALOG);
    if (result)
        {
        ...use openeditem here...
        }
    else
        {
        ...canceled...
        }

Alternatively, you can use:

    TInt openedItem = 0;
    MDesCArray *array = ...;
    CAknSelectionListDialog *dialog = CAknSelectionListDialog::NewL(openedItem, array, R_RES_ID_FOR_A_MENUBAR);
    dialog->PrepareLC(R_RES_ID_FOR_A_DIALOG);
    // do some operations here, for example fill icon array 
    TInt result = dialog->RunLD();
    if (result)
        {
        ...
        }
    else
        {
        ...
        }

Often it is also useful to derive from CAknSelectionListDialog and implement OkToExitL(), constructors and the NewL() methods. OkToExitL() implementation helps with providing navigation with other dialogs; OkToExitL() is ideal place to launch new dialogs when a list item is selected. This way when backstepping, the state of the first dialog is preserved...


Public Types
enum	TFindType { ENoFind, EFixedFind, EPopupFind }
	CAknSelectionListDialog::TFindType Determines what kind of findbox should be used. More...
Public Member Functions
IMPORT_C void	ConstructL (TInt aMenuTitleResourceId)
	ConstructL() Second phase constructor.
IMPORT_C void	SetupFind (TFindType aType)
	SetupFind().
IMPORT_C CArrayPtr< CGulIcon > *	IconArray () const
	IconArray().
IMPORT_C void	SetIconArrayL (CArrayPtr< CGulIcon > *aIcons)
	SetIconArrayL().
IMPORT_C void	HandlePointerEventL (const TPointerEvent &aPointerEvent)
	From CCoeControl.
Static Public Member Functions
static IMPORT_C CAknSelectionListDialog *	NewL (TInt &aOpenedItem, MDesCArray aArray, TInt aMenuBarResourceId, MEikCommandObserver aCommand=0)
	CAknSelectionListDialog::NewL().
static IMPORT_C CAknSelectionListDialog *	NewLC (TInt &aOpenedItem, MDesCArray aArray, TInt aMenuBarResourceId, MEikCommandObserver aCommand=0)
	CAknSelectionListDialog::NewLC().
Protected Member Functions
IMPORT_C	CAknSelectionListDialog (TInt &aIndex, MDesCArray aArray, MEikCommandObserver aCommand)
	CAknSelectionListDialog() Default constructor.
IMPORT_C	~CAknSelectionListDialog ()
	~CAknSelectionListDialog() Destructor.
virtual IMPORT_C void	SelectionListProcessCommandL (TInt aCommand)
	SelectionListProcessCommandL() handles selection list and markable list default commands.
virtual IMPORT_C TBool	IsAcceptableListBoxType (TInt aControlType, TBool &aIsFormattedCellList) const
	IsAcceptableListBoxType(): Detection of list and grid layouts.
IMPORT_C void	ProcessCommandL (TInt aCommandId)
	ProcessCommandL() From CAknDialog.
IMPORT_C void	PreLayoutDynInitL ()
	PreLayoutDynInitL() From CAknDialog.
IMPORT_C void	PostLayoutDynInitL ()
	PreLayoutDynInitL() From CAknDialog.
IMPORT_C void	SetSizeAndPosition (const TSize &aSize)
	SetSizeAndPosition() From CAknDialog.
IMPORT_C TBool	OkToExitL (TInt aButtonId)
	OkToExitL() From CAknDialog.
IMPORT_C void	HandleListBoxEventL (CEikListBox *aListBox, TListBoxEvent aEventType)
	HandleListBoxEventL() From MEikListBoxObserver Handles listbox events.
IMPORT_C TInt	CountComponentControls () const
	CountComponentControls() From CCoeControl.
IMPORT_C CCoeControl *	ComponentControl (TInt aIndex) const
	ComponentControl() From CCoeControl.
IMPORT_C TKeyResponse	OfferKeyEventL (const TKeyEvent &aKeyEvent, TEventCode aType)
	OfferKeyEventL() From CCoeControl.
IMPORT_C SEikControlInfo	CreateCustomControlL (TInt aControlType)
	CreateCustomControlL() creates own list or grid layouts.
virtual IMPORT_C CEikListBox *	ListBox () const
	ListBox() accessor to listbox control.
IMPORT_C CAknSearchField *	FindBox () const
	FindBox() accessor to findbox control.
IMPORT_C TBool	IsFormattedCellListBox () const
	IsFormattedCellListBox() used to check whether listbox control is a CEikFormattedCellListBox or a CEikColumnListBox.
IMPORT_C void	Draw (const TRect &) const
	Draw() from CCoeControl.
Static Protected Member Functions
static TInt	ExitViaIdle (TAny *aSelectionList)
	ExitViaIdle().
Protected Attributes
TBool	iEnterKeyPressed
	iEnterKeyPressed Set as ETrue if EAknCmdOpen is handled in ProcessCommandL().

Member Enumeration Documentation

enum CAknSelectionListDialog::TFindType

CAknSelectionListDialog::TFindType Determines what kind of findbox should be used.

Note, that a fixed findbox is not available with all list types.

Enumerator:

ENoFind	no findbox should be used
EFixedFind	fixed findbox should be used
EPopupFind	popup findbox should be used

Constructor & Destructor Documentation

IMPORT_C CAknSelectionListDialog::CAknSelectionListDialog	(	TInt &	aIndex,
		MDesCArray *	aArray,
		MEikCommandObserver *	aCommand
	)	`[protected]`

CAknSelectionListDialog() Default constructor.

IMPORT_C CAknSelectionListDialog::~CAknSelectionListDialog ( ) [protected]

~CAknSelectionListDialog() Destructor.

Member Function Documentation

IMPORT_C CCoeControl* CAknSelectionListDialog::ComponentControl ( TInt aIndex ) const [protected]

ComponentControl() From CCoeControl.

Reimplemented from CEikDialog.

IMPORT_C void CAknSelectionListDialog::ConstructL

(

TInt

aMenuTitleResourceId

)

ConstructL() Second phase constructor.

Parameters:

aMenuTitleResourceId

Menu items to be shown in options menu. Same as aMenuBarResourceId of NewL(C).

Reimplemented from CAknDialog.

Reimplemented in CAknMarkableListDialog.

IMPORT_C TInt CAknSelectionListDialog::CountComponentControls ( ) const [protected]

CountComponentControls() From CCoeControl.

Reimplemented from CEikDialog.

IMPORT_C SEikControlInfo CAknSelectionListDialog::CreateCustomControlL ( TInt aControlType ) [protected, virtual]

CreateCustomControlL() creates own list or grid layouts.

Normal implementation of this method is:

 SEikControlInfo CreateCustomControlL(TInt aControlType)
     {
     CCoeControl *control = NULL;
     if ( aControlType == EMyCtGridLayout )
         {
         // CMyOddStyleGrid should be derived from CAknFormattedCellListBox or CEikColumnListBox.
         control = new(ELeave)CMyOddStyleGrid;
         } 
     SEikControlInfo info = {control,0,0};
     return info;
     }

Reimplemented from CEikDialog.

IMPORT_C void CAknSelectionListDialog::Draw ( const TRect & ) const [protected, virtual]

Draw() from CCoeControl.

Reimplemented from CAknDialog.

static TInt CAknSelectionListDialog::ExitViaIdle ( TAny * aSelectionList ) [static, protected]

ExitViaIdle().

Callback function to exit dialog after selecting something with tapping it. This prevents dialog to be destroyed before dialog page's handlepointereventl is fully completed.

Parameters:

aSelectionList

pointer to current CAknSelectionList

IMPORT_C CAknSearchField* CAknSelectionListDialog::FindBox ( ) const [protected]

FindBox() accessor to findbox control.

Returns:: a pointer to the findbox

IMPORT_C void CAknSelectionListDialog::HandleListBoxEventL	(	CEikListBox *	aListBox,
		TListBoxEvent	aEventType
	)	`[protected]`

HandleListBoxEventL() From MEikListBoxObserver Handles listbox events.

Parameters:

	aListBox	currently ignored
	aEventType	type of the listbox event

Reimplemented in CAknMarkableListDialog.

IMPORT_C void CAknSelectionListDialog::HandlePointerEventL

(

const TPointerEvent &

aPointerEvent

)

From CCoeControl.

Handles pointer events

Parameters:

aPointerEvent

The pointer event.

Reimplemented from CAknDialog.

Reimplemented in CAknMarkableListDialog.

IMPORT_C CArrayPtr<CGulIcon>* CAknSelectionListDialog::IconArray

Icons, images and thumbnails are in this array.

The list items are tab separated strings with fixed format. Some of the numbers in the list item strings are indexes to this array.

This array can be modified by MDesCArray::MdcaPoint() method or at construction of dialog; after PrepareLC() call.

Returns:: pointer to iconarray of the list

virtual IMPORT_C TBool CAknSelectionListDialog::IsAcceptableListBoxType	(	TInt	aControlType,
		TBool &	aIsFormattedCellList
	)	const `[protected, virtual]`

IsAcceptableListBoxType(): Detection of list and grid layouts.

The CAknSelectionList only works with certain list and grid layouts.

You will get Panic() if you use your own list/grid layouts and you do not have this method implemented!

If you add new list layouts, you should implement this method to publish the type of the layout using this method. This is especially the case where you use CAknSelectionGrid with your own grid layout. (as there are no predefined grid layouts, you need to do this every time you use a selection grid)

The following aControlTypes are already implemented and requires no action:

     EAknCtSingleListBox
     EAknCtSingleNumberListBox
     EAknCtSingleHeadingListBox
     EAknCtSingleGraphicListBox
     EAknCtSingleGraphicHeadingListBox
     EAknCtSingleNumberHeadingListBox
     EAknCtSingleLargeListBox
     EAknCtDoubleListBox
     EAknCtDoubleNumberListBox
     EAknCtDoubleTimeListBox
     EAknCtDoubleLargeListBox
     EAknCtDoubleGraphicListBox
     EAknCtSettingListBox
     EAknCtSettingNumberListBox

Any other layout requires you to inherit from CAknSelectionList and implement the following methods:

 TBool IsAcceptableListBoxType(TInt aControlType, TBool &aIsFormattedCellList)
     {
     if (aControlType == EMyCtGridLayout)
         {
         // CAknGrid is-a formattedcelllistbox.
         aIsFormattedCellList = ETrue;
         return ETrue;
         }
     else
        {
        return EFalse;
        }
     }

Parameters:

	aControlType	type of the control. Ignored in current default implementation.
	aIsFormattedCellList	returns whetehr list is a formatted cell listbox or a column listbox. Ignored in current default implementation. In derived implementations this must be set according to dialog's listbox type.

Returns:: whether layout can be used

IMPORT_C TBool CAknSelectionListDialog::IsFormattedCellListBox ( ) const [protected]

IsFormattedCellListBox() used to check whether listbox control is a CEikFormattedCellListBox or a CEikColumnListBox.

If you derive from IsAcceptableListBoxType() you must take care of the aIsFormattedCellListParameter to make this method to work correctly.

Returns:: whether listbox control is a CEikFormattedCellListBox

virtual IMPORT_C CEikListBox* CAknSelectionListDialog::ListBox ( ) const [protected, virtual]

ListBox() accessor to listbox control.

Returns:: a pointer to the listbox

static IMPORT_C CAknSelectionListDialog* CAknSelectionListDialog::NewL	(	TInt &	aOpenedItem,
		MDesCArray *	aArray,
		TInt	aMenuBarResourceId,
		MEikCommandObserver *	aCommand = `0`
	)	`[static]`

CAknSelectionListDialog::NewL().

Static factory constructor. Uses two phase construction and leaves nothing on the CleanupStack.

Parameters:

	aOpenedItem	Variable to be modified when user selects a list item.
	aArray	Content of list items; A tab-separated string with texts and indexes to icon array
	aMenuBarResourceId	Menu items to be shown in options menu
	aCommand	Callback for state changes. EAknCmdOpen command is send by listbox. Options menu commands come here too.

Returns:: A pointer to created object

static IMPORT_C CAknSelectionListDialog* CAknSelectionListDialog::NewLC	(	TInt &	aOpenedItem,
		MDesCArray *	aArray,
		TInt	aMenuBarResourceId,
		MEikCommandObserver *	aCommand = `0`
	)	`[static]`

CAknSelectionListDialog::NewLC().

Static factory constructor. Uses two phase construction and leaves created object in CleanupStack.

Parameters:

	aOpenedItem	Variable to be modified when user selects a list item.
	aArray	Content of list items; A tab-separated string with texts and indexes to icon array
	aMenuBarResourceId	Menu items to be shown in options menu
	aCommand	Callback for state changes. EAknCmdOpen command is send by listbox. Options menu commands come here too.

Returns:: A pointer to created object

IMPORT_C TKeyResponse CAknSelectionListDialog::OfferKeyEventL	(	const TKeyEvent &	aKeyEvent,
		TEventCode	aType
	)	`[protected]`

OfferKeyEventL() From CCoeControl.

Reimplemented from CAknDialog.

Reimplemented in CAknMarkableListDialog.

IMPORT_C TBool CAknSelectionListDialog::OkToExitL ( TInt aButtonId ) [protected, virtual]

OkToExitL() From CAknDialog.

This is not called if the Cancel button is activated unless the EEikDialogFlagNotifyEsc flag has been set.

Parameters:

aButtonId

The ID of the button that was activated.

Reimplemented from CAknDialog.

Reimplemented in CAknMarkableListDialog.

IMPORT_C void CAknSelectionListDialog::PostLayoutDynInitL ( ) [protected, virtual]

PreLayoutDynInitL() From CAknDialog.

Reimplemented from CEikDialog.

Reimplemented in CAknMarkableListDialog.

IMPORT_C void CAknSelectionListDialog::PreLayoutDynInitL ( ) [protected, virtual]

PreLayoutDynInitL() From CAknDialog.

Reimplemented from CEikDialog.

Reimplemented in CAknMarkableListDialog.

IMPORT_C void CAknSelectionListDialog::ProcessCommandL ( TInt aCommandId ) [protected, virtual]

ProcessCommandL() From CAknDialog.

Processes commands and passes commands to FindBox and ListBox as needed.

Parameters:

aCommandId

id of the command.

Reimplemented from CAknDialog.

Reimplemented in CAknMarkableListDialog.

virtual IMPORT_C void CAknSelectionListDialog::SelectionListProcessCommandL ( TInt aCommand ) [protected, virtual]

SelectionListProcessCommandL() handles selection list and markable list default commands.

For markable lists, this method handles EAknCmdMark, EAknCmdUnmark, EAknMarkAll, EAknUnmarkAll defined in options menu pane R_AVKON_MENUPANE_MARKABLE_LIST.

Reimplemented in CAknMarkableListDialog.

IMPORT_C void CAknSelectionListDialog::SetIconArrayL

(

CArrayPtr< CGulIcon > *

aIcons

)

SetIconArrayL().

Icons, images and thumbnails are in this array.

The list items are tab separated strings with fixed format. Some of the numbers in the list item strings are indexes to this array.

This array can be modified by MDesCArray::MdcaPoint() method or at construction of dialog; after PrepareLC() call.

Parameters:

aIcons

a array containing icons.

IMPORT_C void CAknSelectionListDialog::SetSizeAndPosition ( const TSize & aSize ) [protected, virtual]

SetSizeAndPosition() From CAknDialog.

Sets dialog's size to whole main pane.

Parameters:

aSize

ignored

Reimplemented from CEikDialog.

IMPORT_C void CAknSelectionListDialog::SetupFind

Provides a way to enable and disable find and find popup on runtime. You still need entry with id EFindControl to resource file for the find, this is only for disabling existing find element.

Parameters:

aType

type of findbox to be used.