/*

* 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 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:  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 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

        };

    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).

    */

    IMPORT_C TBool RemoveItemChangeObserver( MListBoxItemChangeObserver* aObserver );

    // functions for accessing the item height

    /**

     * Sets the height of the item to the selected value.

     * 

     * @param aHeight New height for the item.

     */

    IMPORT_C virtual void SetItemHeightL(TInt aHeight);

    /**

     * Gets height of the item.

     *

     * @return Height of the item.

     */

    IMPORT_C TInt ItemHeight() const;

    // functions for scrollbars

    /**

     * Creates a scrollbar frame.

     *

     * @param  aPreAlloc Boolean defining if there should be initial 

     *         memory allocations.

     * @return The new scroll bar frame.

     */

    IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc=EFalse);

    /**

     * Sets the given scroll bar frame for the list box with the given 

     * ownership leve.

     *

     * @param aScrollBarFrame The new frame that is going to be used.

     * @param aOwnerShip Ownership level of the scroll bar frame.

     */

    IMPORT_C void SetScrollBarFrame(CEikScrollBarFrame* aScrollBarFrame, TScrollBarOwnerShip aOwnerShip);

    /**

     * Gets pointer for the scroll bar frame.

     *

     * @return Pointer to the scroll bar frame.

     */

    IMPORT_C CEikScrollBarFrame* const ScrollBarFrame();

    /**

     * Updates all scroll bars.

     */

    IMPORT_C virtual void UpdateScrollBarsL();

    // construction support functions

    /**

     * Gets the size of the rectangle required to display a pop out.

     * 

     * @param aTargetItemIndex The item from which the popout originates.

     * @param aTargetYPos Vertical position of the item from which the popout 

     *        originates.

     * @param aListBoxRect The list box rectangle.

     * @param aMinHeightInNumOfItems The minimum number of items for the popout.

     */

    IMPORT_C void CalculatePopoutRect( TInt aTargetItemIndex,

                                       TInt aTargetYPos,

                                       TRect& aListBoxRect,

                                       TInt aMinHeightInNumOfItems = 1 );

    /**

     * Gets the size of the list box in pixels based on the height of 

     * the list box in items and the length of the items in characters.

     *

     * Returns @c TSize element consisting of two elements, the height 

     * and the width. Height is the number of items times the height 

     * of the font in pixels. Width is the number of characters in a 

     * single line times the width of the font in pixels. 

     *

     * @param aWidthAsNumOfChars Width of list box in characters.

     * @param aHeightAsNumOfItems Height of list box in characters.

     * @return The size of the list box in pixels as TSize.

     */

    IMPORT_C TSize CalcSizeInPixels(TInt aWidthAsNumOfChars, 

                                    TInt aHeightAsNumOfItems) const;

    /**

     * Gets the width of the list box in pixels based on the width of the list 

     * box in characters.

     *

     * Returns the number of characters times the width of a character 

     * in pixels. 

     *

     * @param aNumOfChars The number of characters.

     * @return The width of the list box in pixels.

     */

    IMPORT_C TInt CalcWidthBasedOnNumOfChars(TInt aNumOfChars) const;

    /**

     * Gets the height of the list box in pixels based on the width of the 

     * list box in characters.

     *

     * Returns the number of items times the height of the font in pixels.

     *

     * @param aNumOfItems The number of items.

     * @return The height of the list box in pixels.

     */

    IMPORT_C TInt CalcHeightBasedOnNumOfItems(TInt aNumOfItems) const;

    /**

     * Gets the width of the list box in pixels based on the width of the 

     * list box text in pixels.

     *

     * returns the width of the whole list box in pixels, which includes 

     * the text width and the width of elements in the list box that have

     * an effect on the overall width.

     *

     * @param aTextWidthInPixels Width of list box text in pixels.

     * @return Required width of whole list box in pixels.

     */

    IMPORT_C TInt CalcWidthBasedOnRequiredItemWidth(

                                TInt aTextWidthInPixels) const;

    // drawing/scrolling functions

    /**

     * Draws a list box item, first scrolling the list to make it visible 

     * if it is not already. 

     *

     * @c DrawItem() panics if there is no list box view currently set.

     * @param aItemIndex Index of the item to reveal.

     */

    IMPORT_C void DrawItem(TInt aItemIndex) const;

    /**

     * Makes an item visible in the list, scrolling it if necessary.

     *

     * @param aItemIndex Index of the item to reveal.

     */

    IMPORT_C void ScrollToMakeItemVisible(TInt aItemIndex) const;

    /**

    * Redraws list item.

    * @param aItemIndex index of item to be redrawn.

    * @since 3.2

    */

    IMPORT_C void RedrawItem( TInt aItemIndex );

    // observer support

    /**

     * Sets the observer for the list box.

     *

     * @param aObserver Wanted observer for the list box.

     */

    IMPORT_C void SetListBoxObserver(MEikListBoxObserver* aObserver);

    /**

     * Gets the size of the vertical gap between items. This space is used 

     * by the view to allow a box to be drawn around each item.

     *

     * @return Size of the vertical gap in pixels.

     */

    IMPORT_C TInt VerticalInterItemGap() const;

    // popouts only

    /**

     * Provides a call back mechanism to the button which just launched a 

     * popout menu.

     *

     * @param aButton The button which just launched a popout menu.

     */

    IMPORT_C void SetLaunchingButton(CEikButtonBase* aButton);

    // Editing support

    /**

     * Selects an item editor for the list box.

     *

     * @param aEditor The editor that has been selected for usage.

     */

    IMPORT_C void SetItemEditor(MEikListBoxEditor* aEditor);

    /**

     * Resets the list boxes item editor.

     */

    IMPORT_C void ResetItemEditor();

    /**

     * Gets item editor for the current class.

     *

     * @return The item editor used by the list box class.

     */

    IMPORT_C MEikListBoxEditor* ItemEditor();

    /**

     * Creates an item editor and starts editing the current item.

     *

     * The editor can edit the current item up to a maximum length of 

     * @c aMaxLength characters. Also reports an @c EEventEditingStarted event 

     * to any list box observer by default.

     *

     * The function only creates a new editor if one does not already exist.

     *

     * @param aMaxLength Maximum length of characters to edit.

     */

    IMPORT_C virtual void EditItemL(TInt aMaxLength);

    /**

     * Stops editing and deletes the item editor. 

     *

     * The function reports an @c EEventEditingStopped event to any list box 

     * observer, and updates the list box model if @c aUpdateModel is @c ETrue.

     *

     * @param aUpdateModel If @c ETrue the list box model is updated.

     */

    IMPORT_C void StopEditingL(TBool aUpdateModel);

    // functions needed for Avkon shortcuts, 

    // passing information from one list to another

    /**

     * No Implementation.

     *

     * @return Always returns 0.

     */

    IMPORT_C virtual TInt ShortcutValueForNextList();

    /**

     * No Implementation.

     *

     * @param aValue Not Used.

     */

    IMPORT_C virtual void SetShortcutValueFromPrevList(TInt aValue);

    // pop-up positioning support

    /**

     * Gets the position and the size of the list box.

     *

     * @return A rectangle with the correct position data as 

     *         well as size data for the list box.

     */

    IMPORT_C TRect HighlightRect() const;

    /**

     * Checks whether background drawing is suppressed on item level i.e. each

	 *  list item doesn't draw its background.

	 *

	 * @since S60 5.0

	 * @return ETrue if background drawing is suppressed.

     */

     IMPORT_C TBool BackgroundDrawingSuppressed() const;

