1 /*

     2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *     Interface for Setting page carrying CEikEdwin editors

    16 *		- CAknTextSettingPage: 6 line text editor

    17 *		- CAknIntegerSettingPage: 1 line integer editor

    18 *

    19 *

    20 */

    21 

    22 

    23 #ifndef __AKNTEXTSETTINGPAGE_H__

    24 #define __AKNTEXTSETTINGPAGE_H__ 

    25 

    26 // For coecontrol and its observer

    27 #include <coecntrl.h>

    28 #include <coecobs.h>

    29 

    30 #include <eikdef.h>

    31 #include <eikedwin.h>

    32 #include "aknsettingpage.h"

    33 #include "AknNumEdwin.h"

    34 

    35 /**

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

    37 * Edwins.

    38 *

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

    40 */

    41 class CAknEdwinSettingPage : public CAknSettingPage

    42 {

    43 

    44 public:

    45 

    46 	/**

    47 	*	Common access to the edwin for descendant classes

    48 	*

    49 	* @return Pointer to contained edwin control

    50 	*/

    51 	IMPORT_C CEikEdwin* TextControl();

    52 

    53     /**

    54     * From CCoeControl.     

    55     * Handles pointer events

    56     */

    57     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

    58 

    59 protected:

    60 	/**

    61 	 * Simple constructor depending only on a single resource Id.

    62 	 *

    63 	 * @param aSettingPageResourceId	Setting Page resource id to use 

    64 	 */

    65 	IMPORT_C CAknEdwinSettingPage( TInt ResourceId );

    66 	/**

    67 	 * Constructor that allows separate setting page and editor resources

    68 	 * 

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

    70 	 *

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

    72 	 *

    73 	 *		Editor Resource		Setting Page Resource

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

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

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

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

    78 	 *	 i) control type is present, 

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

    80 	 *

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

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

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

    84 	 *

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

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

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

    88 	 * specific API for setting them, WILL override resource.

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

    90 	 * 

    91 	 * @param aSettingTitleText	Text at top of setting pane; EXTERNALLY OWNED

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

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

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

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

    96 	 */

    97 

    98 	IMPORT_C CAknEdwinSettingPage(

    99 								const TDesC* aSettingTitleText, 

   100 								TInt aSettingNumber, 

   101 								TInt aControlType,

   102 								TInt aEditorResourceId, 

   103 								TInt aSettingPageResourceId );

   104 

   105 //

   106 // From CCoeControl

   107 //

   108 protected:

   109 	/**

   110 	* No implementation of SizeChanged is delivered with this class

   111 	*

   112 	*/

   113 	virtual void SizeChanged() = 0;

   114 

   115 	/**

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

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

   118 	* all that is needed

   119 	*

   120 	* @param	aRect	rectangle within which to perform the draw

   121 	*/

   122 	IMPORT_C void Draw(const TRect& aRect) const;

   123 

   124 private:

   125     /**

   126     * From CAknControl

   127     */

   128     IMPORT_C void* ExtensionInterface( TUid aInterface );

   129 

   130 private:

   131 /**

   132  * New reserved method with this class

   133  *

   134  */

   135 	IMPORT_C virtual void CAknEdwinSettingPage_Reserved_1();

   136 

   137 protected:

   138 	/**

   139 	* Rectangle within which to layout the edwin. Not drawn

   140 	*/

   141 	TAknLayoutRect iEdwinLayoutRect;

   142 

   143 	/**

   144 	* Horizontal shadow rectangle

   145 	*/

   146 	TAknLayoutRect iHorizontalShadow;

   147 	

   148 	/**

   149 	* Vertical shadow rectangle

   150 	*/

   151 	TAknLayoutRect iVerticalShadow;

   152 

   153 	/**

   154 	* Rectangle drawn around the edwin

   155 	*/

   156 	TAknLayoutRect iOutlineFrame;

   157 

   158 private:

   159     TInt iSpare;

   160 };

   161 

   162 /**

   163 * Implementation of the 6 line textual setting page. 

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

   165 * An externally held text descriptor is altered by user input

   166 */

   167 class CAknTextSettingPageExtension;

   168 

   169 class CAknTextSettingPage : public CAknEdwinSettingPage

   170 {

   171 public:

   172 

   173 // Flags to modify the behaviour of the editor

   174 	enum TAknTextSettingPageFlags

   175 	{

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

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

   178 	EZeroLengthAllowed = 0x0000001,

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

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

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

   182 	EUseEdwinCursorAndSelectionFlags = 0x0000010, // DEPRECATED

   183 	EPredictiveTextEntryPermitted = 0x0020

   184 	};

   185 

   186 public:

   187 	/**

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

   189 	 * the link in the setting page resource.

   190 	 *

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

   192 	 * @param aText						Reference to text for editing

   193 	 * @param aTextSettingPageFlags		option flags for miscellaneous things

   194 	 */

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

   196 	/**

   197 	 * Constructor that allows separate setting page and editor resources

   198 	 * 

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

   200 	 *

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

   202 	 *

   203 	 *		Editor Resource		Setting Page Resource

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

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

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

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

   208 	 *	 i) control type is present, 

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

   210 	 *

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

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

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

   214 	 *

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

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

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

   218 	 * specific API for setting them, WILL override resource.

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

   220 	 * 

   221 	 * @param aSettingTitleText	Text at top of setting pane; OWNED EXTERNALLY

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

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

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

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

   226 	 * @param aText					Reference to text for editing

   227 	 * @param aTextSettingPageFlags option flags for miscellaneous things

   228 	 */

   229 	IMPORT_C CAknTextSettingPage(	const TDesC* aSettingTitleText, 

   230 								TInt aSettingNumber, 

   231 								TInt aControlType,

   232 								TInt aEditorResourceId, 

   233 								TInt aSettingPageResourceId,

   234 								TDes& aText, 

   235 								TInt aTextSettingPageFlags = 0);

   236 

   237 	/**

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

   239 	* CAknSettingPage, where the object is constructed from resource.

   240 	* 

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

   242 	* copied from the aText parameter of the constructor. 

   243 	* 

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

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

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

   247 	* 

   248 	*/

   249 	IMPORT_C virtual void ConstructL();

   250 

   251     /**

   252     * From CCoeControl.     

   253     * Handles pointer events

   254     */

   255     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   256 

   257 public:

   258     /**

   259 	 *  add for CAknTextSettingPageExtension to access the api fo CAknTextSettingPage

   260 	 */

   261 	void ProcessPopupStateChangesL();

   262 

   263 protected:

   264 	/**

   265 	* C++ destructor

   266 	*

   267 	*/ 

   268 	IMPORT_C virtual ~CAknTextSettingPage();

   269 

   270 //

   271 // CAknSettingPage Framework implementations

   272 //

   273 protected:

   274 

   275 /**

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

   277 * classes.

   278 *

   279 */

   280 	IMPORT_C virtual void DynamicInitL();

   281 

   282 /**

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

   284 *

   285 */

   286 	IMPORT_C virtual void UpdateSettingL();

   287 

   288 /**

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

   290 * text is written to the client's object

   291 */

   292 	IMPORT_C virtual void AcceptSettingL();

   293 

   294 /**

   295 * Called when the user rejects the setting.  

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

   297 *

   298 */

   299 	IMPORT_C virtual void RestoreOriginalSettingL();

   300 

   301 /**

   302  * From MCoeControlObserver:

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

   304  * flag is set, this updates the setting text.

   305  * 

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

   307  * @param	aEventType	The type of control event 

   308  */

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

   310 

   311 

   312 /**

   313  * Framework method to set the validity of the data

   314  * This is called when the data changes.

   315  *

   316  */

   317 	IMPORT_C virtual void CheckAndSetDataValidity();

   318 

   319 /**

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

   321 *

   322 */

   323 	IMPORT_C virtual void UpdateTextL();

   324 	

   325 /**

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

   327 * there has been a change in data validity.

   328 *

   329 */

   330 	IMPORT_C virtual void UpdateCbaL();

   331 

   332 /**

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

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

   335 * setting page.

   336 * 

   337 *

   338 *

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

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

   341 */

   342     IMPORT_C virtual TBool OkToExitL(TBool aAccept);

   343 

   344 /** 

   345 * This routine routes the keys to the editor. 

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

   347 *

   348 * @param	aKeyEvent	event information	

   349 * @param	aType		type of event being handled

   350 *

   351 */

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

   353 

   354 

   355 /**

   356  * Reserved methods for CAknSettingPage hierarchy

   357  */ 

   358 private: 

   359 	IMPORT_C virtual void CAknSettingPage_Reserved_1();

   360 	IMPORT_C virtual void CAknSettingPage_Reserved_2();

   361 

   362 // 

   363 // From CCoeControl

   364 //

   365 

   366 protected:

   367 

   368 /**

   369 * From CCoeControl

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

   371 * the layout code. 

   372 *

   373 */

   374 	IMPORT_C virtual void SizeChanged();

   375 

   376 /**

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

   378  * Does nothing in release mode.

   379  * Designed to be overidden and base called by subclasses.

   380  *

   381  * @param	aWriteSteam		A connected write stream

   382  */	

   383 	IMPORT_C virtual void WriteInternalStateL(RWriteStream& aWriteStream) const;

   384 

   385 private:

   386 /**

   387  *	Reserved method derived from CCoeControl

   388  */

   389 	IMPORT_C virtual void Reserved_2();

   390 

   391 private:

   392     /**

   393     * From CAknControl

   394     */

   395     IMPORT_C void* ExtensionInterface( TUid aInterface );

   396 

   397 /**

   398  * Reserved method from CAknEdwinSettingPage

   399  *

   400  */

   401 	IMPORT_C virtual void CAknEdwinSettingPage_Reserved_1();

   402 

   403 private: 

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

   405     void RestartMultitapWaitTimer();

   406 

   407 private:

   408 	HBufC* iBackupText;

   409 	TDes& iText;

   410 	TInt iTextSettingPageFlags;

   411 	CAknTextSettingPageExtension* iExtension; 

   412 	};

   413 

   414 

   415 /**

   416  * Setting page specialized for display of CAknIntegerEdwin

   417  *

   418  */

   419 class CAknIntegerSettingPage : public CAknEdwinSettingPage

   420 {

   421 public:

   422 

   423 // Flags to modify the behaviour of the editor

   424 	enum TAknIntegerSettingPageFlags

   425 	{

   426 	EInvalidValueNotOffered = 0x0,

   427 	EEmptyValueAllowed = 0x0000001,

   428 	EInvalidValueAllowed = 0x0000002,

   429 	ENoInitialSelection = 0x0000004,

   430 	EPutCursorAtBeginning = 0x0000008

   431 	};

   432 

   433 public:

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

   435 	/**

   436 	 * Constructor that allows separate setting page and editor resources

   437 	 * 

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

   439 	 *

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

   441 	 *

   442 	 *		Editor Resource		Setting Page Resource

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

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

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

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

   447 	 *	 i) control type is present, 

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

   449 	 *

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

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

   452 	 *

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

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

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

   456 	 * specific API for setting them, WILL override resource.

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

   458 	 * 

   459 	 * @param aSettingTitleText	Text at top of setting pane; OWNED EXTERNALLY

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

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

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

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

   464 	 * @param aValue					Reference to integer value for editing

   465 	 * @param aIntegerSettingPageFlags option flags for miscellaneous things

   466 	 */

   467 	IMPORT_C CAknIntegerSettingPage(	const TDesC* aSettingTitleText, 

   468 								TInt aSettingNumber, 

   469 								TInt aControlType,

   470 								TInt aEditorResourceId, 

   471 								TInt aSettingPageResourceId,

   472 								TInt& aValue, 

   473 								TInt aIntegerSettingPageFlags = 0);

   474 

   475 	/**

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

   477 	* CAknSettingPage, where the object is constructed from resource.

   478 	*/

   479 	IMPORT_C virtual void ConstructL();

   480 

   481 	/** 

   482 	* Type-specific access to the hosted editor

   483 	*

   484 	* @return CAknIntegerEdwin*		pointer to the current hosted editor

   485 	*/

   486 	IMPORT_C CAknIntegerEdwin* IntegerEditorControl();

   487 

   488     /**

   489     * From CCoeControl.     

   490     * Handles pointer events

   491     */

   492     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   493 

   494 //

   495 // Framework methods from CAknSettingPage

   496 //

   497 protected:

   498 

   499 /**

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

   501 * classes.

   502 *

   503 */

   504 	IMPORT_C virtual void DynamicInitL();

   505 

   506 /**

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

   508 *

   509 */

   510 	IMPORT_C virtual void UpdateSettingL();

   511 

   512 

   513 /**

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

   515 *

   516 */

   517 	IMPORT_C virtual void RestoreOriginalSettingL();

   518 

   519 /**

   520  * Framework method to set the validity of the data

   521  * This is called when the data changes.

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

   523  *

   524  */

   525 	IMPORT_C virtual void CheckAndSetDataValidity();

   526 

   527 /** 

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

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

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

   531  * purposes.

   532  */

   533 	IMPORT_C virtual void UpdateCbaL();

   534 

   535 /**

   536  * Reserved methods for CAknSettingPage hierarchy

   537  */ 

   538 private: 

   539 	IMPORT_C virtual void CAknSettingPage_Reserved_1();

   540 	IMPORT_C virtual void CAknSettingPage_Reserved_2();

   541 

   542 

   543 

   544 //

   545 // From MEikControlObserver

   546 //

   547 

   548 protected:

   549 

   550 /**

   551  * From MCoeControlObserver:

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

   553  * 

   554  * The implementation of this class is trivial and should be able to be

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

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

   557  *

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

   559  * @param	aEventType	The type of control event 

   560  */

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

   562 

   563 //

   564 // From CCoeControl

   565 //

   566 protected:

   567 

   568 /**

   569 * From CCoeControl

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

   571 * layout code. 

   572 *

   573 */

   574 	IMPORT_C virtual void SizeChanged();

   575 

   576 

   577 /**

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

   579  * Does nothing in release mode.

   580  * Designed to be overidden and base called by subclasses.

   581  *

   582  * @param	aWriteSteam		A connected write stream

   583  */	

   584 	IMPORT_C virtual void WriteInternalStateL(RWriteStream& aWriteStream) const;

   585 

   586 private: 

   587 /**

   588  *	Reserved method derived from CCoeControl

   589  */

   590 	IMPORT_C virtual void Reserved_2();

   591 

   592 private:

   593     /**

   594     * From CAknControl

   595     */

   596     IMPORT_C void* ExtensionInterface( TUid aInterface );

   597 

   598 private:

   599 

   600 /**

   601  * Reserved method from CAknEdwinSettingPage

   602  *

   603  */

   604 	IMPORT_C virtual void CAknEdwinSettingPage_Reserved_1();

   605 

   606 private:

   607 	TInt iBackupValue;

   608 	TInt& iValue;

   609 	TInt iIntegerSettingPageFlags;

   610 	TInt iSpare_1; 

   611 };

   612 

   613 

   614 #endif