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