public: // from CCoeControl

    /**

     * From @c CCoeControl

     *

     * Gets the list of logical colours employed in the drawing of the control, 

     * paired with an explanation of how they are used. Appends the list to 

     * @c aColorUseList.

     *

     * @param aColorUseList List of logical colours.

     */

    IMPORT_C virtual void GetColorUseListL(

                        CArrayFix<TCoeColorUse>& aColorUseList) const; 

                        // not available before Release 005u

    /**

     * From @c CCoeControl

     *

     * Handles a change to the list box’s resources of type @c aType which are 

     * shared across the environment, colours or fonts for example.

     *

     * @param aType The type of resources that have changed.

     */

    IMPORT_C virtual void HandleResourceChange(TInt aType);         

                // not available before Release 005u

    /**

     * From @c CCoeControl

     *

     * Sets the control as ready to be drawn.

     *

     * The application should call this function on all controls that are not 

     * components in a compound control.

     *

     * The purpose of this function is that controls are not always ready to 

     * be drawn as soon as they have been constructed. For example, it may 

     * not be possible to set the control's extent during construction, but 

     * its extent should always be set before it is drawn. Similarly, if a 

     * control is to be made  invisible, this should be done before it is 

     * activated.

     * 

     * The default implementation sets a flag in the control to indicate it is 

     * ready to be drawn. If the control is a compound control, the default 

     * implementation also calls @c ActivateL() for all the control's components. 

     * To get the control's components it uses @c CountComponentControls() and 

     * @c ComponentControl(), which should be implemented by the compound control.

     * 

     * @c ActivateL() is typically called from the control's @c ConstructL() 

     * function.

     *

     * Notes:

     *

     * This function can be overridden. This is useful for doing late 

     * initialisation of the control, using information that was not available 

     * at the time the control was created. For example, a text editor might 

     * override @c ActivateL() and use it to enquire whether it is focused: if 

     * it is, it makes the cursor and any highlighting visible. At the time when 

     * the editor is created, it doesn't know whether or not it has keyboard 

     * focus.

     *

     * If overriding @c ActivateL(), the implementation must include a base 

     * call to @c CCoeControl's @c ActivateL(). 

     */

    IMPORT_C virtual void ActivateL();

    /**

     * From @c CCoeControl.

     *

     * Gets the input capabilities of the control and all its components.

     *

     * @return The input capabilities of the control.

     */

    IMPORT_C TCoeInputCapabilities InputCapabilities() const;

private:

    /**

    * From CAknControl

    */

    IMPORT_C void* ExtensionInterface( TUid aInterface );

