/*
* Copyright (c) 2002 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: 
*     Represents a combo box type control, used to implement the Series 60 
*     pop-up field.
*     
*
*/


#ifndef AKNPOPUPFIELD_H
#define AKNPOPUPFIELD_H

#include <eikcmobs.h>
#include <eiklbx.h>
#include <eikbctrl.h>
#include <eikcmbut.h>
#include <bamdesca.h>

#include <AknDesCArrayDecorator.h>
#include <AknListBoxLayoutDecorator.h>
#include <aknnotedialog.h>

class TResourceReader;
class CEikLabel;
class CEikCommandButton;
class CAknFormGraphicStyleListBox;
class MAknQueryValue;

class CAknPopupField;
class CAknPopupFieldExtension;

/** 
 * this interface should be implemented by classes that need to know
 * about events occurring in the popup field control
 */
class MAknPopupFieldObserver
	{
public:
	enum TAknPopupFieldEvent
		{
		EAknPopupFieldEventModeChange,
		EAknPopupFieldEventValueChange
		};
public:
    /**
     * Handles events from the popup field control, such as changes between
     * selection list mode and label mode.
     *
     * @param aPopupField pointer to the popup field control that generated
     *        the event.
     * @param aEventType the type of event.
     * @param aHint for possible future use.
     */
    virtual void HandlePopupFieldEventL(CAknPopupField* aPopupField,
                                        TAknPopupFieldEvent aEventType,
                                        TInt aHint)=0;
	};

/**
 * Represents a combo box type control, used to implement the Series 60 
 * pop-up field.
 */
