/*
* Copyright (c) 2005 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:  CAknChoiceList - Choice list for S60 
*
*/



#ifndef AKNCHOICELIST_H
#define AKNCHOICELIST_H

// includes 
#include <akncontrol.h>
#include <coecobs.h>

// forward declarations  
class CAknButton;
class CEikLabel;
class CAknChoiceListPopup;
class CAknChoiceListPopupList;
class CAknsFrameBackgroundControlContext;
class CAknInfoPopupNoteController;

// Class declaration

/**
 *  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. 
 *  @lib avkon.lib
 *  @since S60 5.0
 */ 
class CAknChoiceList : public CAknControl, public MCoeControlObserver
    {   
public:

    /* Flags for choice list types and positioning */   
    enum TAknChoiceListFlags
        {
        /* Using default choice list with popup list */
        EAknChoiceListWithCurrentSelection = 0x01,
        /* Using user defined button to open choice list */
        EAknChoiceListWithoutCurrentSelection = 0x02,
        /* Popup positioning flags */
        EAknChoiceListPositionLeft = 0x04,   
        EAknChoiceListPositionRight = 0x08,   
        EAknChoiceListPositionBottom = 0x10  
        };    
     
     /* Tooltip positioning */
     enum TTooltipPosition
        {
        EPositionTop = 1, /* Tooltip alignment vertically to top */
        EPositionBottom, /* Tooltip alignment vertically to bottom */
        EPositionLeft, /* Tooltip alignment horizontally to left */
        EPositionRight /* Tooltip alignment horizontally to right */
        };
public: 

    /**
     * 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. 
     * @param aParent the parent control for choice list
     * @param aItemArray Array of items to be shown in the choicelist. Transfers ownership.
     * @param aFlags Flags for choice list type and positioning
     * @param aButton user defined button for choicelist. Button replaces the typical choice list. 
     * Transfers ownership.
     */
    IMPORT_C static CAknChoiceList* NewL( CCoeControl* aParent, CDesCArray* aItemArray, TInt aFlags = EAknChoiceListWithCurrentSelection, CAknButton* aButton = NULL );

    /**
     * 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. 
     * @param aParent the parent control for choice list
     * @param aItemArray Array of items to be shown in the choicelist. Transfers ownership.
     * @param aFlags Flags for choice list type and positioning
     * @param aButton user defined button for choicelist. Button replaces the typical choice list. 
     * Transfers ownership.
     */
    IMPORT_C static CAknChoiceList* NewLC( CCoeControl* aParent, CDesCArray* aItemArray, TInt aFlags = EAknChoiceListWithCurrentSelection, CAknButton* aButton = NULL );
    
    /**
     * Destructor
     */
    ~CAknChoiceList();
    
    /**
     * Open choice list.
     * Choicelist can be opened with this function. If the choicelist is already
     * open nothing will happen.
     * @return KErrNone if succeeded
     */
    IMPORT_C TInt ShowChoiceListL();
    
    /**
     * Set certain index of the choice list array to selected
     * @param aIndex Index of the array to be selected as default
     */
    IMPORT_C void SetSelectedIndex( const TInt aIndex );
    
    /**
     * Returns selected index from the choice list array
     * @return TInt selected index
     */
    IMPORT_C TInt SelectedIndex() const;
    
    /**
     * 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.
     * @param aArray Array of text items to be inserted as the content for choice list
     */
    IMPORT_C void SetItems( CDesCArray* aArray );
    
    /**
     * Set certain array as the contents of the choice list. 
     * It's recommended to use CDesCArrayFlat. 
     * @param aResourceId Resource id for an array. 
     */
    IMPORT_C void SetItemsL( TInt aResourceId );
    
    /**
     * Add a text as a new item in the end of the choice list array. 
     * @param aDesC Pointer to a descriptor item that should be appended to the array. 
     * Transfers ownership.
     * @return index in the choicelist array for newly added item. 
     */
    IMPORT_C TInt AddItemL( const TDesC* aDesC );
    
    /**
     * Removes an item from the choice list array with the given index. 
     * @param aIndex index for the item that should be removed from the choice list array
     */
    IMPORT_C void RemoveItem( const TInt aIndex );    
    
    /**
     * Sets flags for choice list.
     * Choice lists position can be changed in runtime with right flags. 
     * @param aFlags The flags to be set for choice list
     */        
    IMPORT_C void SetFlags( const TInt aFlags );
    
    /**
     * Return choice list specific flags.
     * @return choice list flags
     */
    IMPORT_C TInt Flags() const;
    
    /**
     * Set the button that launches choice list opening.
     * @param aButton The Button for opening choice list control 
     */
    IMPORT_C void SetButtonL( CAknButton* aButton );
    
    /**
     * Hide choice list popup. Current selection is not selected.
     */
    IMPORT_C void HideChoiceList();

    /**
     * Set text for tooltip
     * @param aText The text shown as tooltip
     */
    IMPORT_C void SetTooltipTextL( const TDesC& aText );

    /**
     * Set the delays for tooltip
     * @param aBeforeTimeout The delay in milliseconds before tooltip
     *        is shown. The default is 150 milliseconds
     * @param aInViewTiemout The interval in milliseconds how long the
     *        tooltip is displayed. The default is 3000 milliseconds.
     */
    IMPORT_C void SetTooltipTimeouts( const TInt aBeforeTimeout,
                                      const TInt aInViewTimeout );
    /**
     * Set the postion of tooltip
     * @param aPosition The position expressed with TTooltipPosition
     *        The default is EPositionTop
     */                                      
    IMPORT_C void SetTooltipPosition( const TTooltipPosition aPosition );
    
// From CCoeControl
    
    /**
     * From CCoeControl. Returns the control inside control with given index.
     * @param aIndex Index of a control be returned
     * @return A Pointer to control.
     */
    IMPORT_C CCoeControl* ComponentControl( TInt aIndex ) const;

    /**
     * From CCoeControl. Returns number of controls inside the control.
     * @return Number of component controls.
     */
    IMPORT_C TInt CountComponentControls() const;

    /**
     * From CCoeControl. Returns the Minimum size needed by the control. 
     * @return TSize minimum size. 
     */
    IMPORT_C TSize MinimumSize();    
    
    /**
     * From CCoeControl. Handles a change to the control's resources.
     * @param aType A message UID value.   
     */
    IMPORT_C void HandleResourceChange( TInt aType );    
    
    /**
     * From CCoeControl. Handles key events.
     * @param aKeyEvent the key event    
     * @param aType The type of key event
     * @return Indicates whether or not the keyevent was used by this control   
     */
    IMPORT_C TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType );    
    
    /**
     * From CCoeControl. Draws control to given area
     * @param aRect The rectangle that should be drawn by the control. 
     */
    IMPORT_C void Draw( const TRect& aRect ) const;
    

    /**
    * from CCoeControl 
    *
    * Responds to changes in the position of a control.
    *
    */
    IMPORT_C virtual void PositionChanged();


