/*

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

 *

 * Support for popup setting item lists.  THe MAknQueryValue abstract type is 

 * used to carry the state of the selection. 

 *

 * This file also contains the definition for the contained editor of the setting page,

 * CAknPopupSettingList  

 *

 *

 */

 #ifndef __AKNPOPUPSETTINGPAGE_H__

 #define __AKNPOPUPSETTINGPAGE_H__ 

 #include <AknQueryValue.h>

 #include <AknQueryValueText.h>

 #include <AknListBoxSettingPage.h>

 #include <AknDesCArrayDecorator.h>

 #include <AknListBoxLayoutDecorator.h>

 class CAknPopupSettingList;

 class CAknPopupSettingListExtension;

 /** 

  * This interface should be implemented by classes that need to know

  * about events occurring in the popup field control

  */

 class MAknPopupSettingListObserver

 	{

 public:

 	/**

 	* Event types

 	*/

 	enum TAknPopupSettingListEvent

 		{

 		EAknPopupSettingSelectionAndRequestAccept,

 		EAknPopupSettingSelectionAndStayOpen,

 		EAknPopupSettingSelectionAndClose

 		};

 public:

 /**

  * Handle events from the popup field control, such as when it changes between

  * selection list mode and label mode.

  *

  * Implementations of this observer routine should perform a base call to this specific

  * method, in order to pick up any default re-layout actions.

  *

  * @param aPopupSettingList pointer to the popup field control that generated the event

  * @param aEventType the type of event

  * @param aHint for possible future use

  *

  */

 	virtual void HandlePopupSettingListEventL(	CAknPopupSettingList* aPopupSettingList, 

 												TAknPopupSettingListEvent aEventType, 

 												TInt aHint)=0;

 	};

 /**

  *

  * Represents menu list that appears in a popped up setting item

  */

 class CAknPopupSettingList :

 	public CAknSetStyleListBox,

 	public MEikListBoxObserver

 	{

 protected:

 public:

  /** 

  * Standard constructor.

  */

 	IMPORT_C CAknPopupSettingList();

 /** 

  * Destructor.

  *

  */

 	IMPORT_C ~CAknPopupSettingList();

 /** 

  * 2nd phase construction

  *

  */

 	IMPORT_C void ConstructL();

 /**

  * Sets 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 ETrue, set flag; if EFalse, clear flag.

  */

 	IMPORT_C void SetAllowsUserDefinedEntry(TBool aAllows);

 /**

  * Used by the client to set the query value used to represent the user defined 

  * value belonging to this popup field control.

  *

  * @param aValue	pointer to value, ownership is not passed

  *

  */

 	IMPORT_C void SetQueryValueL(MAknQueryValue* aValue);

 /**

  * Set the flag which determines whether the indicators are shown

  * In practice the indicators have the appearance of radio buttons

  *

  * @param aShowIndicators	

  *		If ETrue, indicators are displayed; 

  *		if EFalse, indicators are not displayed

  *

  */

 	IMPORT_C void SetShowIndicators(TBool aShowIndicators);

 /**

  * number of lines used

  *

  * @return number of lines being currently displayed by control, which is determined 

  *		by the number of entries on the selection list, and whether the selection list is active.

  *		NOTE that the number is limited by KAknMaxLinesOnOnePage

  *

  */

 	IMPORT_C TInt NumLines() const;

 /**

  * set an observer of this class to receive events from popup setting list

  * 

  * @param aObserver pointer to the class that implements the observer interface,

  *

  */

 	IMPORT_C void SetPopupSettingListObserver(MAknPopupSettingListObserver* aObserver);

     /**

      * Selects current item.

      * 

      * @internal

      */

     void SelectCurrentItemL();

     /**

 	 * Returns index of currently selected list item.

 	 *

 	 * @return Currently selected item's index.

 	 */

     TInt CurrentSelection() const;

 public: 

 /** 

  * from CCoeControl

  * Construct from resources.

  * @param aReader	constucted and positioned TResourceReader&

  */

 	IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

 protected:

 /**

  * Create the popup list. 

  *

  */

 	IMPORT_C void CreateMenuListL();

 /**

  * Causes the 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 have the focus before it can be activated.

  *

  */

 	IMPORT_C void ActivateMenuListL();

 /**

  *

  * This routine sets up the text arrays for the menu list

  *

  */

 	IMPORT_C void ConfigureMenuListL();

 /**

  * All this does now is remove this from the stack

  *

  */

 	IMPORT_C void DestroyMenuList();

 public:

     /**

     * From CCoeControl. Handles pointer event

     * @param aPointerEvent Pointer event to be handled

     */

     IMPORT_C void HandlePointerEventL( const TPointerEvent& aPointerEvent );

     IMPORT_C void HandleResourceChange(TInt aType);

 private:

     /**

     * From CAknControl

     */

     IMPORT_C void* ExtensionInterface( TUid aInterface );

 protected: 

 /**

  * From MEikListBoxObserver

  * Processes key events from the listbox. Responds to EEventEnterKeyPressed to accept

  * the pop-up.

  *

  * @param	aListBox	Listbox being observed

  * @param	aEventType	Event observed

  *

  *

  * This implementation is vestige of former implementation when the listbox was wrapped up,

  * not derived from. Currently observing itself..

  *

  */

 	IMPORT_C void HandleListBoxEventL(CEikListBox* aListBox, TListBoxEvent aEventType);

 private: // from CCoeControl

 	IMPORT_C void Reserved_1();

 	IMPORT_C void Reserved_2();

 private: 

 	void CommonConstructL();

 	void SetUpSelectionListL();

 /** 

  * Set up the bitmap array for the "not pushed" and "pushed in" states

  *

  */

 	void InitialiseRadioButtonBitmapsL();

 private: 

 /**

  * 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 "has buttons" flag

  * Should be called whenever the flags are changed. 

  *

  */

 	void ConstructLayoutDecoratorL();

 private:

 	// the following members are owned

 	TAknDesCArrayDecorator iDecorator;

 	CAknListBoxLayoutDecorator* iLayoutDecorator;

 	// the following fields are reflected in the POPUP_SETTING_LIST resource structure

 	TInt iFlags;

 	HBufC* iOtherText;

 	TInt iCurrentSelection;

 	// elements to hold info regarding "new Item"- produced setting page

 	TInt iNewItemSettingPageResourceId;

 	TInt iNewItemEditorType;

 	TInt iNewItemEditorControlResourceId;

 	// the following members are not owned

 	MAknQueryValue* iValue;

 	MAknPopupSettingListObserver* iPopupSettingListObserver;

 	//TInt iSpare_1;

 	CAknPopupSettingListExtension* iExtension;

 	};

 /**

 * Interface for the setting page containing a menu list with a Query value data model 

 * This is the more generic of the list-style setting pages. 

 *

 */

 class CAknPopupSettingPage : 

 	public CAknListBoxSettingPage, 

 	public MAknPopupSettingListObserver

 	{

 public:

 	/**

 	* C++ constructor.  This constructor uses just the setting page resource Id to 

 	* construct the setting page, using listbox resource contained in the setting page 

 	* resource.

 	* @param	aResourceId		a resource identifier for a AVKON_SETTING_PAGE resource

 	* @param	aQueryValue		a reference to a query value object

 	*/

 	IMPORT_C CAknPopupSettingPage(TInt aResourceID, MAknQueryValue& aQueryValue );

 	/**

 	 * Constructor that allows separate setting page and editor resources

 	 * 

 	 * This constructor allows the use of setting page using only the editor resource.  Other combinations are also possible

 	 *

 	 * In all cases the number (if supplied i.e. <> 0 ) is used.  

 	 *

 	 *		Editor Resource		Setting Page Resource

 	 *			present				present				Both are used (but text & number overridden)

 	 *			 = 0					present				Editor resource is used via SP resource (Effectively like the other constructor)

 	 *			present				= 0					Default Avkon SP resource if used + this editor resource

 	 *			 = 0					= 0					uses default resource for both SP and editor. This is OK if:

 	 *	 i) control type is present, 

 	 *  ii) a default resource exists ( OK for text, integer, date, time, duration )

 	 *

 	 * Note: THe first argument is a TDesC* (rather than TDesC&) because the other constructor

 	 * cannot initialize such a member without allocation or having an internal dummy buffer.

 	 *

 	 * Rules for text and numbers: The rules are the same for both:  (non-zero length) text or number other 

 	 * than EAknSettingPageNoOrdinalDisplayed if given in this constructor will not override resource 

 	 * (unless that is zero length or EAknSettingPageNoOrdinalDisplayed).  Note, however, that text or number given via the 

 	 * specific API for setting them, WILL override resource.

 	 * It is assumed that number from resource is very rare.  Special text is somewhat more likely.

 	 * 

 	 * @param aSettingTitleText	Text at top of setting pane

 	 * @param aSettingNumber		Number at top left (if present)

 	 * @param aControlType			Determines the type constructed and how its resource is read

 	 * @param aEditorResourceId	Editor resource to use in the setting page (if present)

 	 * @param aSettingPageResourceId		Setting Page to use (if present)

 	 * @param aQueryValue			reference to a query value object

 	 */

 	IMPORT_C CAknPopupSettingPage(	const TDesC* aSettingTitleText, 

 								TInt aSettingNumber, 

 								TInt aControlType,

 								TInt aEditorResourceId, 

 								TInt aSettingPageResourceId,

 								MAknQueryValue& aQueryValue);

 	/**

 	* 2nd stage construction method.  Type specific work is done here; most of the setting

 	* page constuction is performed in a call the base contstruction of CAknSettingPage

 	*

 	*/

 	IMPORT_C virtual void ConstructL();

 /**

  * Access to the contained listbox (inside popup setting list)

  *

  * @return	CAknSetStyleListBox* pointer to the listbox used in the setting page; Does not transfer ownership

  */

 	IMPORT_C CAknSetStyleListBox* ListBoxControl() const;

 /** 

  * Access to the editor control

  * 

  * @return	CAknPopupSettingList* a reference to the contained "editor" as a listbox; no ownership transferred

  */

 	IMPORT_C CAknPopupSettingList* PopupSettingListBox() const;

 /**

  *  From MAknPopupSettingListObserver

  * Handle events from the popup field control, such as when it changes between

  * selection list mode and label mode.

  *

  * @param aPopupSettingList pointer to the popup field control that generated the event

  * @param aEventType the type of event

  * @param aHint for possible future use

  *

  */

 	IMPORT_C virtual void HandlePopupSettingListEventL(CAknPopupSettingList* aPopupSettingList, 

 		TAknPopupSettingListEvent aEventType, TInt aHint);

 /**

 * Can be used dynamically to set a new query value.  This manages the setting up of the new

 * PopupSettingList and its listbox, and also the resizing and redrawing of the setting page

 * Note that all former query value objects and its associated arrays are owned by the client

 * and if no longer used, should be deleted.

 * 

 * @param MAknQueryValue* aQueryValue - the new value; no transfer of ownership

 */

 	IMPORT_C void UpdateQueryValueL( MAknQueryValue* aQueryValue );

 /**

  *	From CCoeControl

  */

     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

 protected:

 /**

 * C++ destructor

 */

 	IMPORT_C virtual ~CAknPopupSettingPage();

 /**

  * This is required to give access to the QueryValue data member from 

  * re-implementations of the popup setting page

  *

  * @return MAknQueryValue* a pointer to the query value object

  *

  */

 	IMPORT_C MAknQueryValue* QueryValue() const;

 /**

  * This method should be implemented in listbox classes to move the selection in 

  * listbox editors prior to exiting from the setting page

  *

  */

 	IMPORT_C virtual void SelectCurrentItemL();

 //

 // CoeControl Framework and reserved methods

 //

 protected:

 /**

  * Writes the internal state of the control and its components to aStream.

  * Does nothing in release mode.

  * Designed to be overidden and base called by subclasses.

  *

  * @param	aWriteSteam		A connected write stream

  */	

 	IMPORT_C virtual void WriteInternalStateL(RWriteStream& aWriteStream) const;

 /**

  *	Reserved method derived from CCoeControl

  */

 	IMPORT_C virtual void Reserved_2();

 private:

     /**

     * From CAknControl

     */

     IMPORT_C void* ExtensionInterface( TUid aInterface );

 /**

  * New reserved methods for CAknSettingPage hierarchy

  */ 

 private: 

 	IMPORT_C virtual void CAknSettingPage_Reserved_1();

 	IMPORT_C virtual void CAknSettingPage_Reserved_2();

 private:

 /**

  * New reserved method from CAknListBoxSettingPage 

  *

  */

 	IMPORT_C virtual void CAknListBoxSettingPage_Reserved_1();

 private:

 	// The objects pointed to or referenced by this is not owned

 	MAknQueryValue& iQueryValue;

 	TInt iSpare_1;

 	TInt iSpare_2;

 };

 #endif