class CAknPopupField :
	public CEikBorderedControl, 
	public MCoeControlObserver, 
	public MEikCommandObserver, 
	public MEikListBoxObserver
	{
protected:
	/**
	 * Specialises bitmap button to make the layout correct for popup field
	 */
	class CAknPopupFieldBitmapButton : public CEikBitmapButton
		{
	public:
		/**
		 * Constructor
		 */
		CAknPopupFieldBitmapButton();
		};
public:
    /**
     * Selection mode of the popup field.
     */
    enum EAknPopupFieldSelectionMode
        {
        /** 
         * Label mode. In Label mode popup field is minimized and popup field
         * looks identical to a list item. When it receives the selection key 
         * press it is changed to @c EAknPopupFieldSelectionListMode and the 
         * pre-defined list is displayed. 
         */
        EAknPopupFieldLabelMode,
		
        /** 
         * Selection list mode. In this selection mode pre-defined popup 
         * selection list is displayed.
         */    
		EAknPopupFieldSelectionListMode
		};

    /**
     * Form mode for the popup field.
     */
	enum EAknFormMode
        {
        /** View mode. */
        EAknFormModeView,

        /** Editable mode. */    
        EAknFormModeEdit,

        /** View mode with graphic. */
        EAknFormModeViewWideWithGraphic,

        /** View mode without graphic. */
        EAknFormModeViewWideWithoutGraphic,

        /** Edit mode with graphic. */
        EAknFormModeEditWideWithGraphic,

        /** Edit mode without graphic. */
		EAknFormModeEditWideWithoutGraphic
		};
public: 
	EAknPopupFieldSelectionMode SelectionMode() const { return iSelectionMode; }
	EAknFormMode FormMode() const { return iFormMode; }
    /**
     * C++ default constructor.
     */
	IMPORT_C CAknPopupField();

	/**
	 * Destructor
	 */
	IMPORT_C ~CAknPopupField();

    /** 
     * Handles 2nd phase construction.
     */
	IMPORT_C void ConstructL();

    /**
     * Sets a flag that enables user defined entry. Note that flag can also be 
     * set from resources, but this method allows behaviour to be changed at 
     * runtime.
     *
     * @param aAllows if @c ETrue sets a flag.
     */
	IMPORT_C void SetAllowsUserDefinedEntry(TBool aAllows);

    /**
     * Causes a list of pre-defined values to appear. 
     * Use this method to activate the pop-up field from a menu option command.
     * Note that the desired control must be focused on before it can be 
     * activated.
     */
	IMPORT_C void ActivateSelectionListL();

    /**
     * Used by the client to set the query value. It is used to represent the 
     * user defined query value in this popup field control.
     *
     * @param aValue Pointer to query value, ownership is not passed.
     */
	IMPORT_C void SetQueryValueL(MAknQueryValue* aValue);

    /**
     * Sets the font of the contained label.
     *
     * @param aFont Font definition used to set the font of the contained 
     *        label.
     */
	IMPORT_C void SetFont(const CFont* aFont);

    /**
     * Sets a flag that determines whether the indicators are shown.
     * In practice the indicators have the appearance of radio buttons.
     *
     * @param aShowIndicators If @c ETrue, indicators are displayed.
     */
	IMPORT_C void SetShowIndicatorsL(TBool aShowIndicators);

    /**
     * Number of lines used.
     *
     * @return Number of entries on the selection list. If selection list 
     *         is not active, 1 is returned.
     *	       NOTE that the number is limited by @c KAknMaxEditorLines.
     */
	IMPORT_C TInt NumLines() const;

    /**
     * Sets an observer of this class to receive events from popup field.
     * 
     * @param aObserver Pointer to the class that implements the observer 
     *        interface.
     */
	IMPORT_C void SetPopupFieldObserver(MAknPopupFieldObserver* aObserver);

    /**
     * Sets the note to be displayed when the selection list has no items 
     * available.
     * 
     * @param aResourceId Resource id for the note.
     * @param aTimeout = CAknNoteDialog::EShortTimeout Timeout for the note. 
     * @param aTone = CAknNoteDialog::ENoTone Tone for the note.
     */
	IMPORT_C void SetEmptyListNoteL(TInt aResourceId,
									CAknNoteDialog::TTimeout aTimeout = CAknNoteDialog::EShortTimeout,
									CAknNoteDialog::TTone aTone = CAknNoteDialog::ENoTone);

    /**
     * Sets the empty list note text. This note is displayed when the 
     * selection list has no items available.
     * 
     * @param aEmptyText The empty list note text.
     */
    IMPORT_C void SetEmptyTextL(const TDesC& aEmptyText);

    /**
     * Sets the text to be added to the bottom of the array to enter user 
     * defined data.
     * 
     * @param aOtherText Text to the bottom of the selection array.
     */
	IMPORT_C void SetOtherTextL(const TDesC& aOtherText);

    /**
     * Sets the text for view state when none of the elements in the
     * list are available. 
     *
     * @param aInvalidText The invalid text.
     */
	IMPORT_C void SetInvalidTextL(const TDesC &aInvalidText);

    /**
     * Closes the selection list 
     *
     *  @since v5.2 
     */
    IMPORT_C void CloseSelectionListL();

public: // from CCoeControl

    /** 
     * From @c CCoeControl.
     *
     * Handles key events.
     *
     * @param aKeyEvent The key event. 
     * @param aType The type of key event.
     * @return Indicates whether or not the key event was used by this control.
     */
	IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);

    /** 
     * From @c CCoeControl.
     * 
     * Constructs the control from a resource file.
     *
     * @param aReader The resource reader pointing to the popup field resource.
     */
	IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

    /** 
     * From @c CCoeControl.
     *
     * Determines the minimum size of the control.
     * 
     * @return The minimum size required by the control.
     */
	IMPORT_C TSize MinimumSize();

    /**
     * From @c CCoeControl.
     *
     * Handles a change to the control's resources.
     *
     * @param aType The type of the resource change. 
	 */
	IMPORT_C void HandleResourceChange(TInt aType);

    /**
     * From @c CCoeControl.
     *
     * Handles pointer events of popup field list.
     *
     * @param aPointerEvent The pointer event to be handled.
     */
    IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
public:
    /**
     * Sets the maximium number of lines that can be displayed.
     *
     * @param aMaxNoLines The maximum number of lines.
     */
	IMPORT_C void SetMaxNumberOfLinesPermitted(TInt aMaxNoLines);
public:

    /**
     * Sets a form field rectangle so that a popup field can correctly position
     * the label.
     *
     * @param aFormFieldRect The form field rectangle.
     */
	IMPORT_C void SetFormFieldRect(TRect aFormFieldRect);

protected: // from MCoeControlObserver
	
    /** 
     * From @c MCoeControlObserver.
     *
     * Handles an event from an observed control.
     *
     * @param aControl The control that sent the event.
     * @param aEvent The event type. 
     */
	IMPORT_C void HandleControlEventL(CCoeControl* aControl,TCoeEvent aEvent);