// From MCoeControlObserver
    
    /**
     * 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
     * @param aControl The control that sent the event.
     * @param aEventType The event type. 
     */
    IMPORT_C void HandleControlEventL( CCoeControl* aControl, TCoeEvent aEventType );

public: 
    // new functions
    /**
    * 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.
    * @param aIndex The array index where new item is going to be inserted.
    * @param aText Items text
    * @return The index of newly inserted item. Index can be other than passed if given index 
    * is out of array bounds
    */
    IMPORT_C TInt InsertItemL( const TInt aIndex, const TDesC& aText );
    
protected: 

// from CCoeControl         
    
    /**
     * From CCoeControl. Sets the size and position of the component. 
     */
    void SizeChanged();
    
    /**
     * From CCoeControl. Handles pointer events
     * @param aPointerEvent the pointer event be be handled.
     */
    void HandlePointerEventL( const TPointerEvent& aPointerEvent );    

private:

    /**
     * C++ Default Constructor 
     */
    CAknChoiceList(); 

    /**
     * 2nd phase constructor
     * @param aParent the parent control for choice list
     * @param aItemArray Array of items to be shown in the choicelist
     * @param aFlags Flags for choice list type and positioning
     * @param aButton user defined button for choicelist. Button replaces the typical choice list
     */
    void ConstructL( CCoeControl* aParent, CDesCArray* aItemArray, TInt aFlags, CAknButton* aButton );    
    
    /**
     * Construct the typical choice list that open with arrow and show current selection 
     * even in the closed state.
     */
    void ConstructTypicalChoiceListL();
    
    /**
     * Calculate positioning for the opened choice list popup by the given position flag.
     */
    void SetPopupRect();
    
    /**
     * Update labels text 
     */
    void UpdateLabelL();

    /**
     * Show tooltip text
     */
    void ShowTooltipL();

    
private: // data

    /**
     * Flags for choice list
     */
    TInt iFlags;
    
    /** 
     * Currently selected index of an item that is stored in choice list array.
     */
    TInt iSelectedIndex;
    
    /** 
     * Used to store if the choice list is closed mode or not. 
     */
    TBool iIsClosed;    
    
    /**
     * Button for opening the choicelist. If choice lists type is 
     * EAknChoiceListWithCurrentSelection this is the arrow button. 
     * Otherwise this is user defined.
     * Own.
     */
    CAknButton* iButton;
    
    /**
     * Label that shows the currently selected item if choice list type is 
     * EAknChoiceListWithCurrentSelection. Otherwise this will not be used. 
     * Own.
     */
    CEikLabel* iLabel;

    /**
     * Array that stores all the items in the choice list. 
     * Own.
     */
    CDesCArray* iArray;    
    
    /**
     * Pointer to current choice list popup window. Popup window is 
     * used only internally and it cannot be accessed from outside.
     * Own.
     */
    CAknChoiceListPopup* iPopup;

    /**
     * Component used to show tooltip
     * Own.
     */
    CAknInfoPopupNoteController* iTooltip;

    /**
     * Stores the text for tooltip
     * Own.
     */
    HBufC* iTooltipText;

    /**
     * Stores the delay in milliseconds when the tooltip is shown
     * Own.
     */
    TInt iTooltipWaitInterval;

    /**
     * Stores the time interval in milliseconds how long the tooltip is shown
     * Own.
     */
    TInt iTooltipInViewInterval;

    /**
     * Stores the tool tip positioning
     * Own.
     */
    TTooltipPosition iTooltipPosition;

    
    };    

#endif // AKNCHOICELIST_H

// end of file