protected:

    // Shortcuts need access to Incremental matching

    // The shortcuts will be used inside OfferkeyEventL().

    friend class AknListBoxShortCutsImplementation;

    // Avkon layout uses SetVerticalMargin, which is protected.

    friend class AknListBoxLayouts;

    /**

     * Responds to a change in focus.

     *

     * This is called whenever the control gains or loses focus, 

     * as a result of a call to @c SetFocus(). A typical use of 

     * @c FocusChanged() is to change the appearance of the control, 

     * for example by drawing a focus rectangle around it.

     *

     * The default implementation is empty, and should be 

     * overridden by the @c CCoeControl-derived class.

     *

     * @param aDrawNow Contains the value that was passed to it 

     *        by @c SetFocus().

     */

    IMPORT_C virtual void FocusChanged(TDrawNow aDrawNow);

    /**

     * Responds to changes to the size and position of the contents 

     * of this control.

     * 

     * For a simple control this might include text or graphics. 

     * For a compound control it sets the size and position of the 

     * components. It has an empty default implementation and should 

     * be implemented by the CCoeControl-derived class.

     *

     * The function is called whenever @c SetExtent(), @c SetSize(), 

     * @c SetRect(), @c SetCornerAndSize(), or @c SetExtentToWholeScreen() 

     * are called on the control. Note that the window server does not 

     * generate size-changed events: @c SizeChanged() gets called only as 

     * a result of calling the functions listed above. Therefore, if a 

     * resize of one control affects the size of other controls, it is 

     * up to the application to ensure that it handles the re-sizing 

     * of all affected controls. 

     */

    IMPORT_C virtual void SizeChanged();

    /**

     * Handles the change in case that the size of the view rectangle

     * for the list box changes.

     */

    IMPORT_C virtual void HandleViewRectSizeChangeL();

    /**

     * Gets the number of controls contained in a compound control.

     *

     * There are two ways to implement a compound control. One way is to

     * override this function. The other way is to use the @c CCoeControlArray

     * functionality (see the @c InitComponentArrayL method).

     *

     * @return The number of component controls contained by this control.

     */

    IMPORT_C virtual TInt CountComponentControls() const;

    /**

     * Gets an indexed component of a compound control.

     *

     * There are two ways to implement a compound control. One way is to 

     * override this function. The other way is to use the @c CCoeControlArray 

     * functionality (see the @c InitComponentArrayL method).

     *

     * Note: Within a compound control each component control is identified 

     * by an index, where the index depends on the order the controls were 

     * added: the first is given an index of 0, the next an index of 1, and

     * so on.

     *

     * @param aIndex The index of the control. 

     * @return The component control with an index of aIndex. 

     */

    IMPORT_C virtual CCoeControl* ComponentControl(TInt aIndex) const;

    // functions that implement first letter and incremental matching

    /**

     * Creates a buffer for checking how well two strings match up.

     */

    IMPORT_C void CreateMatchBufferL();  

    /**

     * Empties the match buffer .

     */

    IMPORT_C void ClearMatchBuffer() const;

    /**

     * Checks matching for the given character.

     *

     * @param aCode Character code.

     */

    IMPORT_C void MatchTypedCharL(TUint aCode);

    /**

     * Undoes changes from the match buffer that have been caused 

     * by the last match with a character.

     */

    IMPORT_C void UndoLastChar();

    /**

     * Checks if the last character matched with the string.

     *

     * @return @c ETrue if a match was found from the buffer with the character.

     */

    IMPORT_C TBool LastCharMatched() const;

    // functions needed for supporting scrollbars

    /**

     * Updates the position of this list box’s scroll bars’ thumbs to reflect 

     * the horizontal and vertical position of the list view within the list.

     */

    IMPORT_C virtual void UpdateScrollBarThumbs() const;

    /**

     * Get horizontal scroll granularity in pixels.

     * The granularity is the minimum size of a horizontal move of the client 

     * area.

     *

     * @return Grain size for horizontal scrolling in pixels.

     */

    IMPORT_C virtual TInt HorizScrollGranularityInPixels() const;

    /**

     * Gets the number of grains to move horizontally when a nudge button is 

     * tapped. 

     * For simple list boxes, this value is a fraction of the width of the 

     * client area. 

     *

     * @return Number of grains to move left or right on each nudge

     */

    IMPORT_C virtual TInt HorizontalNudgeValue() const;

    /**

     * Called by various functions of this class to ensure that the top 

     * item index is always a sane value. The implementation in @c CEikListBox 

     * tries to ensure the minimum amount of white space at the bottom of 

     * the list box. Note that this function does not affect the 

     * current item index.

     */

    IMPORT_C virtual void AdjustTopItemIndex() const;

    // navigation support functions

    /**

     * Simulates an arrow key event. 

     * 

     * If the list box flags include @c EMultipleSelection, this has the effect 

     * of pressing @c SHIFT with the arrow key represented by @c aKeyCode. 

     * Calls @c CEikListBox::OfferKeyEventL() with aKeyCode translated into a 

     * key event.

     *

     * @param aKeyCode A key code.

     */

    IMPORT_C void SimulateArrowKeyEventL(TKeyCode aKeyCode);

    /**