protected: // from MEikCommandObserver
	
    /**
     * From @c MEikCommandObserver.
     *
     * Processes events from the softkeys. Responds to @c EAknSoftkeyOk and 
     * @c EAknSoftkeyCancel to accept or cancel the pop-up.
     * 
     * @param aCommandId Event Id from the soft-key.
     */
	IMPORT_C void ProcessCommandL(TInt aCommandId);	
protected: // From MEikListBoxObserver

    /**
     * From @c MEikListBoxObserver.
     *
     * Processes key events from the listbox. Responds to 
     * @c EEventEnterKeyPressed to accept the pop-up.
     * 
     * @param aListBox Listbox being observed.
     * @param aEventType Event observed.
     */
    IMPORT_C void HandleListBoxEventL(CEikListBox* aListBox, 
                                      TListBoxEvent aEventType);
protected: // from CCoeControl

    /** 
     * From @c CCoeControl.
     *
     * Gets the number of controls contained in a compound control.
     *
     * @return The number of component controls contained by this control.
     */
	IMPORT_C TInt CountComponentControls() const;

    /** 
     * From @c CCoeControl.
     *
     * Gets an indexed component of a compound control.
     * 
     * @param aIndex Control index.
     * @return The component control with an index of @c aIndex. 
     */
	IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;

    /** 
     * From @c CCoeControl.
     *
     * Responds to changes to the size and position of the contents of this 
     * control.
     */
	IMPORT_C void SizeChanged();

    /**
     * From @c CCoeControl.
     *
     * Responds to a change in focus.
     *
     * @param aDrawNow Contains the value that was passed to it by 
     *        @c SetFocus(). 
     */
    IMPORT_C void FocusChanged( TDrawNow aDrawNow );

    /**
     * From @c CEikBorderedControl.
     *
     * Called by the framework to draw the control.
     *
     * @param aRect Rectangle in which the Cone framework believes drawing is 
     *        needed.
     */
	IMPORT_C void Draw(const TRect& aRect) const;

private: // from CCoeControl
	IMPORT_C void Reserved_1();
	IMPORT_C void Reserved_2();

private:
    /**
    * From CAknControl
    */
    IMPORT_C void* ExtensionInterface( TUid aInterface );

protected: // personal

    /**
     * Construction tasks common to both a normal construction and a construction 
     * from a resource. Used from @c ConstructL() and 
     * @c ConstructFromResourceL().
     */
	void CommonConstructL();
protected: // from MObjectProvider

    /**
     * From @c CCoeControl.
     *
     * Retrieves an object of the same type as that encapsulated in @c aId.
     *
     * @param aId An encapsulated object type ID.
     * @return Encapsulates the pointer to the object provided. 
     *         Note that the encapsulated pointer may be NULL.
     */
	IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
private: // personal

    /** 
     * Create the label that will show the currently selected value.
     *
     */
	void ConstructLabelL();

	/** 
	 * Create the command button that will be used to show the other choices indicator.
	 *
	 */
	void ConstructCommandButtonL();

	/** 
	 * Create the selection list box that will fill the expanded popup field
	 *
	 */
	void ConstructSelectionListL();

	/** 
	 * setup the scroll bar within the selection list box
	 *
	 */
	void SetUpScrollBarL();

	/** 
	 * set the scroll bar selection
	 *
	 */
	void SetScrollBarSelectionL();

	/** 
	 * Set up the bitmap array for the "not pushed" and "pushed in" states
	 *
	 */
	void InitialiseRadioButtonBitmapsL();

	/**
	 * Handles the case where the selection list is closed. If necessary, 
	 * update the value of the text label that is displayed.
	 * 
	 * @return TBool ETrue always
	 */
	TBool HandleInteractionConfirmedL();

	/**
	 * Create the popup list. Warn the user if there are no entries in the list.
	 *
	 */
	void CreatePopoutL();

	/**
	 * Destroy the popup list and remove it from the stack
	 *
	 */
	void DestroyPopout();

	/**
	 * Checks to see if the popupfield is empty
	 *
	 */
	TBool IsEmpty() const;
	/**
	 * Checks to see if the popupfield is invalid
	 *
	 */
	TBool IsInvalid() const;
	/**
	 * Handles a horizontal key event
	 *
	 * @return TKeyResponse returns either EKeyWasConsumed
	 *                       or EKeyWasNotConsumed
	 */
	TKeyResponse HandleHorizontalKeyEventL(TUint aKeyEventCode);
