/*

* 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