--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/classicui_pub/setting_pages_api/inc/AknTextSettingPage.h Tue Feb 02 01:00:49 2010 +0200
@@ -0,0 +1,614 @@
+/*
+* 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:
+* 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);
+
+public:
+ /**
+ * add for CAknTextSettingPageExtension to access the api fo CAknTextSettingPage
+ */
+ void ProcessPopupStateChangesL();
+
+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