private: // Avkon

    /**
     * Creates the CBA for use when the selection list is active
     */
	void CreateCbaL();

	/**
	 * Configures the decoration according to the currently set flags.
	 * Should be called whenever the flags are changed. 
	 *
	 */
	void ConfigureDecorator();

	/**
	 * Configures the layout decoration according to the radio button flag
	 * Should be called whenever the flags are changed. 
	 *
	 */
	void ConstructLayoutDecoratorL();

	/**
	 * display a note when the selection list has no items available
	 *
	 */
	void ShowEmptyListNoteL();

	/**
	 * Re-defined method of the base class. Gets called when the 
	 * user tries to select a value. If required, an editor is created to 
	 * allow the user to input the user defined value. Otherwise, the
	 * normal selection behaviour of popup list is activated.
	 *
	 * @param aAccept	If ETrue, popup list was accepted; 
	 *								if EFalse, popup list was cancelled
	 *
	 */
	void AttemptExitL(TBool aAccept);

	/**
	 * Changes the mode of the popupfield to one of
	 * the EAknPopupFieldSelectionMode's
	 */
	void ChangeMode(EAknPopupFieldSelectionMode aNewMode);

private: // async 
	static TInt AttemptExitCallbackL(TAny* aThis);
	void DoAttemptExitL();
	void DoSizeChangedL();
protected:
	// the following members are owned
    /**
     * Label of the popup field.
     * Own.
     */
	CEikLabel* iLabel;

    /**
     * Bitmap button for the popup field.
     * Own.
     */
	CAknPopupFieldBitmapButton* iButton;

    /**
     * List box for the popup field usage.
     * Own.
     */
	CAknFormGraphicStyleListBox* iSelectionList;

    /**
     * Contains a popup field selection array and a leading text that will be 
     * inserted before the text from the descriptor array entry.
     * Own.
     */
	CAknListBoxLayoutDecorator* iLayoutDecorator;

    /**
     * Button group container for the popup field.
     * Own.
     */
	CEikButtonGroupContainer* iCba;

    /**
     * Active object for calling @c AttemptExitCallbackL asynchronously.
     * Own.
     */
	CAsyncCallBack* iAttemptExitAsync;

	// the following fields are reflected in the POPUP_FIELD resource structure
    /**
     * Flags for the popup field.
     */
    TInt iFlags;

    /**
     * Maximum line width.
     */
    TInt iWidth;

    /**
     * Text to the bottom of the selection array.
     * Own.
     */
    HBufC* iOtherText;

    /**
     * The empty list note text.
     * Own.
     */
    HBufC* iEmptyText;

    /**
     * The invalid text. Used in the view state when none of the elements in the
     * list are available. 
     * Own.
     */
    HBufC* iInvalidText;

    /**
     * Resource id for the empty note.
     */
	TInt iEmptyNoteResourceId;
	
	// the following members are not owned
    /**
     * Query value for the popup field.
     * Not own.
     */
	MAknQueryValue* iValue;

    /**
     * Observer for receiving events from the popup field.
     * Not own.
     */
	MAknPopupFieldObserver* iObserver;

	// the following values are member variables
    /**
     * Enumeration representing form mode values.
     */
    EAknFormMode iFormMode;

    /**
     * Timeout for the empty tone.
     */
    CAknNoteDialog::TTimeout iEmptyNoteTimeout;

    /**
     * Tone for the empty note.
     */
    CAknNoteDialog::TTone iEmptyNoteTone;

    /**
     * Selection array for the popup field.
     */
    TAknDesCArrayDecorator iDecorator;

    /**
     * Enumeration representing selection mode values.
     */
    EAknPopupFieldSelectionMode iSelectionMode; 

    /**
     * Maximum number of items in selection array.
     */
	TInt iMaxNoLines;
	// NOTE: use Extension() to extend this class.
private:
	CAknPopupFieldExtension* iExtension;
    TInt iSpare[3];
	};

#endif // AKNPOPUPFIELD_H