/*

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

 *     Interface for Setting page carrying CEikEdwin editors

 *		- CAknTextSettingPage: 6 line text editor

 *		- CAknIntegerSettingPage: 1 line integer editor

 *

 *

 */

 #ifndef __AKNTEXTSETTINGPAGE_H__

 #define __AKNTEXTSETTINGPAGE_H__ 

 // For coecontrol and its observer

 #include <coecntrl.h>

 #include <coecobs.h>

 #include <eikdef.h>

 #include <eikedwin.h>

 #include "aknsettingpage.h"

 #include "aknnumedwin.h"

 /**

 * This class is an intermediate pure virtual class for all setting page classes that host 

 * Edwins.

 *

 * It implements type-specific access to the hosted editor and common drawing code

 */

 class CAknEdwinSettingPage : public CAknSettingPage

 {

 public:

 	/**

 	*	Common access to the edwin for descendant classes

 	*

 	* @return Pointer to contained edwin control

 	*/

 	IMPORT_C CEikEdwin* TextControl();

     /**

     * From CCoeControl.     

     * Handles pointer events

     */

     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

 protected:

 	/**

 	 * Simple constructor depending only on a single resource Id.

 	 *

 	 * @param aSettingPageResourceId	Setting Page resource id to use 

 	 */

 	IMPORT_C CAknEdwinSettingPage( TInt ResourceId );

 	/**

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

 	 * Note that this buffer must be owned by the client until ExecuteLD has been called.

 	 *

 	 * 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; EXTERNALLY OWNED

 	 * @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 CAknEdwinSettingPage(

 								const TDesC* aSettingTitleText, 

 								TInt aSettingNumber, 

 								TInt aControlType,

 								TInt aEditorResourceId, 

 								TInt aSettingPageResourceId );

 //

 // From CCoeControl

 //

 protected:

 	/**

 	* No implementation of SizeChanged is delivered with this class

 	*

 	*/

 	virtual void SizeChanged() = 0;

 	/**

 	* Common draw function for laid-out descendent setting pages. 

 	* This should not need to be re-implemented as long as the rectangle members are

 	* all that is needed

 	*

 	* @param	aRect	rectangle within which to perform the draw

 	*/

 	IMPORT_C void Draw(const TRect& aRect) const;

 private:

     /**

     * From CAknControl

     */

     IMPORT_C void* ExtensionInterface( TUid aInterface );

 private:

 /**

  * New reserved method with this class

  *

  */

 	IMPORT_C virtual void CAknEdwinSettingPage_Reserved_1();

 protected:

 	/**

 	* Rectangle within which to layout the edwin. Not drawn

 	*/

 	TAknLayoutRect iEdwinLayoutRect;

 	/**

 	* Horizontal shadow rectangle

 	*/

 	TAknLayoutRect iHorizontalShadow;

 	/**

 	* Vertical shadow rectangle

 	*/

 	TAknLayoutRect iVerticalShadow;

 	/**

 	* Rectangle drawn around the edwin

 	*/

 	TAknLayoutRect iOutlineFrame;

 private:

     TInt iSpare;

 };

 /**

 * Implementation of the 6 line textual setting page. 

 * A multi-line edwin is displayed when the setting page is executing.

 * An externally held text descriptor is altered by user input

 */

 class CAknTextSettingPageExtension;

 class CAknTextSettingPage : public CAknEdwinSettingPage

 {

 public:

 // Flags to modify the behaviour of the editor

 	enum TAknTextSettingPageFlags

 	{

 	EZeroLengthNotOffered = 0x0,	// DEPRECATED. This enum preserved but with value 0

 	EPutCursorAtEnd = 0x0,			// DEPRECATED. This is already default so putting flag at beginning is more useful

 	EZeroLengthAllowed = 0x0000001,

 	ENoInitialSelection = 0x0000004,	// DEPRECATED and no longer used

 	EPutCursorAtBeginning = 0x0000008,	// DEPRECATED and no longer used

 	// Instructs the TextSettingPage not to override any of the Edwin's cursor and selection flags

 	EUseEdwinCursorAndSelectionFlags = 0x0000010, // DEPRECATED

 	EPredictiveTextEntryPermitted = 0x0020

 	};

 public:

 	/**

 	 * Simple constructor depending only on a single resource Id. Editor resource is given via

 	 * the link in the setting page resource.

 	 *

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

 	 * @param aText						Reference to text for editing

 	 * @param aTextSettingPageFlags		option flags for miscellaneous things

 	 */

 	IMPORT_C CAknTextSettingPage(TInt aResourceID, TDes& aText, TInt aTextSettingPageFlags = 0 );

 	/**

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

 	 * Note that this buffer must be owned by the client until ExecuteLD has been called.

 	 *

 	 * 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; OWNED EXTERNALLY

 	 * @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 aText					Reference to text for editing

 	 * @param aTextSettingPageFlags option flags for miscellaneous things

 	 */

 	IMPORT_C CAknTextSettingPage(	const TDesC* aSettingTitleText, 

 								TInt aSettingNumber, 

 								TInt aControlType,

 								TInt aEditorResourceId, 

 								TInt aSettingPageResourceId,

 								TDes& aText, 

 								TInt aTextSettingPageFlags = 0);

 	/**

 	* 2nd stage construction for this specific type.  Calls BaseConstructL in 

 	* CAknSettingPage, where the object is constructed from resource.

 	* 

 	* After calling this method, the contained editor is fully constructed and has its text set, 

 	* copied from the aText parameter of the constructor. 

 	* 

 	* This constructor can be called prior to a call to ExecuteLD in order to ensure 

 	* construction of the editor if API needs to be called on it prior to setting page launch.

 	* ExecuteLD will not attempt itself to do the construction a 2nd time.

 	* 

 	*/

 	IMPORT_C virtual void ConstructL();

     /**

     * From CCoeControl.     

     * Handles pointer events

     */

     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

 protected:

 	/**

 	* C++ destructor

 	*

 	*/ 

 	IMPORT_C virtual ~CAknTextSettingPage();

 //

 // CAknSettingPage Framework implementations

 //

 protected:

 /**

 * 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 text updated

 *

 */

 	IMPORT_C virtual void UpdateSettingL();

 /**

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

 * text is written to the client's object

 */

 	IMPORT_C virtual void AcceptSettingL();

 /**

 * Called when the user rejects the setting.  

 * A backed up copy is used to restore the initial value

 *

 */

 	IMPORT_C virtual void RestoreOriginalSettingL();

 /**

  * From MCoeControlObserver:

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

  * flag is set, this updates the setting text.

  * 

  * @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 method to set the validity of the data

  * This is called when the data changes.

  *

  */

 	IMPORT_C virtual void CheckAndSetDataValidity();

 /**

 * This method copies out the text from the editor into the client's descriptor

 *

 */

 	IMPORT_C virtual void UpdateTextL();

 /**

 * Update the CBA. This should be called after a control state change in case 

 * there has been a change in data validity.

 *

 */

 	IMPORT_C virtual void UpdateCbaL();

 /**

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

 /** 

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

 /**

  * Reserved methods for CAknSettingPage hierarchy

  */ 

 private: 

 	IMPORT_C virtual void CAknSettingPage_Reserved_1();

 	IMPORT_C virtual void CAknSettingPage_Reserved_2();

 // 

 // From CCoeControl

 //

 protected:

 /**

 * From CCoeControl

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

 * the layout code. 

 *

 */

 	IMPORT_C virtual void SizeChanged();

 /**

  * 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();

 private:

     /**

     * From CAknControl

     */

     IMPORT_C void* ExtensionInterface( TUid aInterface );

 /**

  * Reserved method from CAknEdwinSettingPage

  *

  */

 	IMPORT_C virtual void CAknEdwinSettingPage_Reserved_1();

 private: 

     // restarts timer that blocks Ok button for the period FEP may reject the edit

     void RestartMultitapWaitTimer();

 private:

 	HBufC* iBackupText;

 	TDes& iText;

 	TInt iTextSettingPageFlags;

 	CAknTextSettingPageExtension* iExtension; 

 	};

 /**

  * Setting page specialized for display of CAknIntegerEdwin

  *

  */

 class CAknIntegerSettingPage : public CAknEdwinSettingPage

 {

 public:

 // Flags to modify the behaviour of the editor

 	enum TAknIntegerSettingPageFlags

 	{

 	EInvalidValueNotOffered = 0x0,

 	EEmptyValueAllowed = 0x0000001,

 	EInvalidValueAllowed = 0x0000002,

 	ENoInitialSelection = 0x0000004,

 	EPutCursorAtBeginning = 0x0000008

 	};

 public:

 	IMPORT_C CAknIntegerSettingPage(TInt aResourceID, TInt& aValue, TInt aTextSettingPageFlags = 0 );

 	/**

 	 * 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; OWNED EXTERNALLY

 	 * @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 aValue					Reference to integer value for editing

 	 * @param aIntegerSettingPageFlags option flags for miscellaneous things

 	 */

 	IMPORT_C CAknIntegerSettingPage(	const TDesC* aSettingTitleText, 

 								TInt aSettingNumber, 

 								TInt aControlType,

 								TInt aEditorResourceId, 

 								TInt aSettingPageResourceId,

 								TInt& aValue, 

 								TInt aIntegerSettingPageFlags = 0);

 	/**

 	* 2nd stage construction for this specific type.  Call BaseConstructL in 

 	* CAknSettingPage, where the object is constructed from resource.

 	*/

 	IMPORT_C virtual void ConstructL();

 	/** 

 	* Type-specific access to the hosted editor

 	*

 	* @return CAknIntegerEdwin*		pointer to the current hosted editor

 	*/

 	IMPORT_C CAknIntegerEdwin* IntegerEditorControl();

     /**

     * From CCoeControl.     

     * Handles pointer events

     */

     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

 //

 // Framework methods from CAknSettingPage

 //

 protected:

 /**

 * 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 rejects the setting.  A backup copy may need to be restored if UpdateWhenChanged flag was set

 *

 */

 	IMPORT_C virtual void RestoreOriginalSettingL();

 /**

  * Framework method to set the validity of the data

  * This is called when the data changes.

  * May be over-ridden to change the validation rules.

  *

  */

 	IMPORT_C virtual void CheckAndSetDataValidity();

 /** 

  * 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();

 /**

  * Reserved methods for CAknSettingPage hierarchy

  */ 

 private: 

 	IMPORT_C virtual void CAknSettingPage_Reserved_1();

 	IMPORT_C virtual void CAknSettingPage_Reserved_2();

 //

 // From MEikControlObserver

 //

 protected:

 /**

  * From MCoeControlObserver:

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

  * 

  * The implementation of this class 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 );	

 //

 // From CCoeControl

 //

 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();

 /**

  * 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();

 private:

     /**

     * From CAknControl

     */

     IMPORT_C void* ExtensionInterface( TUid aInterface );

 private:

 /**

  * Reserved method from CAknEdwinSettingPage

  *

  */

 	IMPORT_C virtual void CAknEdwinSettingPage_Reserved_1();

 private:

 	TInt iBackupValue;

 	TInt& iValue;

 	TInt iIntegerSettingPageFlags;

 	TInt iSpare_1; 

 };

 #endif