/*

* Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Base class for an on-screen list box control from

*               which one or more items can be selected.

*

*/

#ifndef __EIKLBX_H__

#define __EIKLBX_H__

//  INCLUDES 

#include <gdi.h>

#include <eikbctrl.h>

#include <eiklbo.h>

#include <eiksbfrm.h>

#include <eiklbm.h>

#include <eiklbv.h>

#include <gulbordr.h>

#include <eiklbed.h>

#include <gulutil.h>

#include <lafpublc.h>

//  FORWARD DECLARATIONS

enum TKeyCode;

class RIncrMatcherBase;

class CListItemDrawer;

class CEikScrollBarFrame;

class CEikButtonBase;

class CMatchBuffer;

class CListBoxExt;

class CEikListBox;

class MAknMarkingModeObserver;

//  CLASS DECLARATION

/**

* Item change observer will be notified when list box items have been added or

* removed or the list box has been reset. Observers can be added and removed by

* using @c CEikListBox methods @c AddItemChangeObserverL() and

* @c RemoveItemChangeObserver().

*

* @since 3.0

*/

class MListBoxItemChangeObserver

    {

    public:

        /**

         * Notification and handling of a list box item change.

         *

         * @param aListBox The source list box of this message.

         */

        virtual void ListBoxItemsChanged(CEikListBox* aListBox) = 0;

    };

/**

* Item selection (marking) observer is used to let application control item marking

* (in markable lists). Observers can be added and removed by using

* @c CEikListBox methods @c AddSelectionObserverL() and

* @c RemoveSelectionObserver().

*

* @since 3.2

*/

class MListBoxSelectionObserver

    {

    public:

        /**

         * Notification of entering and leaving marking mode. Marking mode

         * is enabled by long pressing shift, ctrl or hash keys (when hash key marking is enabled).

         *

         * @param aListBox The source list box of this message.

         * @param aSelectionModeEnabled ETrue, when entering selection (marking) mode.

         */

        virtual void SelectionModeChanged(CEikListBox* aListBox, TBool aSelectionModeEnabled) = 0;

    };

// CLASS DECLARATION

/**

 * Base class for an on-screen list box control from which one or more items 

 * can be selected.

 *

 * @c CEikListBox implements the basics of a list box. It has a scroll bar 

 * frame, an item drawer, and a model, and reports events to a list box 

 * observer.

 * 

 * List boxes display a number of items within a scrolling frame; the items 

 * in a list box which are visible at one time are represented by a list 

 * box view. 

 * 

 * Writing derived classes: 

 * 

 * This class may be derived from to provide specialisations of the basic 

 * list box behaviour. It is usual when subclassing CEikListBox to also 

 * provide specialisations of CListItemDrawer and CListBoxView for 

 * representing the data of such a list box effectively

 */

