/*

* Copyright (c) 1997-1999 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:

*

*/

#if !defined(__EIKLBM_H__)

#define __EIKLBM_H__  

#if !defined(__E32BASE_H__)

#include <e32base.h>

#endif

#if !defined(__BAMDESCA_H__)

#include <bamdesca.h>

#endif

// for some reason, doxygen seems to refuse documenting this...

/** @enum TListBoxModelItemArrayOwnership

* List box item array ownership flags. These values are used to

* describe whether or not a list box model owns an item array.

*/

enum TListBoxModelItemArrayOwnership

    {

    /** The list box model owns the item array, and will delete it in

    * its destructor.*/

    ELbmOwnsItemArray,

    /** The model does not own the item array. You must maintain a

    * pointer to it and free it explicitly before your program exits. */

    ELbmDoesNotOwnItemArray

    };

/**

* Description

* List box data model interface.

* 

* This mixin protocol is implemented by all list box models. List box

* models provide information needed to display the required data in a

* list box.

*

* Writing derived classes:

* 

* This class should be implemented by anything providing data for

* display in a CEikListBox-derived class. The very basic interface

* offered by MListBoxModel is usually expanded upon to provide more

* information for the specialised subclasses of CEikListBox. It is

* usual when deriving specialised list boxes to subclass the list box

* class, its view classes and its model together. See also:

*

*/

class MListBoxModel 

    {

    public:

        /**

        * Destructor.

        */

        IMPORT_C virtual ~MListBoxModel();

        /**

        * Gets the number of items in the list box

        * @return Number of items.

        */

        virtual TInt NumberOfItems() const = 0;

        /**

        * Gets an array of strings used by the list box for matching

        * user keypresses incrementally.

        *

        * @return A pointer to the array.

        */

        virtual const MDesCArray* MatchableTextArray() const = 0;

    private:

        IMPORT_C virtual TAny* MListBoxModel_Reserved();

    };

/**

* Text list box model interface.

*

* Text list box models provide the text of the items which are drawn

* by an associated CTextListItemDrawer. This interface is implemented

* by CTextListBoxModel.

*/

class MTextListBoxModel : public MListBoxModel

    {

    public:

        /**

        * Destructor

        */

        IMPORT_C ~MTextListBoxModel();

        /**

        * Gets the item text for an item by its index. This text,

        * rather than the matcher string, is drawn by

        * CTextListItemDrawers.

        * 

        * @param aItemIndex Index specifying an item.

        * @return The text for that item.

        */

        virtual TPtrC ItemText(TInt aItemIndex) const = 0;

    private: // from MListBoxModel

        IMPORT_C virtual TAny* MListBoxModel_Reserved();

    };

#endif