/*

 * 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 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 setting page (setting item editing) UI

 *

 */

 #ifndef __AKNSETTINGPAGE_H__

 #define __AKNSETTINGPAGE_H__ 

 #include <AknControl.h>

 #include <eikdef.h>

 #include <eikbtgpc.h>

 // For menu support

 #include <eikmenub.h>

 #include <eikmenup.h>

 #include <eikmobs.h>

 // for layout support

 #include <aknutils.h>

 // for navipane support (hint text)

 #include <aknnavi.h>

 //

 // Forward declarations

 //

 class CEikLabel;

 class CAknSettingPageSkinsInfo;

 class MAknsControlContext;

 class CAknsFrameBackgroundControlContext;

 class CAknSettingPageExtension;

 // Used as the return value of SettingId() if not yet set.

 // This because the Id might want to be the index of a 0-based array

 const TInt KAknSettingPageNoIdSet = -1;

 class CAknSettingPage;

 // This class is used as a means of notifying change in settings.

 class MAknSettingPageObserver 

 {

 public:

 enum TAknSettingPageEvent

 	{

 	EEventSettingChanged,

 	EEventSettingCancelled,

 	EEventSettingOked

 	};

 public:

 /**

  * Handles an event of type aEventType reported by the Setting Page to this observer.

  */

 virtual void HandleSettingPageEventL(CAknSettingPage* aSettingPage,TAknSettingPageEvent aEventType )=0;

 };

 class CAknSettingPage : public CAknControl, public MCoeControlObserver, public MEikMenuObserver

 {

 public:

 /**

 * This enumeration is passed in the ExecuteLD() method to control how often the setting page 

 * updates the externally held client object

 */

 	enum TAknSettingPageUpdateMode

 		{

 		EUpdateWhenChanged,

 		EUpdateWhenAccepted

 		};

 /**

 * This enumeration is used to select the type and IIDs for the various classes defined in the 

 * Skins LAF spec for "Opened Setting Items"

 */

 	enum TEditedItemSkinClass

 		{

 		ESettingPageSkinEditedItemClassValueItemList,

 		ESettingPageSkinEditedItemClassVolume,

 		ESettingPageSkinEditedItemClassSlider,

 		ESettingPageSkinEditedItemClassTextEntry,

 		ESettingPageSkinEditedItemClassCodeDateTimeEntry

 		};

 /**

  * Simple contructor for using a single setting page resource which itself gives all 

  * the setup

  */

 	IMPORT_C CAknSettingPage( TInt aSettingPageResourceId );

  /**

  * Constructor that allows separate setting page and editor resources

  *

  * 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

  *			present 			= 0 				Default Avkon SP resource if used

  *			 = 0				= 0 				Not permitted

  *

  * 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 (not copied; must be owned externally until ExecuteLD is called)

  * @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)

  */

 	IMPORT_C CAknSettingPage(	const TDesC* aSettingTitleText, 

 								TInt aSettingNumber, 

 								TInt aControlType,

 								TInt aEditorResourceId, 

 								TInt aSettingPageResourceId = 0 );

 /**

 * C++ destructor

 */

 	IMPORT_C virtual ~CAknSettingPage();

 /**

  * Executes a waiting dialog-like setting page

  * 

  * The passed mode determines if the editor's value is updated continuously, or just

  * when it is accepted.

  * 

  * @param	aMode		The update mode of the class

  */

 	IMPORT_C TBool ExecuteLD( enum CAknSettingPage::TAknSettingPageUpdateMode aMode=EUpdateWhenAccepted );

 /**

  * public method for construction.	Only thing required to do in this class is to call the 

  * BaseConstructL(). Derived classes may be required to do more

  *

  */

 	IMPORT_C virtual void ConstructL();

 /**

  * Returns reference to the hosted "editor" control as a CCoeControl.

  * This routine is used in derived classes, which may then cast to the specific run-time type

  * Note also that derived classes may provide type-specific access that performs these casts already

  * 

  * @return CCoeControl* pointer to the hosted editor control

  */

 	IMPORT_C CCoeControl* EditorControl() const;

 /**

  * Returns the setting Id.

  *

  * @return TInt the setting Id

  */

 	IMPORT_C TInt SettingId() const;

 /**

  * Sets the setting Id.  The Id may be used to unabiguously number a setting in some context.

  * It would be useful to call SettingId() on aSettingPageControl in handling an observer

  * callback.  The Id is not used internally.

  *

  * @param	aSettingId		An id to provide to the observer in the callback 

  */

 	IMPORT_C void SetSettingId( TInt aSettingId );

 /**

 * Substitutes the new setting number. 

 *

 * @param	aSettingNumber	The new setting number to display

 */

 	IMPORT_C void SetSettingNumberL( const TInt aSettingNumber );

 /**

  * Substitutes the new setting text.  Memory is allocated for a copy.

  * If already constructed, the label is reformatted.  

  * 

  * Note that calling this will over-ride text in Setting Page resource

  * 

  * @param	aSettingText	The new setting text to display

  */

 	IMPORT_C void SetSettingTextL( const TDesC& aSettingText );

 /**

  * Sets the observer for the setting page.

  *

  * @param	aObserver	The observer for changes to the setting

  */

 	IMPORT_C void SetSettingPageObserver( MAknSettingPageObserver* aObserver);

 /**

  * Access method for the number of the setting page

  *

  */

 	IMPORT_C TInt SettingNumber() const;

 /**

  * Access method for whether the setting page is numbered or not

  *

  */

 	IMPORT_C TBool IsNumbered() const;

 /**

  * Set method for whether the setting page is numbered or not

  *

  */

 	IMPORT_C void SetNumbered( TBool aNumbered );

 /**

  * Reads the passed-in setting page resource in order to read the contained editor control

  * resource information

  * @param aSettingPageResoruceId	This is used to specifiy what resource to read

  * @param aControlType				Returns the control type (MAY return 0 - that's a valid control type!

  * @param aEditorResourceId 		Returns the setting page's LLINK editor resource, but returns 0 if not present

  * 

  * This will leave if an invalid resource ID is passed

  */

 	IMPORT_C static void GetEditorResourceInfoL( 

 		TInt aSettingPageResourceId, 

 		TInt& aControlType, 

 		TInt& aEditorResourceId );

  /**

  * Set the edit-state of the setting page. The setting page can be edited or 

  * it can be only viewed by the user.

  *

  * @since 3.1

  * @param   aEditable If false, the setting page cannot be modified by the user

  */

  IMPORT_C void SetEditState(const TBool aEditable);

  /**

  * Is the setting page possible to edit by the user.

  *

  * @since 3.1

  * @return  Can user modify the setting page. True if can, false if cannot.

  */

  IMPORT_C TBool IsEditable() const;

  /**

  * Used for aknsettingpage's extenstion corresponding function

  *

  * @since 5.0

  * @param  aCaption On return, this should be set to the caption of the target control. 

  */ 

  void GetCaptionForFep(TDes& aCaption) const;

 protected:

 /**

 * From CCoeControl

 * This routine is called as part of the set-up of the control.	It is the place to put

 * layout code. 

 *

 */

 	IMPORT_C virtual void SizeChanged();

 /**

 * From CCoeControl

 * Takes any action required when the control gains or loses focus e.g. to change its appearance.

 * The control should be redrawn depending on the value of aDrawNow. Empty by default.

 */

 	IMPORT_C virtual void FocusChanged(TDrawNow aDrawNow); 

 /**

  * From MEikCommandObserver

  * Processes events from the softkeys. Responds to EAknSoftkeyOk and EAknSoftkeyBack

  * to accept or cancel the pop-up.

  *

  * @param	aCommandId	Event Id from the soft-key

  */

 	IMPORT_C virtual void ProcessCommandL(TInt aCommandId);

 /**

  * From MCoeControlObserver:

  * Acts upon changes in the hosted control's state. 

  * 

  * This class's implementation is trivial and should be able to be

  * safely re-implemented in directly client-derived classes. 

  * For non-base setting page classes, a call to the base class should be made

  *

  * @param	aControl	The control changing its state (not used)

  * @param	aEventType	The type of control event 

  */

 	IMPORT_C virtual void HandleControlEventL(CCoeControl* aControl,TCoeEvent aEventType);

 //

 //

 // Framework functions. New in this class

 //

 //

 	/**

 	* Framework method to determine if it is OK to exit the setting page.

 	* Derived classes may check for valid data before allowing the dismissal of the 

 	* setting page.

 	*

 	* @param	aAccept ETrue if the user has indicated to accept the setting page; EFalse otherwise

 	* @return	TBool	a value indicating whether the setting page should be dismissed

 	*/

 	IMPORT_C virtual TBool OkToExitL(TBool aAccept);

 /**

 * Called immediately prior to activation of the dialog.  Framework routine for derived

 * classes.

 *

 */

 	IMPORT_C virtual void DynamicInitL();

 /**

  * Called when something has changed and the client's object needs to have its value updated

  *

  */

 	IMPORT_C virtual void UpdateSettingL();

 /**

  * Called when the user accepts a setting and the setting page is about to be dismissed.  The latest value of the

  * setting is written to the client's object

  */

 	IMPORT_C virtual void AcceptSettingL();

 /**

  * Called when the user rejects the setting.  A backup copy may need to be restored if UpdateWhenChanged flag was set

  *

  */

 	IMPORT_C virtual void RestoreOriginalSettingL();

 /** 

  * Display the menu

  */

 	IMPORT_C virtual void DisplayMenuL() ;

 /**

  * Hide the menu

  */

 	IMPORT_C virtual void HideMenu() ;

 /** 

  * Puts the focus back on the editor. For complicated setting pages that have focus removed from them

  * at some point, then a re-implementation may have to do some work here.

  */

 	IMPORT_C virtual void SetFocusToEditor();

 /**

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

  * listbox editors prior to exiting from the setting page. It is called on a 

  * CAknSettingPage* reference, and is therefore declared here.

  */

 	IMPORT_C virtual void SelectCurrentItemL();

 /**

  * Protected non-virtual base method for construction.	Only thing required to do in this class is 

  * call the ConstructFromResourceL routine and set the flag that says construction has occured

  *

  */

 	IMPORT_C void BaseConstructL();

 /**

  * Called to remove the setting page. Should not be called except from within re-implemented

  * AttemptExitL

  *

  * @param	aAccept ETrue to accept the current value; EFalse otherwise

  */

 	IMPORT_C void DismissL( TBool aAccept );  

 /**

  * This is used as a protected access function for the state of the menu bar

  *

  * @return TBool	ETrue if the menu is currently showing 

  */

 	IMPORT_C TBool MenuShowing() const ;

 /** 

 * This constructs the control based upon the id passed

 *

 */

 	IMPORT_C void ConstructFromResourceL( TInt aResourceId);

 /** 

 * This constructs the control based upon a constructed and positioned reader

 *

 */

 	IMPORT_C void ConstructFromResourceL(TResourceReader& aRes);

  /**

  * Called when the user accepts or cancels the setting. Default implementation

  * sets the return value and exists. 

  * 

  * Re-implementations must call DismissL and StopActiveScheduler() if the setting is

  * to leave.

  *

  * @param	aAccept ETrue if the user accepted. EFalse if the user cancelled.

  */

 	IMPORT_C void AttemptExitL(TBool aAccept);

 /**

 * Method to determine the current running state of the setting page's 

 * ActiveScheduler level. 

 *

 * @return	EFalse only if the CActiveSheduler level is not running

 */

 	IMPORT_C TBool Waiting(); 

 /**

 * Access method to the Command button array

 *

 * Must be called after full construction, or null reference will be returned.

 *

 * @return CEikButtonGroupContainer* a pointer to the cba owned by the setting page

 */

 	IMPORT_C CEikButtonGroupContainer* Cba() const ;

 /**

  * This is used to access the default resource id for the cba - the one used when 

  * data is valid.

  *

  * @return TInt 	the default resource Id 

  */

 	IMPORT_C TInt DefaultCbaResourceId() const; 

 /** 

 * This routine routes the keys to the editor. 

 * However, if the menu is showing, then events are sent to the menu. 

 *

 * @param	aKeyEvent	event information	

 * @param	aType		type of event being handled

 *

 */

 	IMPORT_C TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType);

 /**

 * This routine is the base layout for CAknSettingPage. It lays out the labels and configures

 * the drawing in general.

 */	

 	IMPORT_C void StandardSettingPageLayout();

 /**

  * This method can be used to test if BaseConstructL() has been called yet

  * successfully

  *

  * @return TBool	ETrue if BaseContructL has been called (and not left)

  */

 	IMPORT_C TBool IsBaseConstructed();

 /**

  * Access method for the internally held resource Id

  *

  */

 	IMPORT_C TInt SettingPageResourceId();

 /** 

 * Perform the drawing of coded within CAknSettingPage

 * 

 */

 	IMPORT_C void BaseDraw(const TRect& aRect) const;

 /**

 * Set default construction values of internal state

 */

 	IMPORT_C void ResetFlags();

 /**

  * Framework method called as soon as the setting page is displayed, but before the new active sheduler level

  * is started.	Returning EFalse will dismiss the setting page right away

  *

  * @return TBool	ETrue if the setting page is to continue

  */

 	IMPORT_C virtual TBool PostDisplayCheckL();

 /** 

  * This framework method is used to update the contents of the CBA in a custom way.

  * Some setting page classes implement a degree of validation and will implement this.

  * Derived classes should ensure that this is being called frequently enough for their

  * purposes.

  */

 	IMPORT_C virtual void UpdateCbaL();

 /**

  * Called to access the validity state of the data

  *

  * @return TBool ETRrue if the data is valid

  */

 	IMPORT_C TBool DataValidity() const;

 /**

  * used to set the validity of the data

  *

  * @param TBool aValid	Sets the validity true or false

  */

 	IMPORT_C void SetDataValidity(TBool aValid);

 /**

  * Framework method to set the validity of the data

  * This is called when the data changes.

  *

  */

 	IMPORT_C virtual void CheckAndSetDataValidity();

 /**

  * Method to be called by CAknSettingPage descendents when they have laid themselves out.

  * This tells the base class how big the layout spec rectangle hosting the editor is.  

  * The second rectangle is the size of the area that the base class does not have to 

  * draw to for skins. Usually, this is the area actually inhabited by the editor control.

  *

  * Coordinates are to be given in pixels relative to the main_pane. 

  *

  * @param aFrameRect		Layout rectangle in which to host the editor. 

  * @param aRealEditorRect	Layout rectangle actually occupied by the editor control

  *

  * @since 2.0

  */

 	void SetEditedItemLayoutRect( const TRect& aFrameRect, const TRect& aRealEditorRect);

  /**

  * Method to cause this class to construct a control context or type and IID, selected according to

  * the value of enumeration TEditedItemSkinClass, set its coordinate system 

  *

  * This must be called after a call to SetEditedItemLayoutRect has been made on CAknSettingPage.

  * This is becasue this routine must set the control context's origin to the top left of the value 

  * given to SetEditedItemLayoutRect. Since SetEditeItemLayoutRect is to be called in a SizeChanged 

  * method, this means that the this should be called after the SizeChanged in the child class.

  * @param	aClass	enumeration specifying which class of editor (according to LAF spec) is being

  * constructed.

  * @param	aParentAbsolute	ETrue if there is an intervening Window between CAknSettingPage's window

  * and any control that is to draw skin items with this component.

  *

  * since 2.0

  * 

  */

 	void CreateEditedItemControlContextL( TEditedItemSkinClass aSkinClass, TBool aParentAbsolute);

  /**

  * Indicates whether skin system will be able to draw the editor frame and background

  *

  * @return TBool ETrue iff the drawing of the edited item frame is going to be handled by

  *					the base CAknSettingPage class itself using Skins

  * @since 2.0

  */

 	TBool IsSkinsHandlingEditorFrameDrawing() const;

  /**

  * Control context for providing to the skinning for the hosted editor and its framing

  *

  * @return      A valid control context for frame drawing for a hosted editor or NULL

  * @since 2.0

  */ 

     CAknsFrameBackgroundControlContext* EditedItemControlContext() const;

 protected:

  /**

  * From MEikMenuObserver 

  * Called when menu is cancelled.

  */

 	IMPORT_C virtual void SetEmphasis(CCoeControl* /*aMenuControl*/,TBool aEmphasis);

  /**

  * From MEikMenuObserver 

  * This function intializes the items on the menu. It is used to disable and enable menu items and may be

  * over ridden to add new ones.

  * In addition it adds menu items which have been provided in the ConstructL in the form of a Menu Bar resource.

  * Instead of using the Menu Bar directly it extracts the menu panes and adds them to its own menu pane.

  * It must be called in the DynInitMenuPaneL() function of any derived class before anything else.

  */

 	IMPORT_C virtual void DynInitMenuPaneL( TInt aResourceId, CEikMenuPane* aMenuPane ); 

 public: // From CCoeControl

  /**

  * Handles a change to the control's resources of type aType

  * which are shared across the environment, e.g. colors or fonts.

  *

  * @since 2.0

  * @param aType  Reason for the "resource" change, usually an system event UID

  */

     IMPORT_C void HandleResourceChange(TInt aType);

 /**

  * Standard CCoeControl routine to return the number of componentn controls

  *

  * @param	aIndex	index at which to return control

  */

 	IMPORT_C TInt CountComponentControls() const;

 /**

  * Standard CCoeControl routine to return the control at a given index

  *

  * @param	aIndex	index at which to return control

  */ 

 	IMPORT_C CCoeControl* ComponentControl(TInt anIndex) const;

  /**

  * Handles pointer events

  */

     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

  /**

  * From CCoeControl.

  * Gets the control's input capabilities.

  *

  * @return The control's input capabilities.

  */   

 	IMPORT_C TCoeInputCapabilities InputCapabilities() const;

 private:

 	IMPORT_C virtual void Reserved_MtsmPosition();

 	IMPORT_C virtual void Reserved_MtsmObject();

 protected:

 /** 

 *	Access method for the softkey resource used when there is invalid data

 *

 * @return TInt The resource Id of the softkey bindings. 

 */

 	IMPORT_C TInt InvalidDataCbaResourceId() const; 

 protected: // from MObjectProvider

 	IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);

 protected:

 	/**

 	* Hold the update mode passed in the constructor

 	*/

 	TInt iUpdateMode;

 	// The following are not owned:

 	/**

 	* Pointer to setting page observer; may be NULL

 	*/

 	MAknSettingPageObserver* iSettingPageObserver;

 private:

 	//From CCoeControl

 	IMPORT_C void Draw(const TRect& aRect) const;

 private:

     /**

     * From CAknControl

     */

     IMPORT_C void* ExtensionInterface( TUid aInterface );

 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;

 private:

 /**

 *	Reserved method derived from CCoeControl

 */

 	IMPORT_C virtual void Reserved_2();

  /** 

  * Activate another level on the active scheduler

  */ 

 	void StartActiveScheduler();

  /** 

  * Stop current (additional) level on the active scheduler

  */ 

 	void StopActiveScheduler();

 /**

 * Pop the navidecorator. The iNaviPane is used as a flag to show if popping is required to 

 * be done or not. It is zeroed by this method.

 *

 */

 	void PopNaviDecoratorIfRequired();

 private:

 /**

 * New reserved methods for CAknSettingPage hierarchy

 */ 

 private: 

 	IMPORT_C virtual void CAknSettingPage_Reserved_1();

 	IMPORT_C virtual void CAknSettingPage_Reserved_2();

 protected:

     /**

     * Enables / disables transparency effect, i.e. does the setting page draw its own background or not.

     * @param aDrawBackground  EFalse enables transparency

     */ 

     void SetDrawBackground(const TBool aDrawBackground);    

     /**

     * Is the setting page drawing the background itself or not (= "transparency")

     */ 

     TBool IsBackgroundDrawingEnabled() const;

     /**

     * Set the flag to indicate that if the function CAknSettingPage::StopActiveScheduler called or not

     *@param aStopCalled ETrue means the StopActiveScheduler is called.

     */

     void SetStopActiveSchedulerFlag(const TBool aStopCalled );

     /**

      * Is the setting page call the StopActiveScheduler or not 

      */ 

     TBool IsStopActiveSchudlerCalled()const;

     /**

     * Pointer to setting text label

     * @return pointer to the label

     *

 	* @since 5.0

     */    

     IMPORT_C CEikLabel* TextLabel() const;

     /**

     * Pointer to shadow text label

     * @return pointer to the label

     *

 	* @since 5.0

     */    

     IMPORT_C CEikLabel* ShadowText() const;

 private:

 /** 

 * This member points to the setting title text that is passed as part of its more complicated constructor.

 * The descriptor pointed to is not owned, and therefor must be preserved in the client, at least until the 

 * 2nd stage construction is performed (inside ExecuteLD). 

 *

 * Since, however, setting pages are all waiting, the descriptor can usually be on the stack in the client.

 *

 */

 	const TDesC* iSettingTextFromConstructor;

 	TInt iResourceId;

 	TInt iSettingNumber;

 	TInt iSettingId;

 	TInt iMenuBarId;

 	TInt iControlType;

 	TInt iEditorResourceId;

 	TInt iExtensionId;

 	TInt iCbaResourceId;

 	TAknLayoutRect iShadow;

 	TAknLayoutRect iHighlight;

 // pointer to the return value from the setting page.  

 // Needed when presented in waiting mode.  

 	TBool* iReturn; 

 // Internal flags

 	TBitFlags iFlags ;

 	enum TFlagIndices

 		{

 		EMenuShowingIndex = 0,

 		ENumberedStyleIndex,

 		EIsBaseConstructedIndex,

 		EHasValidDataIndex

 		};

 // Heap objects pointed to here are owned:

 	CCoeControl* iEditorControl;

 	CEikLabel* iNumberLabel;

 	CEikLabel* iTextLabel;

 	CEikButtonGroupContainer* iCba;

 	CEikMenuBar* iMenuBar ;

 	HBufC* iHintText;

 	HBufC* iSettingText; 

 	CAknNavigationDecorator* iNaviDecorator;

 	// The following are not owned:

 	// For hint text support

 	CAknNavigationControlContainer* iNaviPane;

 	// Softkey resource when the data is invalid

 	TInt iInvalidDataCbaResourceId;

 	// The following object is used to contain all skinning information required

 	CAknSettingPageSkinsInfo* iSkinsInfo;

 	CActiveSchedulerWait iWait;		// owned, safe to use as direct member data.

     // is setting page editable

     TInt iIsProtected;

     // extension to setting page

     CAknSettingPageExtension* iExtension;

 };

 #endif