class CEikListBox : public CEikBorderedControl, public MEikScrollBarObserver

    {

public:

    friend class CListBoxExt;

public:

    /**

    * Construction flags.

    */

    enum TFlags

        {

        /**

         * Construction flag for a list box from which the user can

         * select multiple items.

         */

        EMultipleSelection          = SLafListBox::EMultipleSelection,

        /**

         * Construction flag for disabling extended selection. 

         * If this is set the user cannot select multiple items by

         * using @c SHIFT button.

         */

        ENoExtendedSelection        = SLafListBox::ENoExtendedSelection,

        /**

         * Construction flag that sets the list box to match user?s keystrokes 

         * incrementally.

         */

        EIncrementalMatching        = SLafListBox::EIncrementalMatching,

        /**

         * Construction flag for setting the list box as a pop-out list box. 

         * Pop-out list boxes handle certain keystrokes and events differently.

         */

        EPopout                     = SLafListBox::EPopout,

        /**

         * Construction flag that enables the indication of pointer press 

         * inside the view of the list box.

         */

        ELeftDownInViewRect         = SLafListBox::ELeftDownInViewRect,

        /**

         * Construction flag for enabling @c CEiklist box item double click 

         * indication.

         */

        EItemDoubleClicked          = SLafListBox::EItemDoubleClicked,

        /**

         * Construction flag for removing the ownership of the supplied list box

         * model from the @c CEikListBox so that the list box model will not be 

         * deleted with the @c CEikListBoxes destruction.

         */

        EKeepModel                  = SLafListBox::EKeepModel,

        /**

         * Construction flag for excluding the scroll bar.

         * If the flag is set the scroll bas is drawn ouside the window that 

         * describes the scroll bars extent.

         */

        EScrollBarSizeExcluded      = SLafListBox::EScrollBarSizeExcluded,

        /**

         * Construction flag for enabling @c CEikListBox change indication.

         */

        EStateChanged               = SLafListBox::EStateChanged,

        /**

         * Construction flag that indicates that the list box should be created 

         * to its own window.

         */

        ECreateOwnWindow            = SLafListBox::ECreateOwnWindow,

        /**

         * Construction flag for disabling key matching.

         */

        ENoFirstLetterMatching      = SLafListBox::ENoFirstLetterMatching,

        /**

         * Construction flag for enabling painting of selected items.

         */

        EPaintedSelection           = SLafListBox::EPaintedSelection ,

        /**

         * Construction flag for enabling loop scrolling in which the list box 

         * jumps from the last item to the first item.

         */

        ELoopScrolling = 0x1000,

        /**

         * Construction flag for enabling @c Avkon multiselection list.

         */

        EEnterMarks = 0x2000,       // Avkon multiselection list

        /**

         * Construction flag for enabling Avkon markable list which enables the 

         * marking of several items from the list. 

         */

        EShiftEnterMarks = 0x4000,  // Avkon markable list

        /**

         * Construction flag that combines @c EPageAtOnceScrolling and 

         * @c EDisableHighlight flags

         */

        EViewerFlag = 0x8000,       // combined the two flags to fit to WORD.

        /**

         * Construction flag for enabling scrolling at a page per time so that 

         * the whole list box page is scrolled to the next. 

         */

        EPageAtOnceScrolling = 0x8000, // Avkon viewers

        /**

         * Construction flag for disabling the highlighting of the selected item.

         */

        EDisableHighlight = 0x8000,  // Avkon viewers       

        /**

         * Construction flag for enabling S60 style selection of multiple items 

         * from the list box.

         */

        ES60StyleMultiselection     = SLafListBox::ES60StyleMultiselection,   

        /**

         * Construction flag for enabling S60 style markable items.

         */

        ES60StyleMarkable           = SLafListBox::ES60StyleMarkable,

        /**

         * Construction flag for disabling item specific stylus popup menu.

         */

        EDisableItemSpecificMenu    = 0x00040000,

        /**

         * Construction flag to make item specific stylus popup menu always

         * shown regardless of list's marking state if the tapped item has 

         * associated commands.

         */

        EItemSpecificMenuAlwaysShown = 0x00080000

        };

    enum {KEikMaxMatchingBufferLength = 2};

    /** 

     * Indicates who owns the scroll bar.

     */ 

    enum TScrollBarOwnerShip

        {

        /**

         * Indicates that the scrollbar is not owned by an external class.

         */

        ENotOwnedExternally=0x0000,

        /**

         * Indicates that the scrollbar is owned by an external class.

         */

        EOwnedExternally   =0x0001

        };

protected:

    /**

     * Used for indicating the reason why the item lost focus.

     */

    enum TReasonForFocusLost

        { 

        /**

         * Focus has been lost from the list box to an external control.

         */

        EFocusLostToExternalControl, 

        /**

         * Focus has been moved from the list box to an internal editor.

         */

        EFocusLostToInternalEditor 

        };

public:

    /**

     * Destructor.

     */

    IMPORT_C ~CEikListBox();

    /**

     * C++ default constructor.

     */

    IMPORT_C CEikListBox();

    /**

     * Handles 2nd phase construction.

     * 

     * Sets list box model and list item drawer. Request another @c ConstructL 

     * to handle @c aParent and @c aFlags. 

     *

     * @param aListBoxModel List box model that is to be used with the list box.

     * @param aListItemDrawer List item drawer that is to be used with the 

     *        list box.

     * @param aParent Host @c CoeControl for the list box.

     * @param aFlags Construction flags (@c TFlags) for the list box.

     */

    IMPORT_C void ConstructL(MListBoxModel* aListBoxModel,

                             CListItemDrawer* aListItemDrawer,

                             const CCoeControl* aParent,

                             TInt aFlags = 0);

    /**

     * Handles 2nd phase construction.

     *

     *

     * Sets the border that is to be drawn outside the list box. Request another 

     * @c ConstructL to handle list box model, list item drawer, @c aParent 

     * and @c aFlags. 

     *

     * @param aListBoxModel List box model that is to be used with the list box.

     * @param aListItemDrawer List item drawer that is to be used with the 

     *        list box.

     * @param aParent Host @c CoeControl for the list box.

     * @param aBorder Border to be drawn outside the list box.

     * @param aFlags Construction flags (@c TFlags) for the list box.

     */

    IMPORT_C void ConstructL(MListBoxModel* aListBoxModel,

                             CListItemDrawer* aListItemDrawer,

                             const CCoeControl* aParent, 

                             TGulBorder aBorder, 

                             TInt aFlags = 0);

    /**

     * Informs the @c CEikListbox of a key press.

     *

     * @param aKeyEvent Details of the key event that is being handled.

     * @param aType Defines what kind of key event is being handled e.g. 

     *        @c EEventKeyUp.

     * @return @c EKeyWasConsumed if the key was handled by the method.

     *         @c EKeyWasNotConsumed if the key was not handled.

     */

    IMPORT_C virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,

                                                 TEventCode aType);

    /**

     * Handling of pointer event within the @c CEikListBox. 

     * Used for e.g. selecting an item from the list box.

     *

     * @param aPointerEvent Details of the pointer event that is being handled.

     */

    IMPORT_C virtual void HandlePointerEventL(

                            const TPointerEvent& aPointerEvent);

    /**

     * Creates an own window for the list box or draws the list box to an old 

     * window defined by the @c aContainer.

     *

     * @param aContainer Defines the container where the list box will be drawn.

     */

    IMPORT_C virtual void SetContainerWindowL(const CCoeControl& aContainer);

    /**

     * Checks the minimum size needed for the list box.

     *

     * @return The two dimensional minimum size for the list box.

     */

    IMPORT_C virtual TSize MinimumSize();

    /**

     * This function sets a flag within the control which indicates 

     * whether or not the control is dimmed (greyed out). 

     *

     * @param aDimmed @c ETrue dimmed. @c EFalse not dimmed.

     */

    IMPORT_C virtual void SetDimmed(TBool aDimmed);

    /**

     * Used for scrolling through the items in the list box. 

     *

     * @param aScrollBar Scroll bar for the list box.

     * @param aEventType Type of the event that occured.

     */

    IMPORT_C virtual void HandleScrollEventL(CEikScrollBar* aScrollBar, 

                                             TEikScrollEvent aEventType);

    // model/view access functions 

    /**

     * Gets the list box data model.

     *

     * @return Interface to the list box data model.

     */

    IMPORT_C MListBoxModel* Model() const;

    /**

     * Gets the list box view.

     *

     * @return Interface to the list box view.

     */

    IMPORT_C CListBoxView* View() const;

    // functions for accessing top/current/bottom item index

    /**

     * Gets the index number of the top item.

     *

     * @return Index number for the top item.

     */

    IMPORT_C TInt TopItemIndex() const;

    /**

     * Sets the selected item to be the top item.

     *

     * @param aItemIndex Index for the item to be set as the top item.

     */

    IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const;

    /**

     * Gets for the bottom items index.

     *

     * @return Index for the bottom item.

     */

    IMPORT_C TInt BottomItemIndex() const;

    /**

     * Gets the index number of the selected item.

     *

     * @return Index of the selected item.

     */

    IMPORT_C TInt CurrentItemIndex() const;   

    /**

     * Changes the current item index to the selected item index. Does not

     * redraw the list. If the item was not previously visible it is set to the 

     * top item in the view.

     *

     * @param aItemIndex Defines the index of the selected item.

     */

    IMPORT_C void SetCurrentItemIndex(TInt aItemIndex) const;

    /**

     * Changes the current item index to the selected item index and 

     * redraws the view.

     *

     * @param aItemIndex Defines the index of the selected item.

     */

    IMPORT_C void SetCurrentItemIndexAndDraw(TInt aItemIndex) const;

    // functions for dealing with the selection state

    /**

     * Gets for list boxes selection indexes.

     *

     * @return Pointer to the list boxes in array of selection indexes.

     */

    IMPORT_C const CListBoxView::CSelectionIndexArray* SelectionIndexes() const;

    /**

     * Assigns a array of selection indexes for the list box.

     *

     * @param aArrayOfSelectionIndexes The index array that is to be assigned 

     *        to the list Box.

     */

    IMPORT_C void SetSelectionIndexesL(

                CListBoxView::CSelectionIndexArray* aArrayOfSelectionIndexes);

    /**

     * Clears the selection from the view.

     */

    IMPORT_C void ClearSelection(); 

    // Functions for updating a list box's internal state after its model has

    // been updated, all of them will emit item change event to item change

    // observers.

    /**

     * Handles the addition of item to the list box.

     */

    IMPORT_C void HandleItemAdditionL();

    /**

     * Handles the removal of an item from the list box.

     */

    IMPORT_C void HandleItemRemovalL();

    /**

     * Handles the addition of new items to the list box and updates 

     * selection indexes array.

     *

     * NOTE. This algorithm can not handle position of the list highlight

     * nor can it update the top item index correctly.

     *

     * @param aArrayOfNewIndexesAfterAddition Array of new indexes to be added.

     */

    IMPORT_C void HandleItemAdditionL(

                    CArrayFix<TInt> &aArrayOfNewIndexesAfterAddition);

    /**

     * Handles the removal of items to the list box and updates 

     * selection indexes array.

     *

     * NOTE. This algorithm cannot handle position of the list highlight

     * nor can it update the top item index correctly.

     *

     * @param aArrayOfOldIndexesBeforeRemoval Array of indexes to be removed.

     */

    IMPORT_C void HandleItemRemovalL(

                    CArrayFix<TInt> &aArrayOfOldIndexesBeforeRemoval);

    /**

     * Deletes the item editor

     */

    IMPORT_C void Reset();

    /**

    * Adds an item change observer to the listbox. Duplicates are not checked

    * (i.e. adding the same observer multiple times is not prevented).

    *

    * @since 3.0

    * @param aObserver Must be non-NULL.

    */

    IMPORT_C void AddItemChangeObserverL( MListBoxItemChangeObserver* aObserver );

    /**

    * Removes an item change observer from the listbox.

    *

    * @since 3.0

    * @param aObserver The observer to be removed.

    * @return ETrue if removal ok, EFalse if observer was not removed (not

    *         found from the list of observers).